This file is where you can specify some of the very basics of BDisk building. It allows you to specify/define certain variables and settings used by the build process. It uses https://docs.python.org/3/library/configparser.html[ConfigParser^] for the parsing engine, and you can do some https://wiki.python.org/moin/ConfigParserExamples[more advanced^] things with it than I demonstrate in the default.
It's single-level, but divided into "sections". This is unfortunately a limitation of ConfigParser, but it should be easy enough to follow.
Blank lines are ignored, as well as any lines beginning with `#` and `;`. There are some restrictions and recommendations for some values, so be sure to note them when they occur. Variables referencing other values in the `build.ini` are allowed in the format of `${value}` if it's in the same section; otherwise, `${section:value}` can be used.
This section controls some basic branding and information having to do with the end product.
==== `name`
This value is a "basic" name of your project. It's not really shown anywhere end-user visible, but we need a consistent name that follows some highly constrained rules:
. Alphanumeric only
. 8 characters total (or less)
. No whitespace
. ASCII only
. Will be converted to uppercase if it isn't already
==== `uxname`
This value is used for filenames and the like. I highly recommend it be the same as `<<__code_name_code,name>>` (in lowercase) but it doesn't need to be. It also has some rules:
. Alphanumeric only
. No whitespace
. ASCII only
. Will be converted to lowercase if it isn't already
==== `pname`
This string is used for "pretty-printing" of the project name; it should be a more human-readable string.
. *Can* contain whitespace
. *Can* be mixed-case, uppercase, or lowercase
. ASCII only
==== `ver`
The version string. If this isn't specified, we'll try to guess based on the current git commit and tags in `<<__code_basedir_code,build:basedir>>`.
. No whitespace
==== `dev`
The name of the developer or publisher of the ISO, be it an individual or organization. For example, if you are using BDisk to build an install CD for your distro, this would be the name of your distro. The same rules as `<<__code_pname_code,pname>>` apply.
. *Can* contain whitespace
. *Can* be mixed-case, uppercase, or lowercase
. ASCII only
==== `email`
An email address to use for git syncing messages, and/or GPG key generation.
==== `desc`
What this distribution/project is used for.
. *Can* contain whitespace
. *Can* be mixed-case, uppercase, or lowercase
. ASCII only
==== `uri`
What is this project's URI (website, etc.)? Alternatively, your personal site, your company's site, etc.
. Should be a valid URI understood by curl
==== `root_password`
The escaped, salted, hashed string to use for the root user.
Please see <<_passwords,the section on passwords>> for information on this value. In the <<_example,example above>>, the string `$$6$$t92Uvm1ETLocDb1D$$BvI0Sa6CSXxzIKBinIaJHb1gLJWheoXp7WzdideAJN46aChFu3hKg07QaIJNk4dfIJ2ry3tEfo3FRvstKWasg/` is created from the password `test`. I cannot stress this enough, do not use a plaintext password here nor just use a regular `/etc/shadow` file/`crypt(3)` hash here. Read the section. I promise it's short.
==== `user`
*Default: no*
This setting specifies if we should create a regular (non-root) user in the live environment.
NOTE: If enabled, this user has full sudo access.
[options="header"]
|======================
2+^|Accepts (case-insensitive) one of:
^m|yes ^m|no
^m|true ^m|false
^m|1 ^m|0
|======================
=== `[user]`
This section of `build.ini` controls aspects about `bdisk:user`. It is only used if <<__code_user_code,`bdisk:user`>> is enabled.
==== `username`
What username should the user have? Standard *nix username rules apply:
. ASCII only
. 32 characters or less
. Alphanumeric only
. Lowercase only
. No whitespace
. Cannot start with a number
==== `name`
What comment/description/real name should be used for the user? For more information on this, see the https://linux.die.net/man/5/passwd[passwd(5) man page^]'s section on *GECOS*.
. ASCII only
==== `password`
The escaped, salted, hashed string to use for the non-root user.
Please see <<_passwords,the section on passwords>> for information on this value. In the <<_example,example above>>, the string `$$6$$t92Uvm1ETLocDb1D$$BvI0Sa6CSXxzIKBinIaJHb1gLJWheoXp7WzdideAJN46aChFu3hKg07QaIJNk4dfIJ2ry3tEfo3FRvstKWasg/` is created from the password `test`. I cannot stress this enough, do not use a plaintext password here nor just use a regular `/etc/shadow` file/`crypt(3)` hash here. Read the section. I promise it's short.
=== `[build]`
This section controls some aspects about the host and things like filesystem paths, etc.
==== `mirror`
A mirror that hosts the bootstrap tarball. It is *highly* recommended you use an Arch Linux https://wiki.archlinux.org/index.php/Install_from_existing_Linux#Method_A:_Using_the_bootstrap_image_.28recommended.29[bootstrap tarball^] as the build process is highly specialized to this (but <<_bug_reports_feature_requests,patches/feature requests>> are welcome for other built distros). You can find a list of mirrors at the bottom of Arch's https://www.archlinux.org/download/[download page^].
. No whitespace
. Must be accessible remotely/via a WAN-recognized address
. Must be a domain/FQDN only; no paths (those come later!)
==== `mirrorproto`
What protocol should we use for <<_mirror,the mirror>>?
|======================
^s|Must be (case-insensitive) one of: ^.^m|http ^.^m|https ^.^m|ftp
|======================
==== `mirrorpath`
What is the path to the tarball directory on the <<__code_mirror_code,`mirror`>>?
. Must be a complete path (e.g. `/dir1/subdir1/subdir2`)
. No whitespace
==== `mirrorfile`
What is the filename for the tarball found in the path specified in <<__code_mirrorpath_code,`mirrorpath`>>? If left blank, we will use the sha1 <<__code_mirrorchksum_code,checksum>> file to try to guess the most recent file.
==== `mirrorchksum`
The path to a sha1 checksum file of the bootstrap tarball.
. No whitespace
. Must be the full path
. Don't include the mirror domain or protocol
==== `mirrorgpgsig`
*[optional]* +
*default: (no GPG checking done)* +
*requires: <<_optional,_gpg/gnupg_>>* +
*requires: <<__code_gpgkey_code,`gpgkey`>>*
If the bootstrap tarball file has a GPG signature, we can use it for extra checking. If it's blank, GPG checking will be disabled.
If you specify just `.sig` (or use the default and don't specify a <<__code_mirrorfile_code,`mirrorfile`>>), BDisk will try to guess based on the file from the sha1 <<__code_mirrorchksum_code,checksum>> file. Note that this must evaluate to a full URL. (e.g. `${mirrorproto}://${mirror}${mirrorpath}somefile.sig`)
==== `gpgkey`
*requires: <<_optional,_gpg/gnupg_>>*
What is a key ID that should be used to verify/validate the <<__code_mirrorgpgsig_code,`mirrorgpgsig`>>?
. Only used if <<__code_mirrorgpgsig_code,`mirrorgpgsig`>> is set
. Can be in "short" form (e.g. _7F2D434B9741E8AC_) or "full" form (_4AA4767BBC9C4B1D18AE28B77F2D434B9741E8AC_), with or without the _0x_ prefix.
==== `gpgkeyserver`
*default: blank (GNUPG-bundled keyservers)* +
*requires: <<_optional,_gpg/gnupg_>>*
What is a valid keyserver we should use to fetch <<__code_gpgkey_code,`gpgkey`>>?
. Only used if <<__code_mirrorgpgsig_code,`mirrorgpgsig`>> is set
. The default (blank) is probably fine. If you don't specify a personal GPG config, then you'll most likely want to leave this blank.
. If set, make sure it is a valid keyserver URI (e.g. `hkp://keys.gnupg.net`)
==== `gpg`
Should we sign our release files? See the gpg section.
[options="header"]
|======================
2+^|Accepts (case-insensitive) one of:
^m|yes ^m|no
^m|true ^m|false
^m|1 ^m|0
|======================
==== `dlpath`
Where should the release files be saved? Note that many other files are created here as well.
