Target Audience: People comfortable using the Linux command line.
Installation of Casuarina Linux is currently done by hand at the command line. There are three main steps:
The documentation on this page describes a basic install on an EFI based system. For BIOS based systems, and information about encryption please refer to the Chimera installation guide.
The rest of this guide assumes you have downloaded and booted into the live ISO. Installation can be performed on the console of the booted system, or over SSH. To use SSH:
root using the password printed when booting the live environmentdinitctl enable sshdip aanon user (SSH as root is not
allowed by default): ssh anon@IProot to perform the install: suNote: If using SSH keep in mind the default live environment passwords are relatively weak, so consider changing these if ssh is exposed to an unfriendly network.
If available, it is preferable to be connected to the internet. Wired
connections should be automatically configured. For Wi-Fi a connection will
need to be established with the Internet wireless daemon (iwd). First start
the daemon with dinit:
dinitctl enable iwdThen enter the CLI to connect:
iwctlDetermine the name of your Wi-Fi device using device list. E.g.
[iwd]# device list
Devices
--------------------------------------------------------------------------------
Name Address Powered Adapter Mode
--------------------------------------------------------------------------------
wlp17s0 ab:cd:ef:01:02:03 on phy0 stationNote: The iwd CLI supports tab completion.
Scan for networks: station wlp17s0 scan. Use station wlp17s0 get-networks to
see a list of available networks. Connect to the desired network (SSID):
station wlp17s0 connect SSIDEnter a password if prompted. This should connect to the network. You can
check on the connection with station wlp17s0 show.
The layout we’re aiming for is GPT partition table with partitions for:
Swap is optional, though recommended even on systems with lots of RAM.
Use the cfdisk tool to partition the disk, passing the device node
as an argument. This will be something like /dev/nvme0n1 for an NVMe
drive /dev/sda for a SATA drive, or /dev/vda for a VirtIO drive in
a virtual machine. For this guide /dev/vda will be used.
cfdisk /dev/vdaIf prompted, select gpt as the partition table type. Next create the
partitions:
/boot: 1G, Type: Linux extended boot/: rest of disk, Type: Linux filesystem (default in cfdisk)Below is an example of this configuration in a virtual machine with a 20Gb drive:
Once the partitions are configured, select [ Write ], then [ Quit ].
Filesystems need to be created on each of the partitions. To have a quick reference for what each of
the partitions is named use fdisk -l /dev/vda:
# fdisk -l /dev/vda
Disk /dev/vda: 20 GiB, 21474836480 bytes, 41943040 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: 42195B4E-9102-4E33-83CB-589257E526EB
Device Start End Sectors Size Type
/dev/vda1 2048 411647 409600 200M EFI System
/dev/vda2 411648 2508799 2097152 1G Linux extended boot
/dev/vda3 2508800 6703103 4194304 2G Linux swap
/dev/vda4 6703104 41940991 35237888 16.8G Linux filesystemThe EFI system partition should be formatted FAT32. Skip this step if using an existing EFI system partition.
mkfs.vfat /dev/vda1/boot/boot should also typically use FAT32.
mkfs.vfat /dev/vda2mkswap /dev/vda3The root partition can use your preferred filesystem. If in doubt ext4 is a safe choice:
mkfs.ext4 /dev/vda4Next that partitions need to be mounted so that the system can be installed. Each parent must be mounted before it’s children, so in the example this is root, boot, efi, swap. A mount-point (directory) must be created before each partition can be mounted.
mkdir /media/root
mount /dev/vda4 /media/rootMake sure the root mount has 755 permissions (ls -l /media/root).
If not, adjust with chmod 755 /media/root.
/bootmkdir /media/root/boot
mount /dev/vda2 /media/root/bootmkdir /media/boot/boot/efi
mount /dev/vda1 /media/root/boot/efiswapon /dev/vda3Now the system can be installed. Installation is mostly configuring
the apk package manager and installing the packages comprising the
base system onto the mounted filesystems. This is automated with the
chimera-bootstrap script. Run chimera-bootstrap -h to learn about its
usage.
If you connected to the internet a network installation (the default) is
preferable as up-to-date packages are installed. If an internet connection
is not available a local install that copies the live environment is also
possible by passing -l to chimera-bootstrap. Bootstrap the system by
passing the path to the root mount:
chimera-bootstrap /media/rootThis will install the base system packages (by default through installing the
base-full package) and should end with the message:
Chimera bootstrap successful at /media/root.
You can use chimera-chroot to get a shell in the system.
Please perform all post-installation steps now (bootloader etc.).You can now chroot into installed system to configure it using the chimera-chroot
script:
chimera-chroot /media/rootIf you performed a local installation, remove the base-live package:
apk del base-liveAt this point the target system does not have a Linux kernel installed.
Stable and long term support (LTS) kernels are available. LTS kernels
are selected kernel versions that only receive minor updates over their
lifetime. The stable kernel tracks the currently released stable kernel
version and may include new or updated drivers, but it also changes more
often. Install your preferred kernel with apk. E.g.:
apk add linux-stableIf you wish to use ZFS add the ZFS kernel modules for your selected kernel:
apk add linux-lts-zfs-binGenerate /etc/fstab using the genfstab tool. This will use the mounted
filesystems to generate content for /etc/fstab:
genfstab -U / >> /etc/fstab-U is passed to make it use UUIDs, which are preferable over device names
as they remain stable across boots and hardware changes.
The generated fstab will probably have a lot of mount options manually
specified. Generally these can be replaced by defaults. Edit the file
with nano or vi. For example the following:
# See fstab(5).
#
# <file system> <dir> <type> <options> <dump> <pass>
UUID=ad5270b2-7361-4bda-bb1e-29ec3b84cf7f / ext4 rw 0 1
UUID=AF08-3D22 /boot vfat rw,fmask=0022,dmask=0022,codepage=437,iocharset=iso8859-1,shortname=mixed,utf8,error
s=remount-ro 0 2
UUID=AEDB-0271 /boot/efi vfat rw,fmask=0022,dmask=0022,codepage=437,iocharset=iso8859-1,shortname=mixed,utf8,e
rrors=remount-ro 0 2
UUID=bd0133a9-571b-4140-bc7b-06821a3a4e91 none swap defaults 0 0can be replaced with:
# See fstab(5).
#
# <file system> <dir> <type> <options> <dump> <pass>
UUID=ad5270b2-7361-4bda-bb1e-29ec3b84cf7f / ext4 rw 0 1
UUID=AF08-3D22 /boot vfat defaults 0 2
UUID=AEDB-0271 /boot/efi vfat defaults 0 2
UUID=bd0133a9-571b-4140-bc7b-06821a3a4e91 none swap defaults 0 0Set the root password. If you forget this you won’t be able to log into the system.
passwd rootThe initial RAM filesystem for the kernel was probably automatically generated when the kernel was installed. However, since It must be present before the bootloader is installed make sure by running the update manually:
update-initramfs -c -k allA bootloader is generally needed to boot the system. systemd-boot is
the recommended bootloader for EFI systems. GRUB is also available if
needed/preferred. This guide will use systemd-boot.
Install the systemd-boot package:
apk add systemd-bootFor the bootctl to add a boot entry to the EFI variables the efivars
filesystem must be mounted rw. Check this is the case:
mount | grep efivarsIf the output shows that’s mount readonly (ro), remount it read-write (rw):
mount -o 'remount,rw' /sys/firmware/efi/efivarsNow install the bootloader onto the drive:
bootctl installSuccessful installation will end with output like:
Successfully initialized system token in EFI variable with 32 bytes.
Created EFI boot entry "Linux Boot Manager".By default systemd-boot does not show a boot menu. This and other
settings can be adjusted by editing the /boot/efi/loader/loader.conf
file.
systemd-boot uses small configuration files to define each boot entry.
At least one of these will need to be present to boot the system. The
gen-systemd-boot script will generate an entry for each installed kernel.
This script is automatically triggered when installing new/updated kernels.
However, it needs to be run manually now:
gen-systemd-bootIf necessary the defaults used by gen-systemd-boot can be overridden by
setting variables in /etc/default/systemd-boot, though this is not typically
needed. Check the /usr/bin/gen-systemd-boot for the available variables.
The system should be capable of booting itself at this point. The following
tasks can be performed in the chroot, or after rebooting. Performing them
from the chroot is recommended.
Create a regular user (non-root) with useradd:
useradd usernameSet the password of the new user:
passwd usernameCasuarina uses doas instead of sudo for elevating privileges. If the new
user will use doas to gain root privileges add them to the wheel group
usermod -a -G wheel wmooreThe flags are: -a to append the groups specified by the -G option to the
user record. View the man page (man usermod) for more information.
Set the hostname for the system by populating /etc/host:
echo casuarina > /etc/hostnameThe default time zone is UTC. To change it sym link /etc/localtime to one of
the time zones in /usr/share/zoneinfo. E.g.
ln -sf /usr/share/zoneinfo/Australia/Brisbane /etc/localtimeSystem services are managed with dinit. Services must be enabled for
them to start automatically. In a booted system this is done with
dinitctl enable service (as the root user). In the live system chroot
add --offline to the invocation: dinitctl enable --offline service. This
is required because dinit is not running in the chroot.
Some common services that you might want to enable are:
syslog-ng for system loggingsshd for SSH accesschrony for NTP synchronisationiwd for connecting via Wi-Fidhcpcd DHCP client for automatically configuring network interfacesAll of the above are part of the base-full package, which chimera-bootstrap
installs by default.
Additional packages that may be needed can be installed here. In particular
packages required to get the network connected should be installed now. Although
the most commonly required tools are installed as part of base-full.
It’s now time to reboot into the new system. Exit the chroot with
exit or Ctrl-d. While not strictly necessary, unmount the install
root with umount -R /media/root, and then reboot:
rebootAll going well the system will boot up into the new install. Refer to other parts of the documentation for more information on using the system. It may also be good to read the Chimera documentation.
If you run into issues the live environment can be used to make
changes such as installing missing packages or altering configuration.
Boot into the live environment. Mount partitions as per the
mounting step, and then enter the system with
chimera-chroot:
chimera-chroot /media/rootFrom there you can make changes as needed before rebooting and trying again.