Sortix
current nightly

Sortix cross-volatile manual

This manual documents Sortix cross-volatile. You can instead view this document in the latest official manual.

NAME

autoinstall.conf — automatic installation configuration

SYNOPSIS

/etc/autoinstall.conf

DESCRIPTION

autoinstall.conf configures sysinstall(8) to do an automatic operating system installation(7).
The system administrator can automate operating system installations by following release-iso-modification(7) to embed the /etc/autoinstall.conf file into the release cdrom filesystem. Existing installations can similarly be automatically upgraded using autoupgrade.conf(5).
Each line is formatted as question=answer which provides an answer to a question asked during installation. Alternatively question+=answer appends to an existing answer (if any) separated by a space, and question++=answer appends another line to an existing answer (if any). Empty lines and lines starting with ‘#’ are comments and are ignored. Otherwise whitespace is significant. The empty answer accepts the default answer (if any) and is different from no answer, which makes sysinstall(8) ask the question normally. Installations can be made fully non-interactive using accept_defaults.
Each question has a counterpart question suffixed with ‘!’ which contains a sh(1) script that is executed before the question is asked. If the original question isn't answered, then the script's standard output is used as the answer to the original question. The installation aborts if the script exits unsuccessfully. These scripts are useful to customize the installation with arbitrary code.
The questions in chronological order are as follows:
accept_defaults=[no | yes] (default no)
Accept the default answer (if any) to questions that were not configured in autoinstall.conf? This feature makes installations entirely automated even if unexpected questions are asked, although the essential questions must be answered.
countdown=seconds (default 10)
Count down for this many seconds with a warning that an automated installation is about to happen? The countdown happens if accept_defaults=yes or if the ready question is answered and either the disked or confirm_install questions are answered.
ignore_missing_programs=[no | yes] (default no)
Ignore if the installer environment does not have the needed ports installed? This situation ordinarily does not happen.
ready=affirmation
Are you ready to begin the installation process? This is a human readable positive affirmation of your choice that you're ready to install, useful for fully automated installations. Not answering this question is useful for semi-automated installations where one would acknowledge the installation before it's begun. It also provides the opportunity to escape to a shell before installing.
The ready! question is convenient for running shell commands before the installation begins.
kblayout=[default | layout] (default default)
Switch to this keyboard layout using chkblayout(1)? The choice is remembered as the kblayout(5) system default.
videomode=[no | yes | WIDTHxHEIGHTxBPP] (default yes)
Interactively select a graphics resolution using chvideomode(1) or non-interactively set it to the specified resolution? The choice is remembered as the videomode(5) system default.
If the installation is non-interactive with accept_defaults=true, then the default is instead no.
grub=[no | yes]
Install the GRUB bootloader onto the device containing the /boot filesystem (if it exists, otherwise the root filesystem)? The default is yes if any existing installations are found with GRUB enabled or if no filesystems were found, otherwise the default is no.
This is an essential question that must be answered for automatic installations.
grub_password=[no | yes] (default yes)
Protect the bootloader with a password to avoid unauthorized root access via the advanced bootloader features? The standard bootloader menu options don't require a password. The password is set in the grub_password_hash question.
If the installation is non-interactive with accept_defaults=true, then the default is instead no if the grub_password_hash question is not answered.
grub_password_hash=hash
The bootloader password as hashed by the grub-mkpasswd-pbkdf2(1) program? The password is asked interactively if this question is not answered. The choice is remembered in grubpw(5).
Although it's discouraged to place unhashed passwords in autoinstall.conf, the grub_password! question could be answered with grub-mkpasswd-pbkdf2 -p password to dynamically hash the bootloader password.
grub_password_empty=[no | yes] (default no)
Allow an insecure empty bootloader password typed interactively?
kernel_options=options
What kernel(7) options should be set in grub(5) with GRUB_CMDLINE_SORTIX? This question is asked only the GRUB port is installed, if the kernel was booted with explicit options or this question is set.
disked=commands
Commands to create partitions and filesystems with disked(8)? The ++= syntax is useful to append multiple lines to the disked answer. A root filesystem must be mounted in order to install the operating system. The mountpoints are remembered in fstab(5).
This is an essential question that must be answered for automatic installations.
The disked! question is convenient for running shell commands before the partitioning step, or to generate dynamic partitioning commands on the standard output if the original disked question is unanswered.
missing_bios_boot_partition=[no | yes] (default yes)
Attempt disked(8) again if the GRUB bootloader is installed but the /boot directory's filesystem is inside a GPT partition table that doesn't have a biosboot partition?
confirm_install=[no | yes | exit | poweroff | reboot | halt] (default yes)
Install the operating system or abort the installation? This is the final confirmation before the operating system is installed, after the partitioning has taken place.
The confirm_install! question is convenient for running shell commands before the installation step, after partitioning has happened, but before the filesystems are mounted.
hostname=hostname
Hostname for the installation? The choice is remembered in hostname(5).
This is an essential question that must be answered for automatic installations. If it isn't answered and accept_defaults=yes, then the current (and likely default) hostname is used.
password_hash_root=hash
Password for the root user as hashed with crypt_newhash(2)? The empty string sets the password to the empty string (insecure) and a literal x disables password login for root. The choice is remembered in passwd(5).
This is an essential question that must be answered for automatic installations. If it isn't answered and accept_defaults=yes, then password login is disabled for root.
Although it's discouraged to place unhashed passwords in autoinstall.conf, the password_hash_root! question could be answered with echo password | passwd -H to dynamically hash the root password.
password_hash_root=[no | yes] (default no)
Allow an insecure empty root password typed interactively?
copy_ssh_authorized_keys_root=[no | yes] (default yes)
Copy the /root/.ssh/authorized_keys file (if it exists) into the installation?
copy_ssh_config_root=[no | yes] (default yes)
Copy the /root/.ssh/config file (if it exists) into the installation?
copy_ssh_id_rsa_root=[no | yes] (default yes)
Copy the /root/.ssh/id_rsa file (if it exists) into the installation?
copy_ssh_known_hosts_root=[no | yes] (default yes)
Copy the /root/.ssh/known_hosts file (if it exists) into the installation?
empty_password=[no | yes] (default no)
Allow insecure empty passwords for regular users?
enable_gui=[no | yes] (default yes)
Enable the display(1) graphical user interface? The choice is remembered in session(5).
enable_ntpd=[no | yes] (default no)
Automatically get time from the network using ntpd(8)? Note this choice has privacy implications as the servers in ntpd.conf(5) file will be contacted in the background. The choice is remembered in /etc/init/local per init(5).
enable_sshd=[no | yes] (default no)
Enable the sshd(8) secure shell server? The choice is remembered in /etc/init/local per init(5).
copy_sshd_config=[no | yes] (default no)
Copy the /etc/sshd_config file (if it exists) into the installation?
enable_sshd_password=[no | yes] (default no)
Enable password authentication in the local sshd(8)? The choice is remembered in sshd_config(5).
It's strongly encouraged to answer no and instead use public key authentication. The installation environment can be seeded with the ssh keys using the release-iso-modification(7) procedure and the default answers will copy the keys into the installation.
enable_sshd_root_password=[no | yes] (default no)
Enable ssh to the root user with password authentication?
copy_sshd_private_keys=[no | yes] (default yes)
Copy the sshd private keys (if they exist) into the installation? These are /etc/ssh_host_ecdsa_key, /etc/ssh_host_ed25519_key, and /etc/ssh_host_rsa_key.
finally=[exit | poweroff | reboot | halt | boot | chroot] (default boot)
What action should be taken when the installation is finished?
The finally! question is convenient for running shell commands once the installation is complete to customize the installation. The working directory is the root filesystem of the installation with all filesystems mounted. The chroot -d . command is useful to chroot(8) into the new root filesystem to run commands with the /dev filesystem mounted.

FILES

/etc/autoinstall.conf
Automatic installation configuration.

EXAMPLES

Fully automated installation

To perform a fully automated installation with root login disabled, create autoinstall.conf:
accept_defaults=yes 
grub=yes 
disked++=mktable mbr 
disked++=mkpart 1 0% 100% ext2 / 
hostname=dragon 
password_hash_root=x
Then follow release-iso-modification(7) to configure the installation medium:
tix-iso-liveconfig --autoinstall=autoinstall.conf liveconfig 
tix-iso-bootconfig \ 
  --liveconfig=liveconfig --default=1 --random-seed \ 
  bootconfig 
tix-iso-add sortix.iso bootconfig -o autosortix.iso
The resulting autosortix.iso image will then automatically format the harddisk and install the operating system on whatever machine it is booted on. Take care.

Setting passwords

The grub-mkpasswd-pbkdf2(1) command can be used to hash a GRUB password and passwd(1) can be used to hash a user password:
grub-mkpasswd-pbkdf2 -p bootloader-password 
echo root-password | passwd -H
The hashes can then be inserted in autoinstall.conf:
grub_password_hash=grub.pbkdf2.sha512.10000.68DA[...] 
password_hash_root=$2b$10$d/9pP1[...]
Alternatively the passwords could be embedded in autoinstall.conf, however beware that your autoinstall.conf file and the installation medium could leak:
grub_password_hash!=grub-mkpasswd-pbkdf2 -p bootloader-password 
password_hash_root!=echo root-password | passwd -H

Automatically install with sshd

To automatically install the operating system with sshd enabled with keys and authorizations set up ahead of time, first create autoinstall.conf:
accept_defaults=yes 
grub=yes 
disked++=mktable mbr 
disked++=mkpart 1 0% 100% ext2 / 
hostname=example.com 
password_hash_root=x 
enable_sshd=yes
Then follow release-iso-modification(7) to configure the installation medium with automated installation and sshd:
tix-iso-liveconfig \ 
  --autoinstall=autoinstall.conf \ 
  --root-ssh-authorized-keys="$HOME/.ssh/id_rsa.pub" \ 
  --sshd-keygen \ 
  --sshd-key-known-hosts-file="$HOME/.ssh/known_hosts" \ 
  --sshd-key-known-hosts-hosts="example.com example.com,192.0.2.1 192.0.2.1" \ 
  liveconfig 
tix-iso-bootconfig \ 
  --liveconfig=liveconfig --default=1 --random-seed \ 
  bootconfig 
tix-iso-add sortix.iso bootconfig -o autosortix.iso
To ssh into the installation after it has finished:
ssh root@example.com
The connection will be immediately trusted because the just-generated server keys were associated with the hostname in the $HOME/.ssh/known_hosts file. This step assumes the hostname (example.com in this example) resolves to the installation's IP address, otherwise the IP address can be used directly. If the IP address is known ahead of time, it should be inserted into the space delimited --sshd-key-known-hosts-hosts list of host aliases.

Automatically install into a virtual machine with sshd

To automatically install into a qemu virtual machine, follow the above example but instead associate the server keys with your localhost and optionally use a known_hosts file per virtual machine.
  ... 
  --sshd-key-known-hosts-file="sortix.hdd.known_hosts" \ 
  --sshd-key-known-hosts-hosts=127.0.0.1 \ 
  ...
Create the harddisk and spawn the virtual machine and forward the local port 2222 to the virtual machine's port 22.
qemu-img create -f qcow2 sortix.hdd 1G 
qemu-system-x86_64 \ 
  -vga std -m 1024 \ 
  -hda sortix.hdd -cdrom autosortix.iso \ 
  -device e1000,netdev=net0 \ 
  -netdev user,id=net0,hostfwd=tcp:127.0.0.1:2222-:22
To ssh into the installation after it has finished:
ssh -oUserKnownHostsFile=sortix.hdd.known_hosts -p 2222 root@127.0.0.1

SEE ALSO

autoupgrade.conf(5), upgrade.conf(5), release-iso-modification(7), upgrade(7), sysupgrade(8), tix(8)
Copyright 2011-2024 Jonas 'Sortie' Termansen and contributors.
Sortix is free software under the ISC license. 		#sortix on irc.sortix.org
@sortix_org