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 768MB system memory is required to install CRUX from a CD-ROM or removable flash drive. It is possible to perform a custom chroot installation with only 16MB of RAM.
The kernel used during installation, i.e. when booting from the CRUX ISO image (El Torito), is compiled with the following disk controllers and USB support:
||cellpadding="3" rules="all" frame="box"
||! Subsystem ||! Driver(s) included in bootkernel ||
||USB||EHCI HCD (USB 2.0) support, UHCI (Intel PIIX4, VIA, ...) support, OHCI (Compaq, iMacs, OPTi, SiS, ALi, ...) support, USB Mass Storage support, USB Human Interface Device (full HID) support, HID input layer support||
In order to install CRUX, your disk controller must be present in the list above. If your hardware is not supported or you have other problems installing CRUX, you might find a solution in the [[https://crux.nu/Wiki/HomePage | CRUX wiki]].
!! [[#InstallingFromCD-ROM]] Installing From optical medium or removable flash drive
Download the CRUX ISO image (%fn%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 %fn%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??
->%lfloat% http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''Please keep in mind that SATA harddisks are usually detected as SCSI devices. The first SATA disk is called ''%fn%/dev/sda%%'' instead of ''%fn%/dev/hda%%''. For more information about harddisk naming conventions please refer to the [[http://www.tldp.org/HOWTO/Partition/devices.html | 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 1G root partition (CRUX will use about 200MB-500MB, depending on your configuration).
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 [[https://chrisdown.name/2018/01/02/in-defence-of-swap.html | In Defense of Swap]].
->%lfloat% http://crux.nu/doc/images/note.png
'''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).''
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 %fn%/home%% (and possibly %fn%/var%%) since that will make your life a lot easier the day you want to upgrade, reinstall or remove your system.
->%lfloat% http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''Make sure the appropriate userspace filesystem tools are installed. xfsprogs, btrfs-progs, jfsutils and reiserfsprogs can be found in the opt repository.''
->%lfloat% http://crux.nu/doc/images/note.png
'''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 %fn%/home%% or %fn%/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 %fn%core%%.
->%lfloat% http://crux.nu/doc/images/note.png
'''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.
[[http://crux.nu/doc/screenshots.html | 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.
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''There is a shortcut command for creating the chroot environment: %fn%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 %fn%/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'' %fn%/sys/*%% ''and'' %fn%/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''
%fn%/dev/pts%%. ''Terminal applications such as'' '''xterm(1)''' ''will not work if you forget to mount it. ''We highly
recommend you check that your %fn%fstab%% contains the following line:''
* Edit %fn%/etc/rc.conf%% to configure font, keyboard, timezone, hostname and services. See Section [[#ConfigurationVariables | "Configuration Variables in /etc/rc.conf"]] for details about %fn%/etc/rc.conf%%.
* Generate locales for your system. See section [[#LocaleGeneration| "Generating locales"]] for more information.
* Edit %fn%/etc/rc.d/net%%, %fn%/etc/hosts%% and %fn%/etc/resolv.conf%% to configure your network (ip-address/gateway/hostname/domain/dns).
* Go to %fn%/usr/src/linux-5.15.x%%, configure and compile a new kernel.
->%lfloat%http://crux.nu/doc/images/note.png
'''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
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->The setup program installs a configuration file
%fn%/usr/src/linux-5.15.x/.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.x
$ make menuconfig
$ make all
$ make modules_install
[[#BootLoader-Setup]] Installing a Bootloader
-->If you plan to use syslinux as your bootloader, skip ahead to [[#syslinux-install | "syslinux installation notes"]]
in the appendix of this document. Otherwise, proceed with '''grub-install''' according to the instructions below.
First place a copy of the newly-compiled kernel in a standard location,
named so that it will be detected by %fn%grub-mkconfig%%. For example,
%fn%grub-mkconfig%% will be able to recognize '''/boot/vmlinuz-5.x''' as
a valid kernel image, but '''NOT''' a file named '''/boot/linuxkernel-5.x'''.
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/]].
* For legacy boot (not UEFI):
** 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.
* For UEFI booting:
** Install grub2 into the ESP using the command '''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.
** Check that the ESP now contains the grub bootloader, and that an entry
for the grub bootloader now appears in the EFI variables.
[@
$ ls /boot/efi/
$ efibootmgr
@]
-->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 DVD-ROM or removable flash drive
Download the CRUX ISO image (%fn%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 %fn%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).
* 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 %fn%/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. To avoid running into trouble (e.g. a new version of some library isn't 100% backwards compatible), it is a good idea to upgrade all packages.
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''The '''setup''' script uses the %fn%/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 %fn%/var/lib/pkg/rejected/%% (Section [[#UpgradingaPackage | "Upgrading a Package"]]).''
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 %fn%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.
->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->''There is a shortcut command for creating the chroot environment: %fn%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 section [[#LocaleGeneration| "Generating locales"]] for more information.
* Go to %fn%/usr/src/linux-5.15.x%%, configure and compile a new kernel.
