/ansible-install-arch-zfs

Install Arch Linux on zfs from a live Arch USB

Primary LanguageJinja

ansible-install-arch-zfs

Ansible script that installs zfs-based Arch Linux from archiso.

Release License

Table Of Contents

Motivation

Install a minimal, bootable, zfs-based Arch Linux to a new machine from a live archiso USB stick.

Base the ansible script on the official Arch Linux Arch Linux ZFS Install Guide (also consult guidance in the Arch Linux Installation Guide and the Arch Linux ZFS pages)

Installation Script Actions

  • Installs to single hard drive, or two mirrored drives.
  • Auto-detects motherboard type (BIOS or UEFI).
  • Sets up GRUB bootloader.
  • Installs and enables NetworkManager.
  • Configures booting of the following archzfs kernels:
    • The zfs-linux stable kernel (via archzfs-linux package): default.
    • The zfs-linux-lts LTS kernel (via archzfs-linux-lts package): selectable in GRUB boot menu.

Installation Script Customization

  • Define required/optional vars using one of the methods in Full Usage / Options.
  • Required vars:
    • user_var_install_devices (an ansible list, e.g. - "sda")
  • Optional vars (have default values, and may be overridden):
    • user_var_zpool_name (e.g. "zpool_alpha")
    • arch_install_def_time_zone_file (e.g. "Canada/Central")
    • arch_install_def_locale (e.g. "en_US.UTF-8")
    • arch_install_def_keymap (e.g. "us")
    • arch_install_def_hostname (e.g. "omegarig")
  • Optional vars (for optional actions, when defined):
    • user_var_bootstrap_git_repo (repo to clone and place in /root)
    • user_var_extra_packages (extra packages to install to new machine)

Post-Installation

  • The machine is now bootable and will connect via wired network interface.
  • NOTE: all systemd zfs integration tasks listed in the Arch Linux ZFS Install Guide are completed automatically by the script.
  • The machine is now ready for normal user-level configuration, at the Arch Linux Post-Installation step.

Requirements

  • A new machine with one (or two, for mirrored setup) empty (or formatable) hard drive(s).
  • A USB stick with a bootable archiso image, and these archiso additions:
    1. A zfs kernel package (e.g. archzfs-linux), loadable with modprobe zfs.
    2. The git and ansible packages.

Quick Start

  1. Insert archiso USB stick into new machine.

  2. Boot up the new machine from the archiso USB stick. A shell prompt for the root user should be active.

  3. As required: use pacman to install git and ansible packages:

    $ pacman -Sy
$ pacman -S git ansible

  4. Clone project into a local directory:

    $ git clone https://github.com/digimokan/ansible-install-arch-zfs.git

  5. Change to the local directory:

    $ cd ansible-install-arch-zfs

  6. Run the ansible script for a single-disk install:

    $ ansible-playbook -i hosts -e '{"user_var_install_devices":["sda"]}' playbook.yml

  7. Configure the new machine, per the Arch Linux Post-Installation instructions in the Arch Linux Installation Guide.

Full Usage / Options

Method 1: Set Required User Vars From Command Line

  • For single-disk install option:

    $ ansible-playbook -i hosts -e '{"user_var_install_devices":["sda"]}' playbook.yml

  • For two-disk mirrored install option:

    $ ansible-playbook -i hosts -e '{"user_var_install_devices":["sda","sdb"]}' playbook.yml

  • For single-disk install option, customizing a var (e.g. zpool name):

    $ ansible-playbook -i hosts -e '{"user_var_install_devices":["sda"],"user_var_zpool_name":"zpool_alpha"}' playbook.yml

Method 2: Set Required User Vars In External Vars File

  1. Define the required user vars in an external file:

    # /some/file/path/my_user_vars.yml
user_var_install_devices:
  - "sda"
  - "sdb"
user_var_zpool_name: "zpool_alpha"

  2. Run the playbook, passing the external vars file:

    $ ansible-playbook -i hosts -e '@/some/file/path/my_user_vars.yml' playbook.yml

Method 3: Set Required User Vars Internally, Within Source Tree

  1. Edit the required user vars in project group_vars/all file:

    # group_vars/all
user_var_install_devices:
  - "sda"
  - "sdb"
user_var_zpool_name: "zpool_alpha"

  2. Run the playbook:

    $ ansible-playbook -i hosts playbook.yml

Source Code Layout

├─┬ ansible-install-arch-zfs/
│ │
│ ├── group_vars/         # required user-vars, and constant playbook vars
│ │
│ ├─┬ roles/
│ │ ├── arch-install/     # install Arch to disk(s), and configure
│ │ ├── archiso-config/   # performs initial config of the live USB OS
│ │ ├── dataset-creation/ # creates reasonable set of system/user datasets
│ │ ├── disk-format/      # formats install disk(s) with boot/zfs partitions
│ │ ├── grub-install/     # install GRUB bootloader to boot partition(s)
│ │ ├── play-fact-set/    # initial calc/set of play-wide vars
│ │ ├── pool-creation/    # creates zpool on the install disk(s)
│ │ ├── post-install/     # clean up and finalize the installation
│ │ ├── user-vars-chk/    # checks that required user_var_* vars are defined
│ │ └── zroot-config/     # configures zpool for use after adding datasets
│ │
│ ├── ansible.cfg         # play-wide ansible meta-config
│ ├── hosts               # ansible inventory (configured for local host)
│ └── playbook.yml        # main ansible playbook
│

Contributing