AIF-NG User Manual: Arch Installation Framework, Next Generation

Table of Contents

• Preface
  • About the Author
  • What is AIF-NG?
  • What it’s Not
  • Copyright/Licensing
• Getting Started
  • Downloading
  • Prerequisites
    • Necessary
    • Optional
• Writing an XML Configuration File
  • <aif>
    • <storage>
      • <disk>
        • <part>
      • <mount>
    • <network>
      • <iface>
    • <system>
      • <users>

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,” ^[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 (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 Ansible, Chef, Puppet, SaltStack, and 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 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 instead be interested in Antergos instead.)

Copyright/Licensing

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. It’s essentially the GPL for non-software, so similar terms apply.

Getting Started

Downloading

If it isn’t in your distro’s repositories (It is in Arch’s AUR! Both tagged release and git master.), you can still easily get rolling. Simply visit the project’s 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 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 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 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 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.

Necessary

These are needed for using AIF-NG.

• Python (>=3.6)

• sgdisk

• parted

• arch-install-scripts (for pacstrap)

  • 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 uses only the python 3 stdlib library.

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:

• LXML

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

Writing an XML Configuration File

I’ve included a sample aif.xml file 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 aif.xsd. For explanation’s sake, however, we’ll go through it here. The directives are referred to in XPath syntax within the documentation text for easier context (but not the titles).

<aif>

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.

<storage>

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

<disk>

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

Attributes	Value
device	The disk to format (e.g. /dev/sda)
diskfmt	gpt or bios

<part>

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

Attributes	Value
num	The partition number (positive integer)
start	The amount of the total disk size to start the partition at
size	The amount of the total disk size to end the partition at
fstype	The partition type. Must be in gdisk format (see below)

The start and size 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 (Petabytes - I know, I know.)

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

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.

fstype	Formatting type
0700	Microsoft basic data
0c01	Microsoft reserved
2700	Windows RE
3000	ONIE config
3900	Plan 9
4100	PowerPC PReP boot
4200	Windows LDM data
4201	Windows LDM metadata
4202	Windows Storage Spaces
7501	IBM GPFS
7f00	ChromeOS kernel
7f01	ChromeOS root
7f02	ChromeOS reserved
8200	Linux swap
8300	Linux filesystem
8301	Linux reserved
8302	Linux /home
8303	Linux x86 root (/)
8304	Linux x86-64 root (/
8305	Linux ARM64 root (/)
8306	Linux /srv
8307	Linux ARM32 root (/)
8400	Intel Rapid Start
8e00	Linux LVM
a500	FreeBSD disklabel
a501	FreeBSD boot
a502	FreeBSD swap
a503	FreeBSD UFS
a504	FreeBSD ZFS
a505	FreeBSD Vinum/RAID
a580	Midnight BSD data
a581	Midnight BSD boot
a582	Midnight BSD swap
a583	Midnight BSD UFS
a584	Midnight BSD ZFS
a585	Midnight BSD Vinum
a600	OpenBSD disklabel
a800	Apple UFS
a901	NetBSD swap
a902	NetBSD FFS
a903	NetBSD LFS
a904	NetBSD concatenated
a905	NetBSD encrypted
a906	NetBSD RAID
ab00	Recovery HD
af00	Apple HFS/HFS+
af01	Apple RAID
af02	Apple RAID offline
af03	Apple label
af04	AppleTV recovery
af05	Apple Core Storage
bc00	Acronis Secure Zone
be00	Solaris boot
bf00	Solaris root
bf01	Solaris /usr & Mac ZFS
bf02	Solaris swap
bf03	Solaris backup
bf04	Solaris /var
bf05	Solaris /home
bf06	Solaris alternate sector
bf07	Solaris Reserved 1
bf08	Solaris Reserved 2
bf09	Solaris Reserved 3
bf0a	Solaris Reserved 4
bf0b	Solaris Reserved 5
c001	HP-UX data
c002	HP-UX service
ea00	Freedesktop $BOOT
eb00	Haiku BFS
ed00	Sony system partition
ed01	Lenovo system partition
ef00	EFI System
ef01	MBR partition scheme
ef02	BIOS boot partition
f800	Ceph OSD
f801	Ceph dm-crypt OSD
f802	Ceph journal
f803	Ceph dm-crypt journal
f804	Ceph disk in creation
f805	Ceph dm-crypt disk in creation
fb00	VMWare VMFS
fb01	VMWare reserved
fc00	VMWare kcore crash protection
fd00	Linux RAID

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

fstype	Formatted as
ef00	vFAT32 (mkfs.vfat -F 32)
ef01	"
ef02	"
8200	GNU/Linux swap (mkswap)
8300	ext4
8301	"
8302	"
8303	"
8304	"
8305	"
8306	"
8307	"

<mount>

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

Attributes	Value
source	The device to mount
target	Where it should be mounted to in the filesystem (on the host system, not the new installation)
order	The order in which it should be mounted. These should be unique positive integers.

<network>

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

Attributes	Value
hostname	The hostname of the new installation

<iface>

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

Attributes	Value
device	The interface name (in Predictable Interface Naming) (e.g. ens3); can be auto (see below)
address	The address to be assigned to the interface (in CIDR format); can be auto (see below)
netproto	One of ipv4, ipv6, or both

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

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 users, users/user, users/user/home, users/user/xgroup, and service elements.

Attributes	Value
timezone	The timezone for the installed system (can be independent of the host system)
locale	The locale of the installed system (e.g. en_US.UTF-8)
chrootpath	The path on the host that will serve as the chroot path. This should be where your new install’s / (root filesystem partition) is mounted at in mounts.

<users>

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.

---

1. See http://catb.org/jargon/html/Y/yak-shaving.html