Installation

Ironforge uses only UEFI so if it you want to use BIOS legacy to bood (which is fine) you cannot follow this guide as-is but you have to "think for yourself" how to adapt it.

It is assumed from here on that /dev/sda is the drive on which Ironforge will be installed. That might be different on your system so please adapt accordingly.

It is also perhaps understood that the /dev/sda drive is not the active OS drive. It is not supported by this guide to try and bootstrap yourself from an active OS drive and install over it.

Tools you will be using:

  • cfdisk to partition the drive;
  • cryptsetup to encrypt the system partition;
  • mkfs.vfat and mkfs.xfs (or equivalent) to format the partitions.

Partition table preparation

This drive will hold both the boot partition (the ESP partition) and the system partition which holds all other data on the OS.

NOTE: Use whatever tooling you want to do this but I find cfdisk (terminal UI) very easy to use and powerful enough for all my partitioning needs.

cfdisk -f /dev/sda

  1. Create a new partition table on a dedicated drive. The partition table must be of gpt type.

  2. Create one 1 GB partition (/dev/sda1) for /boot and one OS partition (/dev/sda2) for the OS files. Use all available space for the OS. The file type for the first partition should be EFI system and the second should be Linux filesystem.

Remember to save your changes. After partitioning you should have a system like 

                                 Disk: /dev/sda
            Size: 489.05 GiB, 525112713216 bytes, 1025610768 sectors
          Label: gpt, identifier: 408A6B5A-D737-4569-BFA7-2AB8C6133648

    Device           Start          End      Sectors    Size Type
    /dev/sda1         2048      2099199      2097152      1G EFI System         
    /dev/sda2      2099200   1025609727   1023510528    488G Linux filesystem

File system preparation

Format the boot partition /dev/sda1

mkfs.fat -F32 -n BOOT /dev/sda1

Encrypt the OS partition with cryptsetup

cryptsetup luksFormat -s 256 --sector-size 4096 /dev/sda2

Expose the decrypted volume:

cryptsetup luksOpen /dev/sda2 os

Use any file system besides ext4. I recommend xfs.

mkfs.xfs /dev/mapper/os

Prepare boot partition

Summary of what needs to be done:

  • Install UEFI shell as \EFI\BOOT\BOOTX64.EFI on the boot partition.
  • Optionally, create a \STARTUP.NSH file to boot into the system.
  • or, use efibootmgr to configure an EFI entry to boot directly into Linux.

Mount /dev/sda1 and mount it at /boot. It does not matter if something is already mounted there on a Live system. Nothing will typically use that after boot.

mount /dev/sda1 /boot

Create a EFI, EFI/BOOT and EFI/ironforge directories:

mkdir -pv /boot/EFI/{BOOT,ironforge}

Note: FAT is case insensive on read so the case does not really matter. You can use what you want. Note that the case you pick when you create the directory or file will still be visible when you list the files.

Download shellx64.efi from the UEFI Shell releases and save it as /boot/EFI/BOOT/BOOTX64.EFI.

Create a default startup script that will be used by UEFI Shell:

cat > /boot/startup.nsh <<'EOF'
MODE 80 25
\EFI\ironforge\bzImage.efi initrd=\EFI\ironforge\initrd.img root=/dev/mapper/os ro quiet net.ifnames=0 video=efib
EOF

Install the prepared kernel:

cp -bvi /path/to/bzImage /boot/EFI/ironforge/bzImage.efi

NOTE: The Linux admin guide claims that the bzImage needs to be called bzImage.efi with an .efi suffix, however I have not seen that this is a requirement on any UEFI installation I have access to.

Install the prepared initial RAM filesystem (initrd.img)

cp -bvi /path/to/initrd.img /boot/EFI/ironforge/initrd.img

Validate that you have the essential files installed:

/boot/EFI/BOOT/BOOTX64.EFI: PE32+ executable (EFI application) x86-64
/boot/startup.nsh: ASCII text
/boot/EFI/ironforge/bzImage.efi: Linux kernel x86 boot executable bzImage
/boot/EFI/ironforge/initrd.img: gzip compressed data, ASCII cpio archive

Finally, unmount the boot partition:

umount /boot

Prepare OS partition

Mount the OS partition

mount /dev/mapper/os /mnt

Setup the initial file system hierarchy:

mkdir -pv /mnt/{bin,boot,etc,lib64,mnt,opt,proc,root,run,sys,tmp,usr,var}

Some obscure programs require that /sbin exists and contains some "privileged set" of tools. In Ironforge all tools are simply stored in /usr/bin so we make a symbolic link to those:

ln -s /usr/bin /mnt/sbin

Install the kernel modules. We assume here that the root partition is mounted at /mnt:

make INSTALL_MOD_PATH=/mnt modules_install

Fetch base system image

Choose a complete /usr and /opt pair from the downloads page. Both files must have the same release ID. Verify their published SHA-256 values before installing them under the release directory and selecting the pair through releases/current:

release=YYYYMMDDHHMM
install -d "/mnt/var/ironforge/releases/$release"
install -m 0644 usr.sqfs "/mnt/var/ironforge/releases/$release/usr.sqfs"
install -m 0644 opt.sqfs "/mnt/var/ironforge/releases/$release/opt.sqfs"

ln -s "$release" /mnt/var/ironforge/releases/current
ln -s releases/current/usr.sqfs /mnt/var/ironforge/usr.sqfs
ln -s releases/current/opt.sqfs /mnt/var/ironforge/opt.sqfs

Replace YYYYMMDDHHMM with the selected release ID. On an existing Ironforge system, forge repo pull performs the download, verification, installation, and activation safely. See Release layout and updates for the complete update and rollback workflow.