This assumes you have partitioned your target drive and formatted your partitions with the necessary filesystems.
The first thing before you install the OS is to mount the partitions with the desired layout matching the final system.
First, you need to mount the root partition. Create a mount point for it first:
# mkdir /media/root
Then mount it (assuming
/dev/sda2 for root partition):
# mount /dev/sda2 /media/root
Make sure that the root file system’s mount has 755 permissions. If it for some reason does not and instead it’s for example 700, it will result in strange issues when logging in as non-root. The fix for that is easy:
# chmod 755 /media/root
Then you can move on to the other partitions.
You will want to mount the EFI System Partition as well. There
are several locations, based on your layout. First, let’s assume
that the ESP is
If you have a dedicated
/boot partition (let’s say
mount it first:
# mkdir /media/root/boot
# mount /dev/sda3 /media/root/boot
Regardless, mount the ESP:
# mkdir -p /media/root/boot/efi
# mount /dev/sda1 /media/root/boot/efi
If your ESP and
/boot are merged, do this instead:
# mkdir /media/root/boot
# mount /dev/sda1 /media/root/boot
You will also want to mount other physical partitions you are using in the locations where they are going to be. Do keep in mind that for nested mountpoints, always mount parent partitions first.
There are two ways you can install the system onto a partitioned, mounted drive. One is a local installation, which copies the live system onto the drive (but without live-related bits), the other is a remote installation from the repositories.
Note that local installation is only available when booted from a live ISO image. When installing from another Chimera system, e.g. when booted from an SD card with a device image flashed, you can only perform a network installation.
For both cases, you use the
chimera-bootstrap program. The
-h for a help listing.
NOTE: The tool will abort by default if any of the directories
within the mounted hierarchy are non-empty. This is a safeguard
against doing something wrong, since this is a sensitive operation
that handles user data. However, it can also fail in intended
scenarios, such as multi-boot setups (pre-existing populated ESP)
or if the user wishes to keep their
/home intact. In those cases,
it is safe to pass the
-f flag to force proceed, but please do
verify that you are indeed using the correct destination when
using this flag.
To perform a local installation with
option is required. Invoke it like this:
# chimera-bootstrap -l /media/root
This is the default mode. By default,
base-full will be installed
into the root; you can override this by passing a custom list of
packages after the root filesystem argument.
# chimera-bootstrap /media/root
You can technically perform this from any booted Chimera system, as
chimera-install-scripts are a part of any base installation.
Prepare the system
Regardless of the installation method you choose, you will need to open a shell in the target system to install updates, possibly other packages you need to boot, and the bootloader.
chimera-chroot tool exists to simplify that task for you.
It will mount the pseudo-filesystems for the session as well as
ensure you have network access inside.
# chimera-chroot /media/root
First, update the system. If installing from the network, this might not do anything.
# apk update
# apk upgrade --available
apk update fails, make sure your system date/time is set to a
correct value. Incorrectly configured date/time can result in HTTPS
certificate errors. If the date/time is indeed wrong, you can set it
# date YYYYMMDDHHmm
Replace the value with the current date/time, typically in UTC, as you do not have a timezone set yet.
If you run into any other errors, such as conflicting packages overwriting each other’s files, don’t worry; just fix it:
# apk fix
After that, try again and there should be no more errors:
# apk upgrade --available
At this point you might also want to enable the
if you plan to install software from there (which there is a good
chance you will):
# apk add chimera-repo-contrib
And refresh indexes again to make it propagate:
# apk update
Device base package
For devices that would use device images, a special base package is needed.
For example, for Raspberry Pi:
# apk add base-rpi
For Pinebook Pro:
# apk add base-pbp
And so on. The format is always
base-PLATFORM, with a list of
platforms available here.
A lot of the device packages are in the
The base packages for U-Boot devices come with a default kernel command
/etc/u-boot-cmdline. This contains a pre-defined
that is suitable for the default partitioning as shipped with the device
images. This will not work with custom partition layouts, for example when
using LVM/LUKS or when your partition label is different, and it’s only
present so that U-Boot configuration can be generated statically without
executing code in the target root, so you can remove it (the U-Boot menu
generator will figure out the root from the current configuration).
This needs to be done before installing the kernel.
If you performed a local installation from the live image, it already comes with a kernel.
Otherwise you might have to add it:
# apk add linux-lts
If you wish to use ZFS, add that too:
# apk add linux-lts-zfs-bin
This typically refers to the latest Long Term Support version of the Linux
kernel. If you’d like to use the latest stable version of the kernel
instead, for example if LTS is missing some functionality or driver
that is important to you, you can install
# apk add linux-stable
Likewise, you can add
linux-stable-zfs-bin for binary ZFS modules.
Device-specific kernel may sometimes be needed. For example for Raspberry Pi,
you will want to use
linux-rpi instead of the above (ZFS modules likewise
exist for it). Chimera typically avoids shipping device-specific kernels
though, so they are rare in the repositories.
Strictly speaking, a Chimera system does not need
/etc/fstab to boot.
Having an entry for the root filesystem is optional and you might not
have any other filesystems. However, it is recommended that you have
fstab, with which you can control mount flags as well as
fsck behavior or e.g. whether the root filesystem is mounted read-only.
The installation scripts come with a
fstab generator. You can invoke
# genfstab / > /etc/fstab
It is also possible to invoke it from the outside of the system, e.g. like:
# genfstab /media/root > /media/root/etc/fstab
You might want to manually edit the generated
fstab to remove useless
mount options and so on.
If you have a swap partition and you want it automatically included in
fstab, activate the swap partition before generating it. Otherwise,
you can also include it manually.
fstab that comes with the system does not contain any entries.
/etc/fstab for a root partition and ESP may look like this:
UUID=... / ext4 defaults 0 1
UUID=... /boot/efi vfat defaults 0 2
It is not necessary to add entries for pseudo-filesystems such as the
/sys mounts. If you want to have read-only
you will also have to add a
tmpfs entry for
/tmp, as the directory
needs to be globally writable. On other systems, you do not need such
/tmp does not need to be a mount (it will be periodically
In general the order of the rows should be root filesystem first and other filesystems after that, as they are mounted in that order and parent mounts need to be mounted first.
The first column identifies the device. It is recommended that you always
use unique paths such as
PARTUUID=... (using alias paths
/dev/disk/by-uuid will work as well),
as names such as
/dev/sda may change. For encrypted devices, you will
want to use the
/dev/mapper paths, e.g.
The second column is the mount point. The entries should be specified in an order so that parent mounts come first.
The third column specifies the file system, and the fourth column contains the mount options for it.
The fifth column should usually be
0 and relates to
dump(8). The sixth
column specifies the order for
fsck(8). Normally the root filesystem
1 and other filesystems should specify
If the root filesystem is not specified in
fstab, Chimera will mount it
as if it was specified with
defaults, and will
fsck it as if the sixth
For more information, see
You can install whichever other packages you like.
Set your root password here, or you will not be able to log in:
# passwd root
Serial login prompt (getty)
This only applies to you if you wish to have console access over the serial port (often the case on embedded devices and servers, but typically not normal desktop computers).
While the live image autodetects this and lets you log in over serial
terminal, the final system does not, and will only by default enable
You need to know which serial tty is yours; often this will be something
/dev/ttyS0, but could be anything else, like
/dev/ttySIF0, and others.
Create the file
/etc/default/agetty that contains something like the
Note that this will only work if the corresponding service exists, for
/etc/dinit.d/agetty-ttyS0. Chimera ships with pre-made service
files for many serial consoles. However, the characteristics and device
may differ a lot, so it might not be exhaustive.
If the baud rate or other parameters need tweaking, you can copy them
from the live system (e.g.
/etc/default/agetty-ttyS0), as the live
autodetection generates a configuration file if necessary.
A bootable system will typically need an initramfs image. You need to create one near the end, but before generating your bootloader config, as the bootloader needs to be aware of it.
Therefore, best do that now:
# update-initramfs -c -k all
GRUB is a common bootloader that works on more or less every platform that Chimera supports. If you wish to use a different way to boot your system, or you can’t use GRUB (e.g. for U-Boot devices, Raspberry Pis, and so on), skip this section.
First you will need to add it.
Example for x86 BIOS:
# apk add grub-i386-pc
Example for x86_64 EFI:
# apk add grub-x86_64-efi
Example for a POWER virtual machine, Power Mac or PowerVM hardware:
# apk add grub-powerpc-ieee1275
On a PowerNV machine with Petitboot, you do not need any low level bootloader
as the machine comes with one, so just add
grub. On other platforms, there
are more choices, e.g.
The installation will differ slightly depending on the platform. For example for BIOS systems:
# grub-install /dev/sda
On OpenPOWER systems (which use Petitboot), you will not install the bootloader but instead you need to create the directory for the config:
# mkdir /boot/grub
On POWER systems with a PReP partition:
# grub-install /dev/sda1
On Power Macs it’s a little more complicated (and needs
# mkdir -p /boot/macppc
# mount -t hfs /dev/sda2 /boot/macppc
# grub-install --macppc-directory=/boot/macppc /dev/sda2
# umount /boot/macppc
# rmdir /boot/macppc
# hmount /dev/sda2
# hattrib -t tbxi -c UNIX :System:Library:CoreServices:BootX
# hattrib -b :System:Library:CoreServices
On EFI systems with separate ESP:
# mkdir -p /boot/efi
# mount /dev/sda1 /boot/efi
# grub-install --efi-directory=/boot/efi
And so on. You will want
--target=x86_64-efi as well if installing EFI on
x86_64 while booted in BIOS mode.
If you do not want GRUB to alter firmware boot entries,
--no-nvram can be
passed. Additionally, certain EFI firmwares are buggy and require a bootable
file at a known location before they show any NVRAM entries. In this case
the system may not boot. This does not affect most systems, but if you have
a board with such buggy firmware, you can pass the
--removable flag to
work around it.
--removable, a similar workaround will also work:
# mv /boot/efi/EFI/chimera /boot/efi/EFI/BOOT
# mv /boot/efi/EFI/BOOT/grubx64.efi /boot/efi/EFI/BOOT/BOOTX64.EFI
On Power Macs it is recommended to turn off graphical GRUB, which can be
done by uncommenting
You may also want to add
GRUB_DISABLE_OS_PROBER=true to prevent GRUB
from scanning other drives (which slows down the config generation).
In any case, you will want to generate a GRUB configuration file on all platforms:
For devices using U-Boot, it is needed to flash it:
# install-u-boot /dev/mmcblk0
The whole target device needs to be passed, not a partition.
After that, you might want to refresh the menu entries just in case:
If your partitioning is somehow special, double-check whether
contains the correct
root= parameter, in case you forgot to remove the
No special setup is necessary for booting on Raspberry Pi, except possibly for
tweaking the cmdline (
/boot/cmdline.txt) to reflect your partition and filesystem
layout. If your filesystem (not partition) is labeled
root, no changes should
Other post-installation tasks
At this point, the system should be capable of booting on its own.
If you wish, you can perform other post-installation tasks here, or you can do so after you have booted into the system.
Either way, proceed to Post-installation.