Installing CRUX

Supported Hardware / Requirements

Packages on the official CRUX ISO image are compiled with optimization for x86-64 (AMD Athlon 64, Intel Core, Intel Atom) or newer processors. Do not try to install it on an i686 (Pentium-Pro, Celeron, Pentium-III) or lower processor, since it simply will not work.

A minimum of 2GB system memory is required to install CRUX from a DVD or removable flash drive. It is possible to perform a custom chroot installation with a smaller amount of RAM.

The kernel used during installation, i.e. when booting from the CRUX ISO image (El Torito), is compiled with support for most disk controllers. If your hard disk is not recognized after booting from the ISO image (i.e., the output of lsblk only shows the CRUX media), you might find a solution in the CRUX wiki, the mailing lists, or the bug tracker. You could also ask for help on the CRUX IRC channels. For example, the owner of a low-power machine that uses a board soldered memory card as its main disk was able to install CRUX successfully after building an ISO with kernel customized to enable CONFIG_X86_INTEL_LPSS.

Installing From Optical Medium or Removable Flash Drive

Download the CRUX ISO image (crux-3.7.iso). To ensure that the download was successful, examine its checksum.

 $ shasum -a 256 crux-3.7.iso

Compare the output with the file crux-3.7.sha256, which can be found in the same directory as the ISO image on the download site. If the checksums match, the download was successful and you can continue by burning the ISO image to a DVD or writing it to a removable flash drive.

The ISO image is bootable. After making sure that your BIOS gives priority to optical drives or flash drives, just insert the newly-written DVD or removable flash drive and reboot your computer. Press Enter at the boot prompt (you might have to adjust the root= parameter, depending on your hardware configuration).
You will be logged in as root on tty1 (root has no password set).
Create (if necessary) and format the partition(s) you want CRUX to be installed on. Remember the choice you make for the filesystems (especially root)! The driver for your chosen filesystem must be compiled into your Linux kernel, or included on an initramfs.

 $ fdisk /dev/sd?
 $ mkfs.???? /dev/sd??
 $ mkswap /dev/sd??

Note

Please keep in mind that SATA harddisks are usually detected as SCSI devices. The first SATA disk is called /dev/sda instead of /dev/hda. For more information about harddisk naming conventions please refer to the Linux Partition HOWTO.

The amount of disk space required depends on how many packages are selected to install. It is recommended to have at least a 5G root partition (CRUX will use about 500MB-1GB, depending on whether you create separate partition for /usr, and other decisions you make in the setup process).

The amount of swap space required depends on several factors, including whether you intend to use hibernation or build new packages in RAM. For more information about how memory is handled by modern Linux kernels, please refer to In Defense of Swap.

Note: UEFI

For UEFI installation a GPT disklabel and an EFI system partition (ESP) are required in most cases. The ESP does not need to be very large (100MiB for example) and should be formatted with a FAT32 filesystem and flagged as bootable. When using UEFI the boot loader/manager will be installed in the ESP rather than the traditional method of installation into the Master Boot Record (MBR).

Note: MBR

If your BIOS does not support UEFI boot mode (or you have disabled it in favor of legacy MBR mode), then you do not need to create a separate small partition for EFI loaders or kernel images. One large partition for / is enough in such cases, and GRUB should be able to find a Linux kernel saved in the subdirectory /boot. But selecting SYSLINUX for your bootloader will require you to flag as bootable whichever partition contains syslinux.cfg. See Installing a Bootloader below for more details.

CRUX supports all the filesystems supported as root filesystems by the Linux kernel: btrfs, ext2, ext3, ext4, JFS, reiserfs and XFS. Further, it is highly recommended to separate the system data from user data, i.e. use a separate partition for /home (and possibly /var) since that will make your life a lot easier the day you want to upgrade, reinstall or remove your system.

Note

Make sure the appropriate userspace filesystem tools are installed. xfsprogs, btrfs-progs, jfsutils and reiserfsprogs can be found in the opt repository.

Note

Make sure that any BIOS Virus Protection option is DISABLED as this option may prevent fdisk from writing new partitions correctly.

Mount the partition on which you want to install this distribution.

 $ mount /dev/sd?? /mnt

If you want the installation to span more than one partition, mount those partitions as well. For example, if you want to have a different partition for /home or /var, then do:

 $ mkdir /mnt/var
 $ mount /dev/sd?? /mnt/var

Activate your swap partition(s).

 $ swapon /dev/sd??

Type setup to start the package installation script. The script will ask where you mounted your new root partition and which packages you want to install. Select the packages you wish to install; it is recommended to install all the packages from core.

Note: UEFI

If installing a UEFI system make sure to select the efibootmgr package from the opt collection during the package selection phase. efibootmgr would be installed automatically during dependency resolution if you chose grub2-efi as your boot loader, but it's a good idea to start your CRUX experience paying close attention to the administrative tools you'll be using.

Note: initramfs

If you plan to build a modular kernel, remember to select the dracut package from the opt collection.

After the packages have finished installing, the setup script will display an installation log. Make sure the last line in the log says “0 error(s)”.

If you missed or forgot to install certain packages, you can just mount the CRUX installation medium and use pkgadd to install them.

Screenshots of setup

Now it's time to compile your kernel and do basic system configuration. The kernel compilation requires that you “chroot” into your new CRUX installation.

Note

There is a shortcut command for creating the chroot environment: setup-chroot. This will execute all these steps at once.

 $ mount --bind /dev /mnt/dev
 $ mount --bind /tmp /mnt/tmp
 $ mount --bind /run /mnt/run
 $ mount -t proc proc /mnt/proc
 $ mount -t sysfs none /mnt/sys
 $ mount -t devpts -o noexec,nosuid,gid=tty,mode=0620 devpts /mnt/dev/pts
 (UEFI only) $ mount --bind /sys/firmware/efi/efivars /mnt/sys/firmware/efi/efivars
 $ chroot /mnt /bin/bash

Set the root password.

 $ passwd

Edit /etc/fstab to configure your filesystem(s). Editors vim and nano are available. The fstab installed by the setup script includes the most commonly-used mountpoints (commented out, of course), which can be used as a reference when customizing fstab for your partition scheme.

udev reads files in /sys/* and /proc/*. Make sure that those pseudo filesystems are enabled in your kernel configuration and available during system-startup. Also note that udev doesn't automatically mount /dev/pts. Terminal applications such as xterm(1) will not work if you forget to mount it. We highly recommend you check that your fstab contains the following line:

# dev> mountpoint>         type> options> dump> pass>
[..]
devpts  /dev/pts      devpts noexec,nosuid,gid=tty,mode=0620  0      0

Edit /etc/rc.conf to configure font, keyboard, timezone, hostname and services. See Section "Configuration Variables in /etc/rc.conf" for details about /etc/rc.conf.
Generate locales for your system. See section "Generating locales" for more information.
Edit /etc/rc.d/net, /etc/hosts and /etc/resolv.conf to configure your network (ip-address/gateway/hostname/domain/dns).
Go to /usr/src/linux-5.15.x, configure and compile a new kernel.

Note

Make sure to include drivers needed to bring up your root filesystem! Unless you also create an initramfs with dracut, these drivers must be built-in and not kernel modules. Look for sections titled "SCSI disk support", "partition types", and "disk controller" when configuring your kernel. For example:

CONFIG_SATA_AHCI=y
CONFIG_BLK_DEV_SD=y
CONFIG_EXT4_FS=y

Note: UEFI

If you disable your motherboard's CSM (compatibility support mode) and use anything other than GRUB as your bootloader, you must include an EFI stub in your compiled kernel. Check that .config has the line CONFIG_EFI_STUB = y before running make.

Note

The setup program installs a configuration file /usr/src/linux-5.15.55/.config which is a good starting point for a custom kernel, because all needed options, like CONFIG_DEVTMPFS, are enabled.

 $ cd /usr/src/linux-5.15.55
 $ make menuconfig
 $ make all
 $ make modules_install
 $ cp arch/x86/boot/bzImage /boot/vmlinuz-5.15.55
 $ cp System.map /boot

Note

The location /boot is the default path that GRUB will search for kernel images. If you use the kernel's EFI stub as your bootloader, then modify the cp commands to copy the kernel into a more appropriate location, e.g., the subdirectory EFI/BOOT under the mountpoint of the EFI system partition. The SYSLINUX bootloader on UEFI systems will also require a different location for the saved kernel; see SYSLINUX, in UEFI boot mode for the proper cp commands.

Note

A user-contributed example of a modular kernel configuration has been provided, if you want to boot a kernel that can tell you the exact set of modules needed for your particular hardware, or if you find it too daunting to navigate through the interface of the make menuconfig step. You can find this file, config-5.15.55-modular, under /crux/kernel/contrib on the installation media.

Installing a Bootloader

Unless you compiled your kernel to provide an EFI stub and have UEFI boot mode enabled in your BIOS, you will want to install a bootloader on your hard disk. Simple instructions are provided below for four distinct combinations of bootloader and BIOS setting. You are advised to choose one of the following options based on how your BIOS is configured and on how much you value “do-it-yourself” config files. The EFI stub option is presented in the Appendix, if you find it simpler to modify EFI variables rather than configuration files.

Note

LILO is no longer maintained in the official ports collections. If you were using LILO to boot CRUX 3.6 or earlier, you are advised to replace the boot sector with GRUB or SYSLINUX when upgrading to CRUX 3.7.

Note

Dual-booting with another operating system is not covered in this handbook. There are more extensive resources for such installations on the SYSLINUX wiki or the GRUB manual.

GRUB, in UEFI boot mode:

Install grub2 into the EFI system partition using a command like grub-install /boot/efi (replace /boot/efi with the location of the mounted ESP).
If efibootmgr was selected during the package selection phase, grub-install will automatically create a boot entry and make it active.
Run grub-mkconfig > /boot/grub/grub.cfg, or create a config file by hand.

GRUB, in legacy (non-UEFI) boot mode:

Install grub2 into the Master Boot Record using the command grub-install /dev/sd??.
Replace /dev/sd?? with the actual node of the device whose Master Boot Record you want to overwrite, eg., /dev/sda for the first SATA disk.
Run grub-mkconfig > /boot/grub/grub.cfg, or create a config file by hand.
grub-mkconfig's output can be altered by setting variables in a configuration file, /etc/default/grub. This file is NOT created by default and is not required, but is useful for customizing the video resolution and grub menu colors without crafting a grub.cfg by hand. For more information, see the GRUB manual at http://www.gnu.org/software/grub/manual/.

SYSLINUX, in UEFI boot mode:

Note

This configuration requires your kernel to be built with an EFI stub (see this developer's terse reply on the mailing list for more context). Double-check that .config contains the line CONFIG_EFI_STUB = y before proceeding.

Copy the bootloader code from /usr/share/syslinux to the mounted EFI system partition, specifically the subdirectory EFI/BOOT, which most UEFI implementations will search by default. (In this example the ESP is assumed to be mounted at /boot/efi)

 $ mkdir -p /boot/efi/EFI/BOOT
 $ cd /boot/efi/EFI/BOOT
 $ cp /usr/src/linux-5.15.55/arch/x86/boot/bzImage vmlinuz-5.15.55
 $ cp /usr/share/syslinux/efi64/ldlinux.e64 .
 $ cp /usr/share/syslinux/efi64/syslinux.efi BOOTX64.EFI
 $ cat <<EOF > syslinux.cfg
DEFAULT CRUX-3.7
PROMPT 1
TIMEOUT 10

LABEL CRUX-3.7
  SAY "Now booting into CRUX"
  KERNEL vmlinuz-5.15.55
  APPEND root=/dev/sda2 rw quiet

# End of config file
EOF

If you choose a different mountpoint for the EFI partition, adjust the mkdir and cd commands accordingly (UEFI itself is completely agnostic about mountpoints specified in /etc/fstab).
SYSLINUX interprets relative paths to the kernel in reference to the syslinux.cfg file, but cannot cross filesystem boundaries to find the kernel. Therefore the cp command from the kernel building step is not applicable when SYSLINUX is installed on the EFI mountpoint /boot/efi, and a different target directory appears in the cp commands above.
Saving a copy of syslinux.efi to the more generic name BOOTX64.EFI helps avoid the extra step of customizing boot entries with efibootmgr. See the Appendix for example efibootmgr commands to define and activate a custom boot entry.
On a computer that has booted other operating systems in the past, there might be lingering boot entries that the UEFI firmware will try to load before BOOTX64.EFI. After installing SYSLINUX, check the boot order reported by efibootmgr. You can either remove all existing entries using efibootmgr -O (forcing the firmware to search the default path \EFI\BOOT\BOOTX64.EFI), or define a custom boot order so that SYSLINUX is tried first.

SYSLINUX, in legacy (non-UEFI) boot mode:

Create a syslinux directory on a vfat or ext2/3/4-formatted partition, and populate it with the kernel and bootloader. Assuming that /boot is on a partition marked bootable, you can do:

 $ mkdir /boot/syslinux
 $ cd /boot/syslinux
 $ cp /usr/share/syslinux/ldlinux.c32 .
 $ extlinux --install /boot/syslinux
 $ [ -e ../vmlinuz-5.15.55 ] || cp /usr/src/linux-5.15.55/arch/x86/boot/bzImage ../vmlinuz-5.15.55
 $ cat <<EOF > syslinux.cfg
DEFAULT CRUX-3.7
PROMPT 1
TIMEOUT 10

LABEL CRUX-3.7
  SAY "Now booting into CRUX"
  KERNEL ../vmlinuz-5.15.55
  APPEND root=/dev/sda2 rw quiet

# End of config file
EOF

Replacing /boot/syslinux in the above commands with /boot/efi/EFI/BOOT will make it easy to toggle between legacy and UEFI boot modes.
SYSLINUX interprets relative paths to the kernel in reference to the syslinux.cfg file, although it cannot cross filesystem boundaries to find the kernel. On a legacy system with no dedicated EFI partition, the cp command from the kernel building step should put the kernel in a reachable path, hence the cp command above does not need to run if the kernel was already copied to the expected place.
Finally, overwrite the contents of the master boot record (MBR) with the binary blob appropriate for your partition type (gptmbr.bin in the case of GPT/GUID partitioning, or mbr.bin in the case of DOS partitioning).

 $ PTYPE=$(fdisk -l /dev/sda | grep "^Disklabel type" | cut -d " " -f3)
 $ [ "$PTYPE" = "gpt" ] && BINBLOB=gptmbr.bin || BINBLOB=mbr.bin
 $ dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/$BINBLOB of=/dev/sda

More information about UEFI and other boot loader/manager options can be found in the CRUX wiki at https://crux.nu/Wiki/UEFI.

Remove the CRUX installation media from your computer and reboot from harddisk.

Upgrading From Optical Medium or Removable Flash Drive

Download the CRUX ISO image (crux-3.7.iso). To ensure that the download was successful, examine its checksum.

 $ shasum -a 256 crux-3.7.iso

The ISO image is bootable. After making sure that your BIOS gives priority to optical drives or flash drives, just insert the newly-written DVD or removable flash drive and reboot your computer. Press Enter at the boot prompt (you might have to adjust the root= parameter, depending on your hardware configuration).
You will be logged in as root on tty1 (root has no password set).
Mount your CRUX root partition.

 $ mount /dev/sd?? /mnt

If your installation spans over more than one partition, mount these partitions as well. For example, if you have a different partition for /var, then do:

 $ mount /dev/sd?? /mnt/var

Activate your swap partition(s).

 $ swapon /dev/sd??

Type setup to start the package installation script. The script will ask you where you mounted your root partition and which packages you want to upgrade.
- Upgrading packages that were linked to soft dependencies outside core and opt will replace them with packages that were only linked to dependencies in core and opt. You will have to rebuild such packages if you want to retain the functionality of your existing CRUX system.
- On the other hand, if it's been a while since you refreshed the ports tree on your existing CRUX system and rebuilt the outdated packages, an upgrade of all packages will save you from trouble (e.g. if some library introduced breaking changes).

Note

The setup script uses the /etc/pkgadd.conf of the target system to determine which files to upgrade, and which files not to upgrade. The files that are not upgraded are put in /var/lib/pkg/rejected/ (see the section "Upgrading a Package" for advice on how to resolve such file conflicts).

When the setup script has upgraded the selected packages an upgrade log will be displayed. Make sure the last line in the log says “0 error(s)”. If you missed/forgot to install certain packages, you can just mount the CRUX installation media and use pkgadd to install them (e.g. pkgadd /mnt/crux/opt/package#1.0-1.pkg.tar.gz).

The already-built kernel from your previous CRUX installation might not be compatible with the newly-upgraded linux-firmware package. To be safe, you're advised to “chroot” into your CRUX installation and compile a fresh kernel from the latest source tree.

Note

There is a shortcut command for creating the chroot environment: setup-chroot. This will execute all these steps at once.

 $ mount --bind /dev /mnt/dev
 $ mount --bind /tmp /mnt/tmp
 $ mount --bind /run /mnt/run
 $ mount -t proc proc /mnt/proc
 $ mount -t sysfs none /mnt/sys
 $ mount -t devpts -o noexec,nosuid,gid=tty,mode=0620 devpts /mnt/dev/pts
 (UEFI only) $ mount --bind /sys/firmware/efi/efivars /mnt/sys/firmware/efi/efivars
 $ chroot /mnt /bin/bash

Generate locales for your system. See the section Generating locales for more information.
Go to /usr/src/linux-5.15.x, configure and compile a new kernel. See the kernel building step for some reminders of how that is done.
Adjust /etc/fstab to reflect any changes made to your partition scheme since your earlier installation of CRUX. In particular, /var/run should not appear as a mountpoint, since this is now a symlink to /run starting with CRUX 3.7. See the notes about fstab in the previous section for other general recommendations.

Finish the upgrade by Installing a Bootloader, and then you should be able to login to your upgraded CRUX system after rebooting.

CRUX : Home

Installing CRUX

Supported Hardware / Requirements

Installing From Optical Medium or Removable Flash Drive

Installing a Bootloader

GRUB, in UEFI boot mode:

GRUB, in legacy (non-UEFI) boot mode:

SYSLINUX, in UEFI boot mode:

SYSLINUX, in legacy (non-UEFI) boot mode:

Upgrading From Optical Medium or Removable Flash Drive