616 lines
40 KiB
Plaintext
616 lines
40 KiB
Plaintext
= AIF-NG User Manual
|
||
Brent Saner <bts@square-r00t.net>
|
||
v1.1, 2017-05-11
|
||
:doctype: book
|
||
:data-uri:
|
||
:imagesdir: images
|
||
:sectlinks:
|
||
:toc: preamble
|
||
:toc2: left
|
||
:idprefix:
|
||
:toclevels: 7
|
||
|
||
|
||
[preface]
|
||
== Preface
|
||
=== About the Author
|
||
I am a GNU/Linux Systems/Network Administrator/Engineer -- I wear a lot of hats. I have a lot of side projects to keep me busy when I’m not working at _${dayjob}_, mostly to assist in other side projects and become more efficient and proficient at those tasks. “Shaving the yak,” footnote:[See http://catb.org/jargon/html/Y/yak-shaving.html] indeed.
|
||
|
||
I got frustrated at the lack of options for installing Arch from a network or automated deployment environment and decided I needed a tool to do that for me.
|
||
|
||
|
||
=== What is AIF-NG?
|
||
AIF-NG (Arch Installation Framework, Next Generation) is a means to automatically install https://www.archlinux.org/[Arch Linux^]. Think of it as something akin to https://en.wikipedia.org/wiki/Kickstart_(Linux)[Kickstart^].
|
||
|
||
https://github.com/jdodds/aif[AIF^] (classic) was written entirely in bash, required compilation, wasn't flexible enough, and is obsolete/no longer maintained. So I rewrote it in Python3 and give it a more basic yet flexible structure.
|
||
|
||
The client (`aifclient.py`) is a single script and gets its configuration from a combination of an XML file and kernel paramaters (which tell it where to find the former and how to access it).
|
||
|
||
AIF-NG is intended mainly for system administrators but if you find yourself turning up a lot of Arch Linux installations in other environments, you may find it useful.
|
||
|
||
=== What it's Not
|
||
AIF-NG is not intended to be a complete turnup solution. Instead, it's useful to build up from baremetal and configure a system to a point where you can use another management tool (such as https://www.ansible.com/[Ansible^], https://www.chef.io/chef/[Chef^], https://puppet.com/[Puppet^], https://saltstack.com/[SaltStack^], and https://en.wikipedia.org/wiki/List_of_build_automation_software#Configuration_management_tools[others^]).
|
||
|
||
Though if you're really gung-ho about it, I suppose you could use the post-script feature to fully turn up a box.
|
||
|
||
It is also not a magic bullet. It will not make an Arch Linux installation *easier*, nor is it designed to do that. Don't file bug reports for this. It's designed to make it *faster*. I recommend you follow the https://wiki.archlinux.org/index.php/installation_guide[manual installation process^] several times first so you're comfortable with the process and understand what's happening behind the scenes. (If you find it too hard to understand, you may be interested in https://antergos.com/[Antergos^] instead.)
|
||
|
||
=== Copyright/Licensing
|
||
The AIF-NG code is https://www.gnu.org/licenses/gpl-3.0.en.html[GPLv3-licensed^]. This means that you can use it for business reasons, personal reasons, modify it, etc. Please be sure to familiarize yourself with the full set of terms. You can find the full license in `docs/LICENSE`.
|
||
|
||
image::https://www.gnu.org/graphics/gplv3-127x51.png[GPLv3,align="center"]
|
||
|
||
This document, and all other associated author-generated documentation, are released under the http://creativecommons.org/licenses/by-sa/4.0/[Creative Commons CC-BY-SA 4.0^] copyright. It's essentially the GPL for non-software, so similar terms apply.
|
||
|
||
image::https://i.creativecommons.org/l/by-sa/4.0/88x31.png[CC-BY-SA_4.0,align="center"]
|
||
|
||
|
||
= Getting Started
|
||
|
||
== Downloading
|
||
If it isn't in your distro's repositories (It *is* in Arch's AUR! Both https://aur.archlinux.org/packages/aif/[tagged release^] and https://aur.archlinux.org/packages/aif-git/[git master^].), you can still easily get rolling. Simply visit the project's https://git.square-r00t.net/AIF-NG/[source code web interface^] and download a tarball under the *Download* column:
|
||
|
||
image::fig1.1.png[cgit,align="center"]
|
||
|
||
If you know the tag of the commit you want, you can use curl:
|
||
|
||
curl -sL -o aif.tar.xz https://git.square-r00t.net/AIF-NG/snapshot/AIF-NG-0.01-BETA.tar.xz
|
||
|
||
or wget:
|
||
|
||
wget -O aif.tar.xz https://git.square-r00t.net/AIF-NG/snapshot/AIF-NG-0.01-BETA.tar.xz
|
||
|
||
You can use `https://git.square-r00t.net/AIF-NG/snapshot/AIF-NG-master.tar.xz` for the URL if you want the latest working version. If you want a snapshot of a specific commit, you can use e.g. `https://git.square-r00t.net/AIF-NG/snapshot/AIF-NG-0e3b4572f9bc460741fe5cd3108b22fad89bfc71.tar.xz` and so on.
|
||
|
||
Alternatively, you can use https://git-scm.com/[git^]. Git most definitely _should_ be in your distro's repositories.
|
||
|
||
TIP: If you're new to git and want to learn more, I highly recommend the book https://git-scm.com/book/en/v2[Pro Git^]. It is available for free download (or online reading).
|
||
|
||
You can clone via https:
|
||
|
||
git clone https://git.square-r00t.net/AIF-NG
|
||
|
||
or native git protocol:
|
||
|
||
git clone git://git.square-r00t.net/aif-ng.git AIF-NG
|
||
|
||
The git protocol is much faster, but at a cost of lessened security.
|
||
|
||
NOTE: I also have a mirror at https://github.com/johnnybubonic/aif-ng[GitHub^], but I don't like GitHub very much and since it's a mirror repository, it's possible it will be out of date. For this reason, it's recommended that you use the resources above.
|
||
|
||
== Prerequisites
|
||
This is a list of software you'll need available to use the AIF-NG client.
|
||
|
||
TIP: Your distro's package manager should have most if not all of these available, so it's unlikely you'll need to install from source.
|
||
|
||
NOTE: Some versions may be higher than actually needed.
|
||
|
||
////
|
||
Need to revamp. Recommended vs. fallback plus required for both
|
||
|
||
Recommended:
|
||
pygobject-introspection
|
||
libblockdev
|
||
libnm
|
||
////
|
||
|
||
=== Necessary
|
||
These are needed for using AIF-NG.
|
||
|
||
* https://www.python.org/[Python^] (>=3.6)
|
||
* http://www.rodsbooks.com/gdisk/sgdisk.html[sgdisk^]
|
||
* https://www.gnu.org/software/parted/[parted^]
|
||
* https://www.archlinux.org/packages/?name=arch-install-scripts[arch-install-scripts^] (for `pacstrap`)
|
||
** https://wiki.archlinux.org/index.php/Install_from_existing_Linux#From_a_host_running_another_Linux_distribution[This^] has some useful methods of installing them in a non-Arch Linux distro.
|
||
|
||
These are no required Python modules, at least for the client; it will work fine with just the standard library for Python 3.
|
||
|
||
=== Optional
|
||
While not strictly necessary, these will greatly enhance your AIF-NG usage. I've included some reasons why you might want to install them.
|
||
|
||
Python modules:
|
||
|
||
* http://lxml.de/[LXML^]
|
||
** Recommended for more complete XML processing, the `aifverify.py` utility, etc.
|
||
|
||
|
||
= Starting an Install
|
||
First, `aifclient.py` (`/usr/bin/aifclient` in AUR packages) must be configured to start at boot after networking has initiated in the host environment. This can be done very easily with a https://www.freedesktop.org/software/systemd/man/systemd.service.html[oneshot^] https://wiki.archlinux.org/index.php/systemd#Writing_unit_files[systemd unit file^].
|
||
|
||
However, this will do nothing on its own. This is a security measure; you can very easily destroy the host's installation if you attempt to run AIF-NG with an inappropriate configuration. For this reason, AIF-NG will exit if it is not enabled via the https://wiki.archlinux.org/index.php/Kernel_parameters[kernel commandline/boot parameters^] (https://wiki.archlinux.org/index.php/Mkinitcpio#HOOKS[mkinitcpio hooks^] may be provided in future updates to the AUR packages to assist in creating more lightweight install environments).
|
||
|
||
Configure your bootloader to add the following options as necessary:
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Parameter ^|Purpose
|
||
^m|aif |This enables AIF-NG; without this, a run will never be initiated -- note that `aif` and `aif=True` are the same, and it can be explicitly disabled by setting `aif=False`
|
||
^m|aif_url |The URI to your <<writing_an_xml_configuration_file, XML configuration file>> (see <<aif_url, below>>)
|
||
^m|aif_auth |(see <<aif_url, below>>)
|
||
^m|aif_username |(see <<aif_url, below>>)
|
||
^m|aif_password |(see <<aif_url, below>>)
|
||
^m|aif_realm |(see <<aif_url, below>>)
|
||
|======================
|
||
|
||
[[aif_url]]
|
||
== Some notes on auth and URIs
|
||
* `aif_url` can be an HTTP/HTTPS URL, an FTP/FTPS URI, or a `file://` URI. e.g.:
|
||
** `aif_url=http://aif.square-r00t.net/aif.xml`
|
||
** `aif_url=https://aif.square-r00t.net/aif.xml`
|
||
** `aif_url=ftp://ftp.domain.tld/bootstrap/aif.xml`
|
||
** `aif_url=ftps://secure.ftp.domain.tld/bootstrap/aif.xml`
|
||
** `aif_url=file:///srv/aif/aif.xml`
|
||
* If `aif_url` is an HTTP/HTTPS URL, then `aif_user` is the username to use with the https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_errors[401^] (https://tools.ietf.org/html/rfc7235[RFC 7235^]) auth (via `aif_auth`).
|
||
** If `aif_url` is an FTP/FTPS URI, then `aif_user` will be the FTP user.
|
||
** The same behavior applies for `aif_password`.
|
||
* If `aif_auth` is `digest`, this is the realm we would use (we attempt to "guess" if it isn’t specified); otherwise it is ignored.
|
||
|
||
== Building a compatible LiveCD
|
||
The default Arch install CD does not have AIF installed (hopefully, this will change someday). You have two options for using AIF-NG.
|
||
|
||
=== Recommended
|
||
The recommended option is to use https://bdisk.square-r00t.net/[BDisk^] (the author should look familiar ;) and per https://bdisk.square-r00t.net/#advanced_customization[the documentation^], you would simply create the following modifications (remember to replace *<BDisk directory>* with your actual BDisk directory):
|
||
|
||
. `mkdir -p *<BDisk directory>*/overlay/etc/systemd/system/multi-target.wants`
|
||
. `ln -s /etc/systemd/system/aif.service *<BDisk directory>*/overlay/etc/systemd/system/multi-target.wants/aif.service`
|
||
.. (NOTE: This is not a typo; the symlink will resolve to the correct place during the build)
|
||
. `printf '[Unit]\nDescription=AIF-NG Client Service\nAfter=livecdfix.service\n\n[Service]\nType=oneshot\nExecStart=/usr/bin/aif\n\n[Install]\nWantedBy=multi-user.target\n' > *<BDisk directory>*/overlay/etc/systemd/system/aif.service`
|
||
.. (NOTE: This is all one line.)
|
||
.. (NOTE: We use a custom aif.service instead of the AUR package provided one because of how BDisk handles bringing up the network.)
|
||
. `echo "aif-git" > *<BDisk directory>*/extra/pre-build.d/root/packages.both`
|
||
. If you want automatic root login on TTY1 like the Arch install ISO (optional):
|
||
.. `mkdir -p *<BDisk directory>*/overlay/etc/systemd/system/getty\@tty1.service.d`
|
||
.. `printf '[Service]\nType=idle\nExecStart=\nExecStart=-/usr/bin/agetty --autologin root --noclear %%I 38400 linux\n' > *<BDisk directory>*/overlay/etc/systemd/system/getty\@tty1.service.d/autologin.conf`
|
||
... (NOTE: This is all one line.)
|
||
|
||
Remember to also create a https://bdisk.square-r00t.net/#the_code_build_ini_code_file[build.ini file^]. You can find a compatible one https://git.square-r00t.net/AIF-NG/plain/extras/bdisk.build.ini[here^] (but remember to tailor it to your particular paths and needs first!).
|
||
|
||
Make any further customizations as you wish, then https://bdisk.square-r00t.net/#building_a_bdisk_iso[start the build^].
|
||
|
||
=== Quickest
|
||
For convenience, I've already built a LiveCD that will auto-start AIF. Note, however, that it is configured to my personal preferences (it installs https://aif.square-r00t.net/cfgs/scripts/pkg/python.sh[python3^], installs https://aif.square-r00t.net/cfgs/scripts/pkg/apacman.py[apacman^] (and configures it and pacman to my tastes), sets up a more strict https://aif.square-r00t.net/cfgs/scripts/post/sshsecure.py[SSH configuration^], and https://aif.square-r00t.net/cfgs/scripts/post/sshkeys.py[installs my SSH pubkeys^].), so you may want to use the recommended method above instead.
|
||
|
||
==== The full environment
|
||
A full ISO build is https://aif.square-r00t.net/download/aif.iso[here] (GPG signatures are available in https://aif.square-r00t.net/download/aif.iso.sig[SIG] and https://aif.square-r00t.net/download/aif.iso.asc[ASC^] format; make sure you https://devblog.square-r00t.net/about/my-gpg-public-key-verification-of-identity[verify it^]).
|
||
|
||
It has a full GNU/Linux environment that you can use, and works on both UEFI and BIOS systems. It boots to a non-passworded root login, but AIF will be running in the background. SSH is installed and configured for key-based authentication only, but is not enabled by default.
|
||
|
||
==== The iPXE environment
|
||
If you would like to boot over the network, I have an iPXE ISO https://aif.square-r00t.net/download/aif-mini.iso[here] (GPG signatures are available in https://aif.square-r00t.net/download/aif-mini.iso.sig[SIG] and https://aif.square-r00t.net/download/aif-mini.iso.asc[ASC^] format; make sure you https://devblog.square-r00t.net/about/my-gpg-public-key-verification-of-identity[verify it^]).
|
||
|
||
You will need at least 2GB of RAM, as it loads entirely into memory.
|
||
|
||
It also boots to a full GNU/Linux environment that you can use, and works on both UEFI and BIOS systems. It boots to a non-passworded root login, but AIF will be running in the background. SSH is installed and configured for key-based authentication only, but is not enabled by default.
|
||
|
||
|
||
|
||
== Logging
|
||
Currently, only one method of logging is enabled, and is always enabled. It can be found on the host and guest at */root/aif.log._<UNIX epoch timestamp>_*. Note that after the build finishes successfully, it will remove the host's log (as it's just a broken symlink at that point). You will be able to find the full log in the guest after the install, however.
|
||
|
||
== Debugging
|
||
Sometimes it's useful to get a little more information, or to start an installation from within an already-booted environment and you didn't remember (or weren't able to) change the kernel parameters. If this is the case, simply export the `DEBUG` environment variable (it can be set to anything, it doesn't matter) -- if this is done, the arguments will be read from /tmp/cmdline instead. e.g.:
|
||
|
||
export DEBUG=true
|
||
cp /proc/cmdline /tmp/.
|
||
chmod 600 /tmp/cmdline
|
||
sed -i -e '1s/$/ aif aif_url=https:\/\/aif.square-r00t.net\/aif.xml/' /tmp/cmdline
|
||
|
||
It will also write the full configuration (*after* parsing) to the <<logging, logfile>>.
|
||
|
||
= Writing an XML Configuration File
|
||
I've included a sample `aif.xml` file with the project which is fully functional. However, it's not ideal -- namely because it will add my personal SSH pubkeys to your new install, and you probably don't want that. However, it's fairly complete so it should serve as a good example. If you want to see the full set of supported configuration elements, take a look at the most up-to-date https://aif.square-r00t.net/aif.xsd[aif.xsd^]. For explanation's sake, however, we'll go through it here. The directives are referred to in https://www.w3schools.com/xml/xml_xpath.asp[XPath^] syntax within the documentation text for easier context (but not the titles).
|
||
|
||
== `<aif>`
|
||
The `/aif` element is the https://en.wikipedia.org/wiki/Root_element[root element^]. It serves as a container for all the configuration data. The only http://www.xmlfiles.com/xml/xml_attributes.asp[attributes^] it contains are for formatting and verification of the containing XML.
|
||
|
||
=== `<storage>`
|
||
The `/aif/storage` element contains <<code_disk_code, disk>>, <<code_part_code, disk/part>>, and <<code_mount_code, mount>> elements.
|
||
|
||
==== `<disk>`
|
||
The `/aif/storage/disk` element holds information about disks on the system, and within this element are one (or more) <<code_part_code, part>> elements. Note that any `disk` elements specified here will be *entirely reformatted*; operate under the assumption that ANY and ALL pre-existing data on the specified device will be IRREVOCABLY LOST.
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|device |The disk to format (e.g. `/dev/sda`)
|
||
^m|diskfmt |https://en.wikipedia.org/wiki/GUID_Partition_Table[`gpt`^] or https://en.wikipedia.org/wiki/Master_boot_record[`msdos`^]
|
||
|======================
|
||
|
||
===== `<part>`
|
||
The `/aif/storage/disk/part` element holds information on partitioning that it's parent <<code_disk_code, disk>> element should have.
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|num |The partition number (positive integer)
|
||
^m|start |The amount of the *total disk size* to _start_ the partition at (see <<specialsize, below>>)
|
||
^m|stop |The amount of the *total disk size* to _end_ the partition at (see <<specialsize, below>>)
|
||
^m|fstype |The partition type. Must be in http://www.rodsbooks.com/gdisk/cgdisk-walkthrough.html[gdisk format^] (see <<fstypes, below>>)
|
||
|======================
|
||
|
||
[[specialsize]]
|
||
The `start` and `stop` attributes can be in the form of:
|
||
|
||
* A percentage of the total disk size, indicated by a percentage sign (`"10%"`)
|
||
* A size, indicated by the abbreviation (`"300KiB"`, `"10GB"`, etc.)
|
||
** Accepts notation in https://en.wikipedia.org/wiki/Binary_prefix[SI or IEC formats^]
|
||
* A raw sector size, if no suffix is provided (sector sizes are *typically* 512 bytes but this can vary depending on disk) (`1024`)
|
||
* One can also specify modifiers (`"+10%"`, `"-400MB"`, etc.). A positive modifier indicates from the beginning of the *start of the disk* and a negative modifier specifies from the *end of the disk* (the default, if none is specified, is to use the _previously defined partition's end_ as the *start* for the new partition, or to use the _beginning of the usable disk space_ as the *start* if no previous partition is specified, and to *add* the size to the *start* until the *stop* is reached)
|
||
|
||
[[fstypes]]
|
||
NOTE: The following is a table for your reference of partition types. Note that it may be out of date, so reference the link above for the most up-to-date table.
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|fstype ^|Formatting type
|
||
^m|0700 |Microsoft basic data
|
||
^m|0c01 |Microsoft reserved
|
||
^m|2700 |Windows RE
|
||
^m|3000 |ONIE config
|
||
^m|3900 |Plan 9
|
||
^m|4100 |PowerPC PReP boot
|
||
^m|4200 |Windows LDM data
|
||
^m|4201 |Windows LDM metadata
|
||
^m|4202 |Windows Storage Spaces
|
||
^m|7501 |IBM GPFS
|
||
^m|7f00 |ChromeOS kernel
|
||
^m|7f01 |ChromeOS root
|
||
^m|7f02 |ChromeOS reserved
|
||
^m|8200 |Linux swap
|
||
^m|8300 |Linux filesystem
|
||
^m|8301 |Linux reserved
|
||
^m|8302 |Linux /home
|
||
^m|8303 |Linux x86 root (/)
|
||
^m|8304 |Linux x86-64 root (/
|
||
^m|8305 |Linux ARM64 root (/)
|
||
^m|8306 |Linux /srv
|
||
^m|8307 |Linux ARM32 root (/)
|
||
^m|8400 |Intel Rapid Start
|
||
^m|8e00 |Linux LVM
|
||
^m|a500 |FreeBSD disklabel
|
||
^m|a501 |FreeBSD boot
|
||
^m|a502 |FreeBSD swap
|
||
^m|a503 |FreeBSD UFS
|
||
^m|a504 |FreeBSD ZFS
|
||
^m|a505 |FreeBSD Vinum/RAID
|
||
^m|a580 |Midnight BSD data
|
||
^m|a581 |Midnight BSD boot
|
||
^m|a582 |Midnight BSD swap
|
||
^m|a583 |Midnight BSD UFS
|
||
^m|a584 |Midnight BSD ZFS
|
||
^m|a585 |Midnight BSD Vinum
|
||
^m|a600 |OpenBSD disklabel
|
||
^m|a800 |Apple UFS
|
||
^m|a901 |NetBSD swap
|
||
^m|a902 |NetBSD FFS
|
||
^m|a903 |NetBSD LFS
|
||
^m|a904 |NetBSD concatenated
|
||
^m|a905 |NetBSD encrypted
|
||
^m|a906 |NetBSD RAID
|
||
^m|ab00 |Recovery HD
|
||
^m|af00 |Apple HFS/HFS+
|
||
^m|af01 |Apple RAID
|
||
^m|af02 |Apple RAID offline
|
||
^m|af03 |Apple label
|
||
^m|af04 |AppleTV recovery
|
||
^m|af05 |Apple Core Storage
|
||
^m|bc00 |Acronis Secure Zone
|
||
^m|be00 |Solaris boot
|
||
^m|bf00 |Solaris root
|
||
^m|bf01 |Solaris /usr & Mac ZFS
|
||
^m|bf02 |Solaris swap
|
||
^m|bf03 |Solaris backup
|
||
^m|bf04 |Solaris /var
|
||
^m|bf05 |Solaris /home
|
||
^m|bf06 |Solaris alternate sector
|
||
^m|bf07 |Solaris Reserved 1
|
||
^m|bf08 |Solaris Reserved 2
|
||
^m|bf09 |Solaris Reserved 3
|
||
^m|bf0a |Solaris Reserved 4
|
||
^m|bf0b |Solaris Reserved 5
|
||
^m|c001 |HP-UX data
|
||
^m|c002 |HP-UX service
|
||
^m|ea00 |Freedesktop $BOOT
|
||
^m|eb00 |Haiku BFS
|
||
^m|ed00 |Sony system partition
|
||
^m|ed01 |Lenovo system partition
|
||
^m|ef00 |EFI System
|
||
^m|ef01 |MBR partition scheme
|
||
^m|ef02 |BIOS boot partition
|
||
^m|f800 |Ceph OSD
|
||
^m|f801 |Ceph dm-crypt OSD
|
||
^m|f802 |Ceph journal
|
||
^m|f803 |Ceph dm-crypt journal
|
||
^m|f804 |Ceph disk in creation
|
||
^m|f805 |Ceph dm-crypt disk in creation
|
||
^m|fb00 |VMWare VMFS
|
||
^m|fb01 |VMWare reserved
|
||
^m|fc00 |VMWare kcore crash protection
|
||
^m|fd00 |Linux RAID
|
||
|======================
|
||
|
||
NOTE: Automatic formatting is currently only enabled for the following (subject to further configuration in later versions):
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|fstype ^|Formatted as
|
||
^m|ef00 |vFAT32 (mkfs.vfat -F 32)
|
||
^m|ef01 ^|"
|
||
^m|ef02 ^|"
|
||
^m|8200 |GNU/Linux swap (mkswap)
|
||
^m|8300 |ext4
|
||
^m|8301 ^|"
|
||
^m|8302 ^|"
|
||
^m|8303 ^|"
|
||
^m|8304 ^|"
|
||
^m|8305 ^|"
|
||
^m|8306 ^|"
|
||
^m|8307 ^|"
|
||
|======================
|
||
|
||
==== `<mount>`
|
||
The `/aif/storage/mount` element specifies mountpoints for each <<code_disk_code, disk>>'s <<code_part_code, partition>>.
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|source |The device to mount
|
||
^m|target |Where it should be mounted to in the filesystem (on the host system, not the new installation); if `swap`, it will be handled as swapspace instead
|
||
^m|order |The order in which it should be mounted. These should be unique positive integers.
|
||
^m|fstype |The filesystem type; usually this is not required but if you need to manually specify the type of filesystem, this will allow you to do it
|
||
^m|opts |The mount options; provide the string exactly as it would be provided to mount(8)'s `-o` option
|
||
|======================
|
||
|
||
=== `<network>`
|
||
The `/aif/network` element specifies network configuration(s). It contains <<code_iface_code, iface>> ("interface") elements.
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|hostname |The hostname of the new installation
|
||
|======================
|
||
|
||
==== `<iface>`
|
||
The `/aif/network/iface` element specifies various <<code_network_code, network>> configurations. Currently only ethernet is supported, and only limited support for IPv6 is available (but future improvements/flexible capabilities are planned).
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|device |The interface name (in https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/[Predictable Interface Naming^]) (e.g. `ens3`); can be `auto` (see below)
|
||
^m|address |The address to be assigned to the interface (in https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing[CIDR^] format); can be `auto` (see below)
|
||
^m|netproto |One of `ipv4`, `ipv6`, or `both`
|
||
^m|gateway |The gateway address for the interface/protocol pairing; only used if `address` is not `auto`
|
||
^m|resolvers |The DNS resolver addresses, if you wish/need to manually specify them; pass as a comma-separated list
|
||
|======================
|
||
|
||
If "auto" is specified for `device`, the system will configure the first (and *only* the first) interface it finds with an active link with the provided address information.
|
||
|
||
If "auto" is specified for `address`, then DHCP (or https://en.wikipedia.org/wiki/DHCPv6[DHCPv6], depending on the configuration of `netproto`).
|
||
|
||
NOTE: Setting `netproto` to "both" is really only useful if "auto" is specified for `address`.
|
||
|
||
=== `<system>`
|
||
The `/aif/system` element is for handling general system configuration. It contains the <<code_users_code, users>>, <<code_user_code, users/user>>, <<code_home_code, users/user/home>>, <<code_xgroup_code, users/user/xgroup>>, and <<code_service_code, service>> elements.
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|timezone |The https://wiki.archlinux.org/index.php/Time#Time_zone[timezone^] for the installed system (can be independent of the host system)
|
||
^m|locale |The https://wiki.archlinux.org/index.php/Locale#Setting_the_system_locale[locale^] of the installed system (e.g. `en_US.UTF-8`); if a short version is used (e.g. `en`), then all locales starting with that prefix will be enabled (multiple explicit locale support is in the TODO)
|
||
^m|chrootpath |The path on the host that will serve as the https://wiki.archlinux.org/index.php/Change_root[chroot^] path. This should be where your new install's / (root filesystem partition) is mounted at in <<code_mount_code, mounts>>
|
||
^m|kbd |The https://wiki.archlinux.org/index.php/installation_guide#Set_the_keyboard_layout[keyboard layout^] (if not US)
|
||
^m|reboot |If we should reboot the system after the install (in order to boot to the newly-installed system, assuming your boot order is set correctly). Boolean, accepts `1`/`true` or `0`/`false`.
|
||
|======================
|
||
|
||
==== `<users>`
|
||
The `/aif/system/users` element is used to specify users you wish to create (if any). It contains the <<code_user_code, user>>, <<code_home_code, user/home>>, and <<code_xgroup_code, user/xgroup>> elements.
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|rootpass |A properly hashed-and-salted password. See <<passwordhashes, below>>
|
||
|======================
|
||
|
||
[[passwordhashes]]
|
||
NOTE: To generate a proper hashed/salted password, you may want to reference https://bdisk.square-r00t.net/#generating_a_password_salt_hash[this section^] from https://bdisk.square-r00t.net/[BDisk^]'s user manual (another project of mine). You can use https://git.square-r00t.net/BDisk/tree/extra/bin/hashgen.py[this python script^] to generate one. If you specify an empty string, the password will be BLANK (i.e. you can log in with just the username). This is very insecure. If you specify a `!` instead of a salted hash, TTY login will be disabled (though it will still be possible to log in via other means such as SSH pubkey auth -- assuming you configure it beforehand. This has some *added* security benefits).
|
||
|
||
===== `<user>`
|
||
The `/aif/system/users/user` element specifies user(s) to create. It contains <<code_xgroup_code, xgroup>> and <<code_home_code, home>> elements.
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|name |The username/login name
|
||
^m|sudo |If (full) sudo access should be granted to this user (boolean; must be one of `1`/`true` or `0`/`false`)
|
||
^m|password |The salted/hashed password (see <<passwordhashes, above>>)
|
||
^m|comment |A comment (typically, the user's real/full name)
|
||
^m|uid |The https://en.wikipedia.org/wiki/User_identifier[UID^] of the user; if specified, must be a positive integer
|
||
^m|group |The primary group of the user (the default is to create a new group named after that user)
|
||
^m|gid |The https://en.wikipedia.org/wiki/Group_identifier[GID^] to use for the primary group; must be a positive integer
|
||
|======================
|
||
|
||
====== `<xgroup>`
|
||
The `/aif/system/users/user/xgroup` elements specifies one (or more) "eXtra groups" (i.e. non-primary) that AIF-NG should add the user to.
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|name |The group name
|
||
^m|create |If the group should be created (boolean; must be one of `1`/`true` or `0`/`false`)
|
||
^m|gid |The https://en.wikipedia.org/wiki/Group_identifier[GID^] to use (if creating); must be a positive integer and not be taken by an existing group
|
||
|======================
|
||
|
||
====== `<home>`
|
||
The `/aif/system/users/user/home` element contains information for a <<code_user_code, user>>'s home directory. It can be only specified once per user, but it is optional.
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|path |The path for the home directory; useful if you don't want it to be /home/<username>
|
||
^m|create |If the home directory should be created (boolean; must be one of `1`/`true` or `0`/`false`)
|
||
|======================
|
||
|
||
==== `<service>`
|
||
The `/aif/system/service` element holds information about services that should explicitly be enabled/disabled on boot.
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|name |The service name. It can be shortform (`sshd`) or long form (`git-daemon.socket`); if the shortform is provided, ".service" is assumed
|
||
^m|status |A boolean that specifies if the service should be enabled (`1`/`true`) or disabled (`0`/`false`)
|
||
|======================
|
||
|
||
=== `<pacman>`
|
||
The `/aif/pacman` element contains the <<code_repos_code, repos>>, <<code_repo_code, repos/repo>>, <<code_mirrorlist_code, mirrorlist>>, <<code_mirror_code, mirrorlist/mirror>>, <<code_software_code, software>>, and <<code_package_code, software/packages>> elements.
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|command |The command to use to install a package
|
||
|======================
|
||
|
||
[[command]]
|
||
If you configured an alternate package utility (using a `execution="pkg"` <<code_script_code, script>> entry), you can specify the command here. Note that it should be configured/called with necessary options to avoid the necessity of user involvement (since that's the entire point of AIF-NG). e.g.:
|
||
|
||
<aif ... >
|
||
...
|
||
<pacman command="apacman --needed --noconfirm --noedit --skipinteg -S">
|
||
...
|
||
</aif>
|
||
|
||
==== `<repos>`
|
||
The `/aif/pacman/repos` element contains one (or more) <<code_repo_code, repo>> element(s).
|
||
|
||
===== `<repo>`
|
||
The `/aif/pacman/repos/repo` elements specify information for configuring the installed system's /etc/pacman.conf (specifically, the repositories).
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|name |The name of the repository
|
||
^m|enabled |A boolean that specifies if the repository should be enabled (`1`/`true`) or disabled (`0`/`false`)
|
||
^m|siglevel |The https://wiki.archlinux.org/index.php/pacman#Package_security[siglevel^] of the repository (e.g. `Optional TrustedOnly`); can be `default` (in which the pacman.conf default siglevel will be used)
|
||
^m|mirror |The URI for the https://wiki.archlinux.org/index.php/pacman#Repositories_and_mirrors[mirror^]; if it begins with `file://`, we will use it as an `Include =` instead of a `Server =` (make sure it is a full/absolute path and it exists on the newly installed system)
|
||
|======================
|
||
|
||
===== `<mirrorlist>`
|
||
The `/aif/pacman/mirrorlist` element contains elements that should be in `/etc/pacman.d/mirrorlist`. It is optional; if it isn't specified, the default distributed mirrorlist will be used instead.
|
||
|
||
====== `<mirror>`
|
||
The `/aif/pacman/mirrorlist/mirror` elements are <<code_mirrorlist_code, mirrorlist>> entries.
|
||
|
||
===== `<software>`
|
||
The `/aif/pacman/software` element contains one (or more) <<code_package_code, package>> element(s) that describe software to install. It is optional.
|
||
|
||
====== `<package>`
|
||
The `/aif/pacman/software/package` element holds information about software to be installed.
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|name |The name of the package (e.g. `openssh`)
|
||
^m|repo |Optional, but you can specify which repository to install the package from (in the case of multiple repositories providing the same package)
|
||
|======================
|
||
|
||
=== `<bootloader>`
|
||
The `/aif/bootloader` element specifies a https://wiki.archlinux.org/index.php/installation_guide#Boot_loader[bootloader^] to install.
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|type |The bootloader to use; currently, the only supported values are `grub` and `systemd` (for https://wiki.archlinux.org/index.php/Systemd-boot[systemd-boot^]) but more options may be available in the future
|
||
^m|efi |If used for (U)EFI support; note that the install environment must be booted in UEFI mode and that `systemd`(-boot) only supports EFI and that it is a boolean (`1`/`true` or `0`/`false`)
|
||
^m|target |This should be the absolute path (from within the newly installed system) to your https://wiki.archlinux.org/index.php/EFI_System_Partition[ESP^] (if `efi` is true); otherwise the disk/partition to install the bootloader to (if you're using BIOS mode)
|
||
|======================
|
||
|
||
=== `<scripts>`
|
||
The `/aif/scripts` element contains one or more <<code_script_code, script>> elements.
|
||
|
||
==== `<script>`
|
||
The `/aif/scripts/script` elements specify scripts to be run at different stages during the install process. This is useful if you need to set up SSH pubkey authentication, for example, or configure https://wiki.archlinux.org/index.php/RAID[mdadm^] so you can use that as a <<code_disk_code, disk>>.
|
||
|
||
[options="header"]
|
||
|======================
|
||
^|Attribute ^|Value
|
||
^m|uri |The URI to the script; can be an HTTP/HTTPS reference, an FTP/FTPS reference, or a local file reference (`\file:///path/to/file`).
|
||
^m|order |A unique positive integer used to order the scripts during the run; note that e.g. pre- and post-scripts are executed at different points, so you can use the same `order` as long as it's in different execution points
|
||
^m|authtype |Same behavior as <<starting_an_install, `aif_auth`>> but for fetching this script (see also <<aif_url, further notes>> on this)
|
||
^m|user |Same behavior as <<starting_an_install, `aif_user`>> but for fetching this script (see also <<aif_url, further notes>> on this)
|
||
^m|password |Same behavior as <<starting_an_install, `aif_password`>> but for fetching this script (see also <<aif_url, further notes>> on this)
|
||
^m|realm |Same behavior as <<starting_an_install, `aif_realm`>> but for fetching this script (see also <<aif_url, further notes>> on this)
|
||
^m|execution |(see <<script_types, below>>)
|
||
|======================
|
||
|
||
|
||
[[script_types]]
|
||
There are several script types availabe for `execution`. Currently, these are:
|
||
|
||
* pre
|
||
* pkg
|
||
* post
|
||
|
||
*pre* scripts are run (in numerical `order`) before the disks are even formatted. *pkg* scripts are run (in numerical `order`) right before the <<code_package_code, packages>> are installed (this allows you to configure an <<command, alternate packager>> such as https://aur.archlinux.org/packages/apacman/[apacman^]) -- these are run *inside* the chroot of the new install. *post* scripts are run inside the chroot like *pkg*, but are executed very last thing, just before the reboot.
|
||
|
||
= Further Information
|
||
Here you will find further info and other resources relating to AIF-NG.
|
||
|
||
== FAQ
|
||
|
||
=== "I specified start sector as 0 for a GPT-labeled disk but it starts at sector 2048 instead. What gives?"
|
||
GPT requires 33 sectors for the table at the beginning (and 32 sectors at the end) for the actual table. That plus an extra (usually) 512 bytes at the beginning for something called a https://en.wikipedia.org/wiki/GUID_Partition_Table#Protective_MBR_(LBA_0)[Protective MBR^] (this prevents disk utilities from overwriting the GPT label automatically in case they only recognize "msdos" labels and assume the disk is not formatted yet).
|
||
|
||
Most disks these days use something called https://en.wikipedia.org/wiki/Advanced_Format[Advanced Format^]. These align their sectors to factors of 8, so sector 34 can't be used - it'd have to be sector 40. Additionally, various other low-level disk interactions (e.g. RAID stripe sizes) require a much larger boundary between partitions. If you're interested in a little more detail, you may find https://metebalci.com/blog/a-quick-tour-of-guid-partition-table-gpt/[this^] interesting (specifically https://metebalci.com/blog/a-quick-tour-of-guid-partition-table-gpt/#gpt-partition-entry-array[this section^], paragraph starting with `You may also ask why the first partition starts from LBA 2048...`).
|
||
|
||
TL;DR: "It's the safest way to make sure your disk doesn't suffer massive degradation in performance, your RAID doesn't eat partitions, etc." Don't worry, it typically only ends up being about 1MB of "wasted" space surrounding partitions. I've written plaintext documentation larger than 1MB.
|
||
|
||
=== "Why isn't my last GPT partition extending to the last sector?"
|
||
See above.
|
||
|
||
=== "Why do partitions take `start`/`stop` attributes but LVs take `size`?"
|
||
Using `start`/`stop` attributes makes sense for disk partitions because they operate on actual geometry (positions on-disk); that is, this lets you create a "gap" between partitions on the disk which can be helpful if you want to do any modifications to the partition table afterwards (this is also why partitions are processed in the order they're specified).
|
||
|
||
LVM (LVs, in particular), however, aren't consecutive. There *is* no concept of a "start" and "stop" for an LV; LVM uses chunks called "(physical) extents" rather than sectors, and VGs don't have geometry since they're essentially a pool of blocks. This is also why the modifiers like `-` and `+` aren't allowed for LV sizes - they're position-based.
|
||
|
||
=== "Why aren't the network settings in <network> being applied during install?"
|
||
Simply put, a logical race condition. In order for probably 90+% of AIF-NG deploys to bootstrap, they fetch their XML configuration via a network URI (rather than a file URI). This means it needs a network connection that pre-exists in the *install environment* (LiveCD, LiveUSB, PXE/iPXE, etc.) before it even knows what network configuration you want the *persistent environment* to have.
|
||
|
||
Granted, this is a moot point if you're using a *`file://`* URI for the XML configuration, but this is not a very flexible means regardless. If demand increases for this, future releases may include this functionality.
|
||
|
||
If you desire the configuration to be applied *during* the install, you can do it yourself in an `/aif/scripts/pre/script` or `/aif/scripts/pkg/script` script. The fetched XML file can be found at `/var/tmp/AIF.xml` in the install environment. (Alternatively, configure the network yourself procedurally using one of those scripts).
|
||
|
||
If you wish to SSH into the install environment to check the status/progress of the install, it is recommended that you set up a static lease (if using DHCP) or use SLAAC (if using IPv6) beforehand and configure your install environment beforehand. Remember, AIF-NG only *installs* Arch Linux; it tries very hard to *not* interact with the install environment.
|
||
|
||
|
||
== Bug Reports/Feature Requests
|
||
NOTE: It is possible to submit a bug or feature request without registering in my bugtracker. One of my pet peeves is needing to create an account/register on a bugtracker simply to report a bug! The following links only require an email address to file a bug (which is necessary in case I need any further clarification from you or to keep you updated on the status of the bug/feature request -- so please be sure to use a valid email address).
|
||
|
||
=== Bugs
|
||
If you encounter any bugs in *AIF-NG* (for the actual agent), you can file a bug report https://bugs.square-r00t.net/index.php?do=newtask&project=9&task_type=1&https://bugs.square-r00t.net/index.php?do=newtask&project=9&product_category=19[here^].
|
||
|
||
If you encounter any bugs in the *configuration file tool*, you can file a bug report https://bugs.square-r00t.net/index.php?do=newtask&project=9&task_type=1&https://bugs.square-r00t.net/index.php?do=newtask&project=9&product_category=24[here^].
|
||
|
||
If you encounter any bugs (inaccurate information, typos, misformatting, etc.) in *this documentation*, you can file a bug report https://bugs.square-r00t.net/index.php?do=newtask&project=9&task_type=1&product_category=25[here^].
|
||
|
||
=== Feature Requests
|
||
If you have any features you'd like to see or you think would help *AIF-NG* become even more useful, please file a feature request https://bugs.square-r00t.net/index.php?do=newtask&project=9&task_type=2&product_category=19[here^].
|
||
|
||
If you have any features you'd like to see in the *configuration file tool*, you can file a feature requests https://bugs.square-r00t.net/index.php?do=newtask&project=9&task_type=1&https://bugs.square-r00t.net/index.php?do=newtask&project=9&task_type=2product_category=25[here^].
|
||
|
||
If you have any suggestions on how to improve *this documentation* or feel it's missing information that could be useful, please file a feature request https://bugs.square-r00t.net/index.php?do=newtask&project=9&task_type=2&product_category=25[here^].
|
||
|
||
=== Patches
|
||
I gladly welcome https://www.gnu.org/software/diffutils/manual/html_node/Unified-Format.html[patches^], but I deplore using GitHub (even though I https://github.com/johnnybubonic/aif-ng[have a mirror there^]). For this reason, please follow the same https://www.kernel.org/doc/Documentation/process/submitting-patches.rst[patch/pull request process] for the Linux kernel and email it to bts@square-r00t.net.
|
||
|
||
Alternatively, you may attach a patch to a <<bugs,bug report>>/<<feature_requests,feature request>>.
|
||
|
||
== Contact the Author
|
||
If you have any questions, comments, or concerns, you can use the following information to get in touch with me.
|
||
|
||
I am available via mailto:bts@square-r00t.net[email]. If you use GPG, you can find my pubkey and other related info https://devblog.square-r00t.net/about/my-gpg-public-key-verification-of-identity[here^] (and on most keyservers).
|
||
|
||
I occasionally write howto articles, brief tips, and other information in my https://devblog.square-r00t.net[dev blog].
|
||
|
||
I am on IRC as *r00t^2*, and am usually in the irc://irc.freenode.org/#sysadministrivia[Sysadministrivia channel on Freenode]. Which reminds me, I run a podcast called https://sysadministrivia.com[Sysadministrivia^].
|
||
|
||
I am on Twitter as https://twitter.com/brentsaner[@brentsaner^], though I don't tweet very often. (I usually tweet from my https://twitter.com/SysAdm_Podcast[podcast's twitter^].)
|