AIF-NG is a tool to enable unattended Arch Linux installations.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
brent s 7a2e66f1a2
manual update
6 years ago
docs manual update 6 years ago
extras aif-config is... done? 6 years ago
script-samples 15:37:38 < jthan> you should use say, not print. 6 years ago
.gitignore updating gitignore 6 years ago aif-config is... done? 6 years ago
aif.xsd changing size attrib to stop 6 years ago changing size attrib to stop 6 years ago


AIF-NG User Manual


About the Author

I am a GNU/Linux Systems/Network Administrator/EngineerI wear a lot of hats. I have a lot of side projects to keep me busy when Im not working at ${dayjob}, mostly to assist in other side projects and become more efficient and proficient at those tasks. “Shaving the yak,” [1] 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 Arch Linux. Think of it as something akin to Kickstart.

AIF (classic) was written entirely in bash, required compilation, wasnt 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 ( 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 its Not

AIF-NG is not intended to be a complete turnup solution. Instead, its useful to build up from baremetal and configure a system to a point where you can use another management tool (such as Ansible, Chef, Puppet, SaltStack, and others).

Though if youre 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. Dont file bug reports for this. Its designed to make it faster. I recommend you follow the manual installation process several times first so youre comfortable with the process and understand whats happening behind the scenes. (If you find it too hard to understand, you may be interested in Antergos instead.)


The AIF-NG code is 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.


This document, and all other associated author-generated documentation, are released under the Creative Commons CC-BY-SA 4.0 copyright. Its essentially the GPL for non-software, so similar terms apply.


Getting Started


If it isnt in your distros repositories (It is in Archs AUR! Both tagged release and git master.), you can still easily get rolling. Simply visit the projects source code web interface and download a tarball under the Download column:


If you know the tag of the commit you want, you can use curl:

curl -sL -o aif.tar.xz

or wget:

wget -O aif.tar.xz

You can use for the URL if you want the latest working version. If you want a snapshot of a specific commit, you can use e.g. and so on.

Alternatively, you can use git. Git most definitely should be in your distros repositories.

If youre new to git and want to learn more, I highly recommend the book Pro Git. It is available for free download (or online reading).

You can clone via https:

git clone

or native git protocol:

git clone git:// AIF-NG

The git protocol is much faster, but at a cost of lessened security.

I also have a mirror at GitHub, but I dont like GitHub very much and since its a mirror repository, its possible it will be out of date. For this reason, its recommended that you use the resources above.


This is a list of software youll need available to use the AIF-NG client.

Your distros package manager should have most if not all of these available, so its unlikely youll need to install from source.
Some versions may be higher than actually needed.


These are needed for using AIF-NG.

These are no required Python modules, at least for the client; it will work fine with just the standard library for Python 3.


While not strictly necessary, these will greatly enhance your AIF-NG usage. Ive included some reasons why you might want to install them.

Python modules:

  • LXML

    • Recommended for more complete XML processing, the utility, etc.

Starting an Install

First, (/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 oneshot systemd unit file.

However, this will do nothing on its own. This is a security measure; you can very easily destroy the hosts 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 kernel commandline/boot parameters (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:

Parameter Purpose


This enables AIF-NG; without this, a run will never be initiatednote that aif and aif=True are the same, and it can be explicitly disabled by setting aif=False


The URI to your XML configuration file (see below)


(see below)


(see below)


(see below)


(see below)

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=

    • aif_url=

    • 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 401 (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 isnt 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.

The recommended option is to use BDisk (the author should look familiar ;) and per the documentation, you would simply create the following modifications (remember to replace <BDisk directory> with your actual BDisk directory):

  1. mkdir -p <BDisk directory>/overlay/etc/systemd/system/multi-target.wants

  2. ln -s /etc/systemd/system/aif.service <BDisk directory>/overlay/etc/systemd/system/multi-target.wants/aif.service

    1. (NOTE: This is not a typo; the symlink will resolve to the correct place during the build)

  3. printf '[Unit]\nDescription=AIF-NG Client Service\nAfter=livecdfix.service\n\n[Service]\nType=oneshot\nExecStart=/usr/bin/aif\n\n[Install]\\n' > <BDisk directory>/overlay/etc/systemd/system/aif.service

    1. (NOTE: This is all one line.)

    2. (NOTE: We use a custom aif.service instead of the AUR package provided one because of how BDisk handles bringing up the network.)

  4. echo "aif-git" > <BDisk directory>/extra/pre-build.d/root/packages.both

  5. If you want automatic root login on TTY1 like the Arch install ISO (optional):

    1. mkdir -p <BDisk directory>/overlay/etc/systemd/system/getty\@tty1.service.d

    2. 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

      1. (NOTE: This is all one line.)

Remember to also create a build.ini file. You can find a compatible one here (but remember to tailor it to your particular paths and needs first!).

Make any further customizations as you wish, then start the build.


For convenience, Ive already built a LiveCD that will auto-start AIF. Note, however, that it is configured to my personal preferences (it installs python3, installs apacman (and configures it and pacman to my tastes), sets up a more strict SSH configuration, and installs my SSH pubkeys.), so you may want to use the recommended method above instead.

The full environment

A full ISO build is here (GPG signatures are available in SIG and ASC format; make sure you 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 here (GPG signatures are available in SIG and ASC format; make sure you 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.


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 hosts log (as its just a broken symlink at that point). You will be able to find the full log in the guest after the install, however.


Sometimes its useful to get a little more information, or to start an installation from within an already-booted environment and you didnt remember (or werent able to) change the kernel parameters. If this is the case, simply export the DEBUG environment variable (it can be set to anything, it doesnt 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.xml/' /tmp/cmdline

It will also write the full configuration (after parsing) to the logfile.

Writing an XML Configuration File

Ive included a sample aif.xml file with the project which is fully functional. However, its not idealnamely because it will add my personal SSH pubkeys to your new install, and you probably dont want that. However, its 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 aif.xsd. For explanations sake, however, well go through it here. The directives are referred to in XPath syntax within the documentation text for easier context (but not the titles).


The /aif element is the root element. It serves as a container for all the configuration data. The only attributes it contains are for formatting and verification of the containing XML.


The /aif/storage element contains disk, disk/part, and mount elements.


The /aif/storage/disk element holds information about disks on the system, and within this element are one (or more) part elements.

Attribute Value


The disk to format (e.g. /dev/sda)


gpt or bios


The /aif/storage/disk/part element holds information on partitioning that its parent disk element should have.

Attribute Value


The partition number (positive integer)


The amount of the total disk size to start the partition at (see below)


The amount of the total disk size to end the partition at (see below)


The partition type. Must be in gdisk format (see below)

The start and stop attributes can be in the form of:

  • A percentage, indicated by a percentage sign ("10%")

  • A size, indicated by the abbreviation ("300K", "30G", etc.)

    • Accepts K (Kilobytes), M (Megabytes), G (Gigabytes), T (Terabytes), or P (PetabytesI know, I know.)

    • Can also accept modifiers for this form ("+500G", "-400M")

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.
fstype Formatting type


Microsoft basic data


Microsoft reserved


Windows RE


ONIE config


Plan 9


PowerPC PReP boot


Windows LDM data


Windows LDM metadata


Windows Storage Spaces




ChromeOS kernel


ChromeOS root


ChromeOS reserved


Linux swap


Linux filesystem


Linux reserved


Linux /home


Linux x86 root (/)


Linux x86-64 root (/


Linux ARM64 root (/)


Linux /srv


Linux ARM32 root (/)


Intel Rapid Start


Linux LVM


FreeBSD disklabel


FreeBSD boot


FreeBSD swap






FreeBSD Vinum/RAID


Midnight BSD data


Midnight BSD boot


Midnight BSD swap


Midnight BSD UFS


Midnight BSD ZFS


Midnight BSD Vinum


OpenBSD disklabel


Apple UFS


NetBSD swap






NetBSD concatenated


NetBSD encrypted




Recovery HD


Apple HFS/HFS+


Apple RAID


Apple RAID offline


Apple label


AppleTV recovery


Apple Core Storage


Acronis Secure Zone


Solaris boot


Solaris root


Solaris /usr & Mac ZFS


Solaris swap


Solaris backup


Solaris /var


Solaris /home


Solaris alternate sector


Solaris Reserved 1


Solaris Reserved 2


Solaris Reserved 3


Solaris Reserved 4


Solaris Reserved 5


HP-UX data


HP-UX service


Freedesktop $BOOT


Haiku BFS


Sony system partition


Lenovo system partition


EFI System


MBR partition scheme


BIOS boot partition


Ceph OSD


Ceph dm-crypt OSD


Ceph journal


Ceph dm-crypt journal


Ceph disk in creation


Ceph dm-crypt disk in creation




VMWare reserved


VMWare kcore crash protection


Linux RAID

Automatic formatting is currently only enabled for the following (subject to further configuration in later versions):
fstype Formatted as


vFAT32 (mkfs.vfat -F 32)






GNU/Linux swap (mkswap)


















The /aif/storage/mount element specifies mountpoints for each disk's partition.

Attribute Value


The device to mount


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


The order in which it should be mounted. These should be unique positive integers.


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


The mount options; provide the string exactly as it would be provided to mount(8)'s -o option


The /aif/network element specifies network configuration(s). It contains iface ("interface") elements.

Attribute Value


The hostname of the new installation


The /aif/network/iface element specifies various network configurations. Currently only ethernet is supported, and only limited support for IPv6 is available (but future improvements/flexible capabilities are planned).

Attribute Value


The interface name (in Predictable Interface Naming) (e.g. ens3); can be auto (see below)


The address to be assigned to the interface (in CIDR format); can be auto (see below)


One of ipv4, ipv6, or both


The gateway address for the interface/protocol pairing; only used if address is not auto


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 DHCPv6, depending on the configuration of netproto).

Setting netproto to "both" is really only useful if "auto" is specified for address.


The /aif/system element is for handling general system configuration. It contains the users, users/user, users/user/home, users/user/xgroup, and service elements.

Attribute Value


The timezone for the installed system (can be independent of the host system)


The 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)


The path on the host that will serve as the chroot path. This should be where your new installs / (root filesystem partition) is mounted at in mounts


The keyboard layout (if not US)


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.


The /aif/system/users element is used to specify users you wish to create (if any). It contains the user, user/home, and user/xgroup elements.

Attribute Value


A properly hashed-and-salted password. See below

To generate a proper hashed/salted password, you may want to reference this section from BDisk's user manual (another project of mine). You can use 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 authassuming you configure it beforehand. This has some added security benefits).

The /aif/system/users/user element specifies user(s) to create. It contains xgroup and home elements.

Attribute Value


The username/login name


If (full) sudo access should be granted to this user (boolean; must be one of 1/true or 0/false)


The salted/hashed password (see above)


A comment (typically, the users real/full name)


The UID of the user; if specified, must be a positive integer


The primary group of the user (the default is to create a new group named after that user)


The GID to use for the primary group; must be a positive integer


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.

Attribute Value


The group name


If the group should be created (boolean; must be one of 1/true or 0/false)


The GID to use (if creating); must be a positive integer and not be taken by an existing group


The /aif/system/users/user/home element contains information for a user's home directory. It can be only specified once per user, but it is optional.

Attribute Value


The path for the home directory; useful if you dont want it to be /home/<username>


If the home directory should be created (boolean; must be one of 1/true or 0/false)


The /aif/system/service element holds information about services that should explicitly be enabled/disabled on boot.

Attribute Value


The service name. It can be shortform (sshd) or long form (git-daemon.socket); if the shortform is provided, ".service" is assumed


A boolean that specifies if the service should be enabled (1/true) or disabled (0/false)


The /aif/pacman element contains the repos, repos/repo, mirrorlist, mirrorlist/mirror, software, and software/packages elements.

Attribute Value


The command to use to install a package

If you configured an alternate package utility (using a execution="pkg" 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 thats the entire point of AIF-NG). e.g.:

<aif ... >
    <pacman command="apacman --needed --noconfirm --noedit --skipinteg -S">


The /aif/pacman/repos element contains one (or more) repo element(s).


The /aif/pacman/repos/repo elements specify information for configuring the installed systems /etc/pacman.conf (specifically, the repositories).

Attribute Value


The name of the repository


A boolean that specifies if the repository should be enabled (1/true) or disabled (0/false)


The siglevel of the repository (e.g. Optional TrustedOnly); can be default (in which the pacman.conf default siglevel will be used)


The URI for the 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)


The /aif/pacman/mirrorlist element contains elements that should be in /etc/pacman.d/mirrorlist. It is optional; if it isnt specified, the default distributed mirrorlist will be used instead.


The /aif/pacman/mirrorlist/mirror elements are mirrorlist entries.


The /aif/pacman/software element contains one (or more) package element(s) that describe software to install. It is optional.


The /aif/pacman/software/package element holds information about software to be installed.

Attribute Value


The name of the package (e.g. openssh)


Optional, but you can specify which repository to install the package from (in the case of multiple repositories providing the same package)


The /aif/bootloader element specifies a bootloader to install.

Attribute Value


The bootloader to use; currently, the only supported values are grub and systemd (for systemd-boot) but more options may be available in the future


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)


This should be the absolute path (from within the newly installed system) to your ESP (if efi is true); otherwise the disk/partition to install the bootloader to (if youre using BIOS mode)


The /aif/scripts element contains one or more script elements.


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 mdadm so you can use that as a disk.

Attribute Value


The URI to the script; can be an HTTP/HTTPS reference, an FTP/FTPS reference, or a local file reference (file:///path/to/file).


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 its in different execution points


Same behavior as aif_auth but for fetching this script (see also further notes on this)


Same behavior as aif_user but for fetching this script (see also further notes on this)


Same behavior as aif_password but for fetching this script (see also further notes on this)


Same behavior as aif_realm but for fetching this script (see also further notes on this)


(see below)

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 packages are installed (this allows you to configure an alternate packager such as 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, other resources, and such relating to AIF-NG.

Bug Reports/Feature Requests

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 requestso please be sure to use a valid email address).


If you encounter any bugs in AIF-NG (for the actual agent), you can file a bug report here.

If you encounter any bugs in the configuration file tool, you can file a bug report here.

If you encounter any bugs (inaccurate information, typos, misformatting, etc.) in this documentation, you can file a bug report here.

Feature Requests

If you have any features youd like to see or you think would help AIF-NG become even more useful, please file a feature request here.

If you have any features youd like to see in the configuration file tool, you can file a feature requests here.

If you have any suggestions on how to improve this documentation or feel its missing information that could be useful, please file a feature request here.


I gladly welcome patches, but I deplore using GitHub (even though I have a mirror there). For this reason, please follow the same patch/pull request process for the Linux kernel and email it to

Alternatively, you may attach a patch to a bug report/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 email. If you use GPG, you can find my pubkey and other related info here (and on most keyservers).

I occasionally write howto articles, brief tips, and other information in my dev blog.

I am on IRC as r00t^2, and am usually in the Sysadministrivia channel on Freenode. Which reminds me, I run a podcast called Sysadministrivia.

I am on Twitter as @brentsaner, though I dont tweet very often. (I usually tweet from my podcasts twitter.)