| .. | ||
| images | ||
| COPYING | ||
| LICENSE | ||
| README.adoc | ||
AIF-NG User Manual: Arch Installation Framework, Next Generation
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)
-
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.
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>
<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 |
|---|---|
|
The disk to format (e.g. |
|
<part>
The /aif/storage/disk/part element holds information on partitioning that it’s parent disk element should have.
| Attributes | Value |
|---|---|
|
The partition number (positive integer) |
|
The amount of the total disk size to start the partition at |
|
The amount of the total disk size to end the partition at |
|
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 |
|---|---|
|
Microsoft basic data |
|
Microsoft reserved |
|
Windows RE |
|
ONIE config |
|
Plan 9 |
|
PowerPC PReP boot |
|
Windows LDM data |
|
Windows LDM metadata |
|
Windows Storage Spaces |
|
IBM GPFS |
|
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 UFS |
|
FreeBSD ZFS |
|
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 FFS |
|
NetBSD LFS |
|
NetBSD concatenated |
|
NetBSD encrypted |
|
NetBSD RAID |
|
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 VMFS |
|
VMWare reserved |
|
VMWare kcore crash protection |
|
Linux RAID |
|
Note
|
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) |
|
ext4 |
|
" |
|
" |
|
" |
|
" |
|
" |
|
" |
|
" |
<mount>
| Attributes | Value |
|---|---|
|
The device to mount |
|
Where it should be mounted to in the filesystem (on the host system, not the new installation) |
|
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 |
|---|---|
|
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 |
|---|---|
|
The interface name (in Predictable Interface Naming) (e.g. |
|
The address to be assigned to the interface (in CIDR format); can be |
|
One of |
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 |
|---|---|
|
The timezone for the installed system (can be independent of the host system) |
|
The locale of the installed system (e.g. |
|
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.