Documentation/crux-wiki/Handbook3-7-Install

! 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 the following disk controllers and USB support: 
 
||cellpadding="3" rules="all" frame="box"
||! Subsystem ||! Driver(s) included in bootkernel ||
||PATA/IDE||ALi, AMD/Nvidia, ARTOP 6210/6260, ATI, CMD64x, CS5510/30/35/36, Cypress CY82C693, EFAR SLC90E66, HPT 34x/36x/37x, ITE 8211/12/13, JMicron, Marvell, NETCELL Revolution, Ninja32/Delkin, Nat Semi NS8741x, Intel PIIX/SCH/MPIIX, OPTI FireStar/621x, Promise, RADISYS 82600, SC1200, SERVERWORKS OSB4/CSB5/CSB6/HT1000, CMD / Silicon Image 680, SiS, Compaq Triflex, VIA, Winbond SL82C105, ISA Plug & Play, PC Tech RZ1000, Generic||
||SATA||AHCI, Intel ESB/ICH/PIIX, Initio 162x, Silicon Image/Silicon Image 31xx, Pacific Digital ADMA/QStor, Promise SX4/TX2/TX4, Marvell, Nvidia, SiS 180/96x, Broadcom/ServerWorks/Apple K2, ULi, VIA, Vitesse VSC7174/Intel 31244||
||SCSI/SAS||3Ware 5/6/7/8/9xxx, HP Smart Array, 7000FASST, ACARD, Adaptec AHA15xx/28xx, Adaptec AACRAID, Adaptec AIC7xxx/79xx/94xx, Adaptec I20, Marvell 88SE64xx/94xx, Advansys, Always IN2000, ARECA 11xx/12xx/13xx/16xx, LSI Logic New/Legacy/MegaRAID/MPT, HighPoint RocketRAID 3xxx/4xxx, BusLogic, VMware PVSCSI, DMX3191D, DTC 3x80, EATA, Future Domain 16xx/Adaptec AHA2920A, Intel/ICP, IBM ServeRAID/Power Linux, Initio 9100U/INI-A100U2W, NCR53c406a, Promise SuperTrak EX, SYM53C8xx, PAS16, Qlogic FAS, Qlogic QLA 1xxxx/2xxx, Qlogic ISP 4xxx/82xx, Emulex LightPulse FC, Symbios 53c416, Tekram DCxxx, Trantor Txxx, UltraStor, UltraStor 14F/34F||
||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 5G root partition (CRUX will use
about 500MB-1GB, depending on whether you create separate partition for %fn%/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 [[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).
 
'''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 %fn%%/%%
is enough in such cases, and GRUB should be able to find a Linux kernel
saved in the subdirectory %fn%/boot%%. But selecting SYSLINUX for your
bootloader will require you to flag as bootable whichever partition contains
%fn%syslinux.cfg%%. See [[#syslinux-install | "SYSLINUX installation" ]] in
the Appendix for 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 %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:''
 
-> [@# dev> mountpoint>         type> options> dump> pass>
[..]
devpts  /dev/pts      devpts noexec,nosuid,gid=tty,mode=0620  0      0
@]
 
* 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.
 
[[#KernelBuildingNotes]]
->%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.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-1
 $ cp System.map /boot

->%lfloat%http://crux.nu/doc/images/note.png
'''Note'''[[]]
->The location %fn%/boot%% is the default path that GRUB will 
search for kernel images. If you use SYSLINUX or the kernel itself as
your bootloader, then modify the @@cp@@ commands to copy the kernel into a
more appropriate location, e.g., the subdirectory %fn%EFI/BOOT%% under the
mountpoint of the EFI system partition.

->%lfloat%http://crux.nu/doc/images/note.png
'''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, %fn%config-5.15.55-modular%%, under %fn%/crux/kernel/contrib%% on
the installation media.
 
[[#BootLoader-Setup]] !!! 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
important you consider hand-editable configuration files. The EFI stub
option is presented in the [[#EFI-stub-install|Appendix]], if you find it
simpler to modify EFI variables rather than configuration files.

* GRUB, in UEFI boot mode:
** Install grub2 into the EFI system partition 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.
** Run @@grub-mkconfig > /boot/grub/grub.cfg@@, or 
[[#grubcfg-manually|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 
[[#grubcfg-manually|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:
** Copy the bootloader code from %fn%/usr/share/syslinux%% to the mounted
EFI system partition, specifically the subdirectory %fn%EFI/BOOT%%, which
most UEFI implementations will search by default. (In this example the ESP
is assumed to be mounted at %fn%/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
@]
** Saving a copy of %fn%syslinux.efi%% to the more generic name
%fn%BOOTX64.EFI%% helps avoid the extra step of customizing boot entries
with @@efibootmgr@@.
** 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 %fn%/etc/fstab).
** Proceed to [[#syslinux-cfg|write a syslinux configuration file]], keeping
in mind where you saved the kernel image.
* 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 %fn%/boot%% is
on a partition marked bootable''', you can do:
[@
 $ mkdir /boot/syslinux
 $ cd /boot/syslinux
 $ cp /usr/share/syslinux/ldlinux.c32 .
 $ cp /usr/src/linux-5.15.55/arch/x86/boot/bzImage ../vmlinuz-5.15.55
 $ extlinux --install /boot/syslinux
@]
** Replacing %fn%/boot/syslinux%% in the above commands with
%fn%/boot/efi/EFI/BOOT%% will make it easy to toggle between legacy and UEFI
boot modes.
** Next, overwrite the contents of the master boot record (MBR) with the
binary blob appropriate for your partition type (%fn%gptmbr.bin%% in the
case of GPT/GUID partitioning, or %fn%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
@]
** Proceed to write a syslinux configuration file, keeping in mind where you
saved the kernel image.

[[#syslinux-cfg]] Template for a SYSLINUX configuration file

If you select SYSLINUX as your bootloader, you need to tell it where
to find your kernel and the root filesystem.
SYSLINUX interprets relative paths to the kernel in reference to the
%fn%syslinux.cfg%% file. In the template below, suppose @@extlinux@@
assigned %fn%/boot/syslinux%% as the preferred location for
%fn%syslinux.cfg%%, and a copy of the kernel was saved in the parent
directory as %fn%/boot/vmlinuz-5.15.55%%. The relative path therefore
begins with %fn%../% .

[@
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
EOF
@]

-->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 @@&#8220;0
error(s)&#8221;@@. 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 &#8220;chroot&#8221; 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. See the
[[#KernelBuildingNotes| kernel building notes]] from the "Install" section
for some reminders of how that is done.

* Adjust %fn%/etc/fstab%% to reflect any changes made to your partition
scheme since your earlier installation of CRUX. In particular,
%fn%/var/run%% should not appear as a mountpoint, since this is now a
symlink to %fn%/run%% starting with CRUX 3.7. See the notes about
%fn%fstab%% in the [[#InstallingFromCD-ROM| "Installing"]] section for other
general recommendations.
 
Finish the upgrade by [[#BootLoader-Setup | installing a bootloader]], and
then you should be able to login to your upgraded CRUX system after
rebooting.