aif-ng/docs
2017-05-04 16:35:55 -04:00
..
images working my way through docs... 2017-05-04 16:35:55 -04:00
COPYING initial commit- license 2017-01-16 16:23:06 -05:00
LICENSE initial commit- license 2017-01-16 16:23:06 -05:00
README.adoc working my way through docs... 2017-05-04 16:35:55 -04:00

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

GPLv3

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.

CC-BY-SA_4.0

Getting Started

Downloading

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:

cgit

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 distros repositories.

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

Prerequisites

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

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

Necessary

These are needed for using AIF-NG.

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

Ive included a sample aif.xml file which is fully functional. However, its not ideal- namely 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).

<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 its 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 installs / (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.