HANDBOOK FOR CRUX 3.4 1. Preface 2.1. What is CRUX? 2.2. Why use CRUX? 2.3. License 2.3.1. Packages 2.3.2. Build Scripts 2.3.3. NO WARRANTY 3. Installing CRUX 3.1. Supported Hardware / Requirements 3.2. Installing From CD-ROM or removable flash drive 3.3. Upgrading From CD-ROM or removable flash drive 4. The Package System 4.1. Introduction 4.2. Using the Package System 4.2.1. Installing a Package 4.2.2. Upgrading a Package 4.2.3. Removing a Package 4.2.4. Querying the Package Database 4.3. Package management frontend: prt-get 4.4. Creating Packages 4.5. Adjusting/Configuring the Package Build Process 4.6. Package Guidelines 4.6.1. General 4.6.2. Directories 4.6.3. Remove Junk Files 4.6.4. Pkgfile 4.6.4.1. Pkgfile header 5. The Ports System 5.1. Introduction 5.1.1. What is a Port? 5.1.2. What is the Ports System? 5.1.3. Port collections 5.1.3.1. The official collections 'core', 'opt', 'xorg' and 'compat-32' 5.1.3.2. The user contributed collection 'contrib' 5.1.3.3. The individual collections from CRUX users 5.2. Using the Ports System 5.2.1. Synchronizing Your Local Ports Structure 5.2.2. Listing Local Ports 5.2.3. Listing Version Differences 5.2.4. Building and Installing Packages 5.2.5. Enabling the 'contrib' collection 5.2.6. Enabling the 'compat-32' collection 5.2.7. Additional tools 5.2.7.1. Building ports as unprivileged user 5.2.7.2. Useful scripts 6. Configuration 6.1. Initialization Scripts 6.1.1. Runlevels 6.1.2. Layout 6.1.3. Configuration Variables in /etc/rc.conf 6.1.4. Generating locales 6.1.5. Network Configuration 6.2. Passwords 6.3. Upgrading the Kernel 7. Appendix 7.1. Troubleshooting 7.2. GRUB installation 7.2.1. Precaution 7.2.2. Installation 7.2.3. Configuration file 7.2.3.1. Automatic creation 7.2.3.2. Manual creation 1. Preface Per Lidén wrote this handbook. RobertMcMeekin converted it to DocBook, the CRUX team made a Wiki version. Numerous others have given feedback and improvement suggestions. 2. Introduction 2.1. What is CRUX? CRUX is a lightweight Linux distribution for the x86-64 architecture targeted at experienced Linux users. The primary focus of this distribution is "keep it simple", which it reflects in a simple tar.gz-based package system, BSD-style initscripts, and a relatively small collection of trimmed packages. The secondary focus is utilization of new Linux features and recent tools and libraries. CRUX also has a ports system which makes it easy to install and upgrade applications. 2.2. Why use CRUX? There are many Linux distributions out there these days, so what makes CRUX any better than the others? The choice of distribution is a matter of taste, really. Here are a few hints about the tastes and goals of the people behind CRUX. CRUX is made with simplicity in mind from beginning to end. Making it easy to create new and update old packages is essential; updating a package in CRUX is often just a matter of typing pkgmk -d -u. The usage of ports helps keep your packages up-to-date; not the latest bleeding-edge-alpha version, but the latest stable version. Other features include creating packages optimized for your processor, eg. by compiling with -march=x86-64, and avoiding cluttering the filesystem with files you'll never use, eg. /usr/doc/*, etc. If you need more information about a specific program, other than information found in the man-page, Google usually knows all about it. Finally, it strives to use new features as they become available, as long as they are consistent with the rest of the goals. In short, CRUX might suit you very well if you are: • A somewhat experienced Linux user who wants a clean and solid Linux distribution as the foundation of your installation. • A person who prefers editing configuration files with an editor to using a GUI. • Someone who does not hesitate to download and compile programs from the source. Note If you are using CRUX we highly recommend to subscribe to our low volume mailing list, because security updates and updates that need user action are announced there . 2.3. License 2.3.1. Packages Since CRUX is a Linux distribution, it contains software written by a lot of different people. Each software package comes with its own license, chosen by its author(s). To find out how a particular package is licensed, have a look at its source code. 2.3.2. Build Scripts All package build scripts in CRUX (in package categories core, opt, xorg, and compat-32) are Copyright © 2000-2018 by Per Lidén and the CRUX development team, and licensed through the GNU General Public License. 2.3.3. NO WARRANTY CRUX is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Use it at YOUR OWN RISK. 3. Installing CRUX 3.1. 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 192MB system memory is required to install CRUX from 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:. ┌─────────┬──────────────────────────────────────────────────────────────┐ │Subsystem│ Driver(s) included in bootkernel │ ├─────────┼──────────────────────────────────────────────────────────────┤ │ │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 │ │PATA/IDE │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 │ ├─────────┼──────────────────────────────────────────────────────────────┤ │ │AHCI, Intel ESB/ICH/PIIX, Initio 162x, Silicon Image/Silicon │ │SATA │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 │ ├─────────┼──────────────────────────────────────────────────────────────┤ │ │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, │ │SCSI/SAS │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 │ ├─────────┼──────────────────────────────────────────────────────────────┤ │ │EHCI HCD (USB 2.0) support, UHCI (Intel PIIX4, VIA, ...) │ │USB │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 CRUX wiki. 3.2. Installing From CD-ROM or removable flash drive • Download the CRUX ISO image (crux-3.4.iso). To ensure that the download was successful, examine its checksum using md5sum. $ md5sum crux-3.4.iso Compare the output with the file crux-3.4.md5, 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 CD or writing it to a removable flash drive. • The ISO image is bootable, just insert the newly-written CD 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 automatically logged in as as root on tty1 (root has no password set). • Create (if necessary) and format the partition(s) you want CRUX to be installed on. $ 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 1G root partition (CRUX will use about 200MB-500MB, depending on your configuration). 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 /home (and possibly /var) since that will make your life a lot easier the day you want to upgrade/reinstall/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 and grub2-efi packages from the opt collection during the package selection phase. 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/forgot to install certain packages, you can just mount the CRUX installation media 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 -t proc proc /mnt/proc $ mount -t sysfs none /mnt/sys $ chroot /mnt /bin/bash • Set the root password. $ passwd • Edit /etc/fstab to configure your filesystem(s). Editors vim and nano are available. • 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-4.14.x, configure and compile a new kernel. Note Make sure to include drivers needed to bring up your root filesystem! Such as "SCSI disk support", filesystem and disk controller. For example: • CONFIG_SATA_AHCI=y • CONFIG_BLK_DEV_SD=y • CONFIG_EXT4_FS=y Note The setup program installs a configuration file /usr/src/linux-4.14.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-4.14.x $ make menuconfig $ make all $ make modules_install $ cp arch/x86/boot/bzImage /boot/vmlinuz $ cp System.map /boot • If installing a BIOS-based system: • Edit /etc/lilo.conf to boot the kernel you just compiled and run lilo to make the new system bootable. If you plan to use GRUB (which is included in the ISO) make sure you read the installation notes in the appendix of this document. • If installing a UEFI-based system: • Install grub2 into the ESP using the command grub-install /boot/efi. • Generate a grub2 configuration file using the command grub-mkconfig -o /boot/grub/grub.cfg. 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. 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. 3.3. Upgrading From CD-ROM or removable flash drive • Download the CRUX ISO image (crux-3.4.iso). To ensure that the download was successful, examine its checksum using md5sum. $ md5sum crux-3.4.iso Compare the output with the file crux-3.4.md5, 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 CD or writing it to a removable flash drive. • The ISO image is bootable, just insert the newly-written CD 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 automatically logged in as 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. 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. Note The setup script uses the /etc/pkgadd.conf of the target system to determine which files to upgrade, and which files to not upgrade. The files that are not upgraded are put in /var/lib/pkg/rejected/ (Section "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). • Now it's time to compile your kernel. The kernel compilation requires that you “chroot” into your 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 -t proc proc /mnt/proc $ mount -t sysfs none /mnt/sys $ chroot /mnt /bin/bash • Generate locales for your system. See section "Generating locales" for more information. • Go to /usr/src/linux-4.14.x, configure and compile a new kernel. • Adjust /etc/fstab if needed. 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 your fstab file:'' # [..] devpts /dev/pts devpts noexec,nosuid,gid=tty,mode=0620 0 0 • If installing a BIOS-based system: • Edit /etc/lilo.conf to boot the kernel you just compiled and run lilo to make the new system bootable. If you plan to use GRUB (which is included in the ISO) make sure you read the installation notes in the appendix of this document. • If installing a UEFI-based system: • Install grub2 into the ESP using the command grub-install /boot/efi. • Generate a grub2 configuration file using the command grub-mkconfig -o /boot/grub/grub.cfg. 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. 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 CD-ROM from your drive and reboot from harddisk. 4. The Package System 4.1. Introduction The package system (pkgutils) is made with simplicity in mind, where all packages are plain tar.gz files (i.e. without any kind of meta data). Packages follow the naming convention #-.pkg.tar.gz, where is the name of the program, is the version number of the program, and is the version number of the package. The pkg.tar.gz extension is used (instead of just tar.gz) to indicate that this is not just any tar.gz file, but a tar.gz that is meant to be installed using pkgadd. This helps distinguish packages from other tar.gz files. Note that pkgmk nowadays supports additional compression schemes like bzip2 with the tar.bz2 extension or XZ ending with tar.xz. pkgadd(8), pkgrm(8), pkginfo(8), and pkgmk(8) are the package management utilities. With these utilities you can install, uninstall, inspect, make packages, or query the package database. When a package is installed using pkgadd a new record is added to the package database (stored in /var/lib/pkg/db). The basic package system does not have any kind of dependency checking, thus it will not warn you if you install a package that requires other packages to be installed. The included prt-get tool, however, does support dependencies. The following sections will in short describe how to use the package utilities. Additional information about these utilities can be found on their respective man page. 4.2. Using the Package System 4.2.1. Installing a Package Installing a package is done by using pkgadd. This utility requires at least one argument, the package you want to install. Example: $ pkgadd bash#2.05-1.pkg.tar.gz When installing a package the package manager will ensure that no previously installed files are overwritten. If conflicts are found, an error message will be printed and pkgadd will abort without installing the package. The error message will contain the names of the conflicting files. Example: $ pkgadd bash#2.05-1.pkg.tar.gz bin/sh usr/man/man1/sh.1.gz pkgadd error: listed file(s) already installed (use -f to ignore and overwrite) To force the installation and overwrite the conflicting files, you can use the option -f (or --force). Example: $ pkgadd -f bash#2.05-1.pkg.tar.gz The package system allows a file to be owned by exactly one package. When forcing an installation the ownership of the conflicting files will be transferred to the package that is currently being installed. Directories can however be owned by more then one package. Warning It is often not a good idea to force the installation unless you really know what you are doing. If a package conflicts with already installed files it could be a sign that the package is broken and installs unexpected files. Use this option with extreme care, preferably not at all. As earlier, the package file itself does not contain any meta data. Instead, the package manager uses the package filename to determine the package name and version. Thus, when installing a package file named bash#2.05-1.pkg.tar.gz, the package manager will interpret this as a package named bash at version 2.05-1. If pkgadd is unable to interpret the filename (e.g. # is missing or the filename does not end with .pkg.tar.gz) an error message will be printed and pkgadd will abort without installing the package. 4.2.2. Upgrading a Package Upgrading a package is done using pkgadd with the -u option. Example: $ pkgadd -u bash#2.05-1.pkg.tar.gz This will replace the previously installed bash package with the new one. If you have not previously installed bash, pkgadd will print an error message. The package system does not care about the version number of the package in that you can “upgrade” version 2.05-1 with version 2.04-1 (or even with version 2.05-1 itself). The installed package will be replaced with the specified package. Upgrading a package is equivalent to executing pkgrm followed by pkgadd with one (big) exception. When upgrading a package (with pkgadd -u) you have the option to prevent some of the already installed files from getting replaced. This is typically useful when you want to preserve configuration and log files. When executing pkgadd the file /etc/pkgadd.conf will be read. This file can contain rules describing how pkgadd should behave when doing upgrades. A rule is built out of three fragments; event, pattern and action. The event describes in what kind of situation this rule applies. Currently only one type of event is supported, that is UPGRADE. The pattern is a filename pattern expressed as a regular expression and the action applicable to the UPGRADE event is YES or NO. More than one rule of the same event type is allowed, in which case the first rule will have the lowest priority and the last rule will have the highest priority. Example: # # /etc/pkgadd.conf: pkgadd(8) configuration # UPGRADE ^etc/.*$ NO UPGRADE ^var/log/.*$ NO UPGRADE ^etc/X11/.*$ YES UPGRADE ^etc/X11/xorg.conf$ NO # End of file The above example will cause pkgadd to never upgrade anything in /etc/ or /var/log/ (subdirectories included), except files in /etc/X11/ (subdirectories included), unless it is the file /etc/X11/xorg.conf. The default rule is to upgrade everything, rules in this file are exceptions to that rule. Note A pattern should never contain an initial “/” since you are referring to the files in the package, not the files on the disk. If pkgadd finds that a specific file should not be upgraded, it will install it under /var/lib/pkg/rejected/. Files in this directory are never added to the package database. The user is then free to examine, use and/or remove that file manually. Another option is to use rejmerge. For each rejected file found in /var/lib/pkg/rejected/, rejmerge will display the difference between the installed version and the rejected version. The user can then choose to keep the installed version, upgrade to the rejected version or perform a merge of the two. Example (using the above /etc/pkgadd.conf): $ pkgadd -u bash#2.05-1.pkg.tar.gz pkgadd: rejecting etc/profile, keeping existing version $ ls /var/lib/pkg/rejected/ etc/ $ ls /var/lib/pkg/rejected/etc/ profile 4.2.3. Removing a Package Removing a package is done by using pkgrm. This utility requires one argument, the name of the package you want to remove. Example: $ pkgrm bash Warning This will remove all files owned by the package, no questions asked. Think twice before doing it and make sure that you did not misspell the package name since that could remove something completely different (e.g. think about what could happen if you misspelled glib as glibc). 4.2.4. Querying the Package Database Querying the package database is done using pkginfo. This utility has a few options to answer different queries. ┌───────────────────────┬────────────────────────────────────────────────┐ │ Option │ Description │ ├───────────────────────┼────────────────────────────────────────────────┤ │-i, --installed │List installed packages and their version. │ ├───────────────────────┼────────────────────────────────────────────────┤ │-l, --list package|file│List files owned by the specified package or │ │ │contained in file │ ├───────────────────────┼────────────────────────────────────────────────┤ │-o, --owner pattern │List owner(s) of file(s) matching pattern. │ └───────────────────────┴────────────────────────────────────────────────┘ Examples: $ pkginfo -i audiofile 0.2.3-1 autoconf 2.52-1 automake 1.5-1 <...> xmms 1.2.7-1 zip 2.3-1 zlib 1.1.4-1 $ pkginfo -l bash bin/ bin/bash bin/sh etc/ etc/profile usr/ usr/man/ usr/man/man1/ usr/man/man1/bash.1.gz usr/man/man1/sh.1.gz $ pkginfo -l grep#2.5-1.pkg.tar.gz usr/ usr/bin/ usr/bin/egrep usr/bin/fgrep usr/bin/grep usr/man/ usr/man/man1/ usr/man/man1/egrep.1.gz usr/man/man1/fgrep.1.gz usr/man/man1/grep.1.gz $ pkginfo -o bin/ls e2fsprogs usr/bin/lsattr fileutils bin/ls modutils sbin/lsmod 4.3. Package management frontend: prt-get To address the different requirements towards package management in CRUX, a number of users started discussion about an advanced package management frontend to pkgutils, with dependency handling and support for large install transactions. The result of this community effort is prt-get, a tool which provides a number of features on top of pkgutils while keeping pkgutils' original character and power. Its main features are • Dependency handling • Build logging • Powerful search and query functionality Nowadays prt-get is an official project and tool of the CRUX project. A full description can be found in the manual and quick start of prt-get. 4.4. Creating Packages Creating a package is done using pkgmk. This utility uses a file called Pkgfile, which contains information about the package (such as name, version, etc) and the commands that should be executed in order to compile the package in question. To be more specific, the Pkgfile file is actually a bash(1) script, which defines a number of variables (name, version, release and source) and a function (build). Below is an example of what a Pkgfile file might look like. The example shows how to package the grep(1) utility. Some comments are inserted for explanation. # Specify the name of the package. name=grep # Specify the version of the package. version=2.4.2 # Specify the package release. release=1 # The source(s) used to build this package. source=(ftp://ftp.ibiblio.org/pub/gnu/$name/$name-$version.tar.gz) # The build() function below will be called by pkgmk when # the listed source files have been unpacked. build() { # The first thing we do is to cd into the source directory. cd $name-$version # Run the configure script with desired arguments. # In this case we want to put grep under /usr/bin and # disable national language support. ./configure --prefix=/usr --disable-nls # Compile. make # Install the files, BUT do not install it under /usr, instead # we redirect all the files to $PKG/usr by setting the DESTDIR # variable. The $PKG variable points to a temporary directory # which will later be made into a tar.gz-file. Note that the # DESTDIR variable is not used by all Makefiles, some use prefix # and others use ROOT, etc. You have to inspect the Makefile in # question to find out. Some Makefiles do not support redirection # at all. In those cases you will have to create a patch for it. make DESTDIR=$PKG install # Remove unwanted files, in this case the info-pages. rm -rf $PKG/usr/info } In reality you do not include all those comments, thus the real Pkgfile for grep(1) looks like this: # Description: GNU grep, egrep and fgrep # URL: http://www.gnu.org/software/grep/grep.html # Maintainer: Per Lidén, per at fukt dot bth dot se name=grep version=2.4.2 release=1 source=(ftp://ftp.ibiblio.org/pub/gnu/$name/$name-$version.tar.gz) build() { cd $name-$version ./configure --prefix=/usr --disable-nls make make DESTDIR=$PKG install rm -rf $PKG/usr/info } Note The build() function in the example above is just an example of how grep is built. The contents of the function can differ significantly if the program is build in some other way, e.g. does not use autoconf. When the build() function has been executed, the $PKG directory will be made into a package named #-.pkg.tar.gz. Before the package creation is completed, pkgmk will check the content of the package against the .footprint file. If this file does not exist, it will be created and the test will be skipped. The .footprint file will contain a list of all files that should be in the package if the build was successful or a list of all the files that were installed in $PKG (if the .footprint did not already exist). If there is a mismatch the test will fail and an error message will be printed. You should not write the .footprint file by hand. Instead, when a package has been upgraded and you need to update the contents of the .footprint file you simply do pkgmk -uf. This test ensures that a rebuild of the package turned out as expected. If the package built without errors it's time to install it by using pkgadd and try it out. I highly recommend looking at the Pkgfile in another package(s), since looking at examples is a great way to learn. Note Please see the PortGuidelines for additional information.'' 4.5. Adjusting/Configuring the Package Build Process Many settings pertaining to the package build process can be adjusted by editing the pkgmk(8) configuration file /etc/pkgmk.conf. Some of these configurable settings include: • CFLAGS, CXXFLAGS - these settings control optimization and architecture options for package compiles. It is best NOT to change these unless you absolutely know what you're doing! • PKGMK_SOURCE_MIRRORS - this setting defines locations from which pkgmk will attempt to fetch source archives • PKGMK_SOURCE_DIR - this setting defines where pkgmk will store (if downloading) and use source archives when building • PKGMK_PACKAGE_DIR - this setting defines where pkgmk will create package files once the build process is complete • PKGMK_WORK_DIR - this setting defines a work area pkgmk will use to build the package Here are some examples: PKGMK_SOURCE_MIRRORS=(http://fileserver.intranet/crux/sources/) This setting instructs pkgmk to attempt to fetch all source archives from http://fileserver.intranet/crux/sources/ before falling back to the source URL specified in the Pkgfile. Multiple URLS can be separated by spaces. PKGMK_SOURCE_DIR="/usr/ports/srcfiles" This example instructs pkgmk to store and find source archives in /usr/ports/srcfiles. An example benefit of this setup would be the ability to store /usr/ports/srcfiles on an NFS server on your local network for use by multiple crux installations. PKGMK_PACKAGE_DIR can be set and used the same way. PKGMK_WORK_DIR="/usr/ports/work/$name" This example instructs pkgmk to use /usr/ports/work/$name as a work area for building the specified package. Building the grep package would result in the work area being /usr/ports/work/grep. An alternative would be to use a tmpfs as your work directory. There are a few more settings which can be found in the pkgmk.conf man page. 4.6. Package Guidelines 4.6.1. General • The name of a package should always be lowercase (e.g. name=eterm and not name=Eterm). In case the package is added to the CRUX ports system the exact same name should be use for the name of the directory in the ports structure, i.e. /usr/ports/???/eterm. • Do not combine several separately distributed programs/libraries into one package. Make several packages instead. 4.6.2. Directories • In general packages should install files in these directories. Exceptions are of course allowed if there is a good reason. But try to follow the following directory structure as close as possible. ┌──────────────────┬─────────────────────────────────────────────────────┐ │ Directory │ Description │ ├──────────────────┼─────────────────────────────────────────────────────┤ │/usr/bin/ │User command/application binaries │ ├──────────────────┼─────────────────────────────────────────────────────┤ │/usr/sbin/ │System binaries (e.g. daemons) │ ├──────────────────┼─────────────────────────────────────────────────────┤ │/usr/lib/ │Libraries │ ├──────────────────┼─────────────────────────────────────────────────────┤ │/usr/include/ │Header files │ ├──────────────────┼─────────────────────────────────────────────────────┤ │/usr/lib// │Plug-ins, addons, etc │ ├──────────────────┼─────────────────────────────────────────────────────┤ │/usr/share/man/ │Man pages │ ├──────────────────┼─────────────────────────────────────────────────────┤ │/usr/share//│Data files │ ├──────────────────┼─────────────────────────────────────────────────────┤ │/usr/etc// │Configuration files │ ├──────────────────┼─────────────────────────────────────────────────────┤ │/etc/ │Configuration files for system software (daemons, │ │ │etc) │ └──────────────────┴─────────────────────────────────────────────────────┘ • /opt directory is reserved for manually compiled/installed applications. Packages should never place anything there. • /usr/libexec/ is not used in CRUX, thus packages should never install anything there. Use /usr/lib// instead. 4.6.3. Remove Junk Files • Packages should not contain “junk files”. This includes info pages and other online documentation, man pages excluded (e.g. usr/doc/*, README, *.info, *.html, etc). • Files related to NLS (national language support), always use --disable-nls when available. • Useless or obsolete binaries (e.g. /usr/games/banner and /sbin/mkfs.minix). 4.6.4. Pkgfile • Do not add new variables to the Pkgfile. Only in very few cases does this actually improve the readability or the quality of the package. Further, the only variables that are guranteed to work with future versions of pkgmk are name, version, release, and source. Other names could be in conflict with internal variables in pkgmk. • Use the $name and $version variables to make the package easier to update/maintain. For example, source=(http://xyz.org/$name-$version.tar.gz) is better than source=(http://xyz.org/myprog-1.0.3.tar.gz) since the URL will automatically updated when you modify the $version variable. • Remember that source is an array, i.e. always do source=(...) and not source=... 4.6.4.1. Pkgfile header Provide a header including the following fields: ┌───────────┬────────────────────────────────────────────────────────────┐ │Name │Meaning │ ├───────────┼────────────────────────────────────────────────────────────┤ │Description│A short description of the package; keep it factual │ ├───────────┼────────────────────────────────────────────────────────────┤ │Maintainer │Your full name and e-mail address, obfuscated if you want │ ├───────────┼────────────────────────────────────────────────────────────┤ │Packager │The original packager's full name and e-mail address │ ├───────────┼────────────────────────────────────────────────────────────┤ │URL │A webpage with more information on this software package │ ├───────────┼────────────────────────────────────────────────────────────┤ │Depends on │A list of dependencies, separated either by spaces or commas│ └───────────┴────────────────────────────────────────────────────────────┘ Depends on can be omitted if there are no dependencies; Packager can be omitted if the maintainer and packager are the same person. Example header # Description: Terminal based IRC client for UNIX systems # URL: http://www.irssi.org/ # Maintainer: Jukka Heino, jukka at karsikkopuu dot net # Packager: Daniel K. Gebhart, dkg at con-fuse dot org # Depends on: glib 5. The Ports System 5.1. Introduction 5.1.1. What is a Port? A port is a directory containing the files needed for building a package using pkgmk. This means that this directory at least has the files Pkgfile (which is the package build description) and .footprint (which is used for regression testing and contains a list of files this package is expected to contain once it is built). Further, a port directory can contain patches and/or other files needed for building the package. It is important to understand that the actual source code for the package is not necessarily present in port directory. Instead the Pkgfile contains an URL which points to a location where the source can be downloaded. The use of the word port in this context is borrowed from the BSD world, where a port refers to a program that has been ported to a system or platform. The word can sometimes be a bit misleading since most programs require no actual porting to run on CRUX (or on Linux in general). 5.1.2. What is the Ports System? The term Ports System refers to a remote repository containing ports and a client program capable of downloading ports from that repository. CRUX users use the ports(8) utility to download ports from the repository and place them in /usr/ports/. The ports utility uses rsync(1) or httpup(1) to do the actual downloading/synchronization. 5.1.3. Port collections CRUX' ports are organized in so called collections. There are three different layers of ports: 5.1.3.1. The official collections 'core', 'opt', 'xorg' and 'compat-32' core, opt, xorg and compat-32 are the four primary collections of CRUX. They're maintained by the CRUX development team which ensures that they're consistent and working well together. The first three are enabled by default. The compat-32 collection is disabled by default and contains 32-bit compatibility ports. 5.1.3.2. The user contributed collection 'contrib' The contrib collection is a collection which is provided by experienced port maintainers: some are part of the CRUX development team, while others are regular users. Its goal is to reduce the number of duplicate ports provided in the individual collections. If you're a seasoned port maintainer, you might even want to join the contrib collection. As those ports are not provided officially by the CRUX development team, this collection is disabled by default. 5.1.3.3. The individual collections from CRUX users Using HttpUp, every user can publish his or her own ports easily; the only requirement for that is some webspace to upload the ports. Publishing ports in an HttpUp repository is the easiest way to contribute back to the CRUX community. 5.2. Using the Ports System 5.2.1. Synchronizing Your Local Ports Structure When CRUX is installed for the first time the local ports structure (/usr/ports/) is empty. To bring your local ports structure up to date you use the ports utility with the -u option. Example: $ ports -u The -u option means update, and tells ports to contact the ports repository and download new and updated ports. The output from this execution is something like this: Updating file list from crux.nu::ports/crux-3.1/core/ Updating collection ports/crux-3.1/core/ ... Updating file list from crux.nu::ports/crux-3.1/opt/ Updating collection ports/crux-3.1/opt/ ... Updating file list from crux.nu::ports/crux-3.1/xorg/ Updating collection ports/crux-3.1/xorg/ ... Finished successfully The output reveals which files are downloaded, updated and deleted. 5.2.2. Listing Local Ports When the local ports structure has been updated the directory /usr/ports/ will contain two package categories, core and opt. Under each of these directories you will find ports. You can simply browse around in the directory structure to find out which ports are available. $ cd /usr/ports/core/ $ ls acl/ gawk/ libtool/ reiserfsprogs/ attr/ gcc/ libusb/ rsync/ autoconf/ gdbm/ libusb-compat/ sed/ automake/ gettext/ lilo/ shadow/ bash/ glibc/ m4/ sudo/ bc/ glibc-32/ make/ sysfsutils/ bin86/ grep/ man/ sysklogd/ bindutils/ groff/ man-pages/ sysvinit/ binutils/ gzip/ mlocate/ tar/ bison/ hdparm/ nasm/ tcp_wrappers/ btrfs-progs/ httpup/ ncurses/ time/ bzip2/ iana-etc/ net-tools/ traceroute/ ca-certificates/ inetutils/ openrdate/ tzdata/ coreutils/ iproute2/ openssh/ udev/ cpio/ iptables/ openssl/ unzip/ curl/ iputils/ patch/ usbutils/ db/ jfsutils/ pciutils/ util-linux/ dcron/ kbd/ perl/ vim/ dhcpcd/ kmod/ pkg-config/ wget/ diffutils/ less/ pkgutils/ which/ e2fsprogs/ libarchive/ ports/ xfsprogs/ ed/ libcap/ ppp/ xz/ exim/ libdevmapper/ procps/ zip/ file/ libgmp/ prt-get/ zlib/ filesystem/ libmpc/ psmisc/ findutils/ libmpfr/ rc/ flex/ libpcre/ readline/ You can also use ports with the -l option to list all local ports. Example: $ ports -l core/autoconf core/automake core/bash core/bc core/bin86 core/bindutils core/binutils ... If you are looking for a specific package, it might be easier to use this approach (e.g. ports -l | grep sendmail) to find out if the package is available and if so in which category it is located. 5.2.3. Listing Version Differences To find out if the ports structure carries ports that are different (likely newer) compared to the versions currently installed you can use the option -d. If version differences are found, the output from the above command could look something like this: $ ports -d Collection Name Port Installed core glibc 2.3.6-3 2.3.6-2 opt gtk 2.8.12-1 2.8.11-1 If no version differences were found, i.e. the system is in sync with the ports structure, the output will simply be: $ ports -d No differences found 5.2.4. Building and Installing Packages Once you have found a port that you want to build and install you simply go into the desired port directory and use pkgmk to build it. Example: $ cd /usr/ports/core/gawk $ pkgmk -d The -d option means download missing source files and tells pkgmk to download the source(s) specified in the Pkgfile (in case the source is already downloaded this option is ignored). When the download is completed the package will be built. If the package was built successfully you can use pkgadd to install or upgrade it. Example: $ pkgadd gawk#3.1.5-3.pkg.tar.gz To make life a bit easier these two steps can be made into one by using the options -i (for install) or -u (for upgrade). Example: $ pkgmk -d -i or $ pkgmk -d -u This will download, build and then install/upgrade the package. Note that the package will only be installed/upgraded if the build is successful. 5.2.5. Enabling the 'contrib' collection As previously mentioned, the 'contrib' collection contains useful ports of experienced port maintainers. Since they are not provided by the CRUX development team, you should be slightly more critical with respect to quality and security. However, most members of the 'contrib' collections are well respected members of the community. To enable it for ports, do $ cd /etc/ports $ mv contrib.rsync.inactive contrib.rsync To let prt-get know that you want it to use the contrib tree too, edit /etc/prt-get.conf and uncomment the line prtdir /usr/ports/contrib (i.e. remove the hashmark in the beginning of the line. After that, it should look like this: ### ### prt-get conf ### # note: the order matters: the package found first is used prtdir /usr/ports/core prtdir /usr/ports/opt # the following line enables the user maintained contrib collection prtdir /usr/ports/contrib Now, run ports -u and you're ready to use the ports from contrib. 5.2.6. Enabling the 'compat-32' collection The 'compat-32' collection contains compatibility ports needed for 32-bit support (32-bit applications running on a 64-bit multilib system.) To enable it for ports, do $ cd /etc/ports $ mv compat-32.rsync.inactive compat-32.rsync The 'compat-32' collection is enabled in the same way as the 'contrib' collection (described previously) for usage with prt-get. As with 'contrib', run ports -u and you're ready to use the ports from compat-32. 5.2.7. Additional tools 5.2.7.1. Building ports as unprivileged user Normaly building packages requires root-privileges. This is critical because a malicious or badly designed port can damage your system. The fakeroot command provides a way to build ports as normal user. Particularly when you build packages from user contributed repositories you should always invoke fakeroot: $ fakeroot pkgmk -d You can also make prt-get use fakeroot. There is a manual on the CRUX website describing how to achieve that. 5.2.7.2. Useful scripts Regarding package and ports management there are many tasks which can be done in several steps with the CRUX standard tools introduced above. The port prt-utils in the opt repository contains a collection of such scripts. The usage of these scripts is documented in the corresponding man pages. In the documentation section of the CRUX website is an overview of all the scripts in prt-utils. 6. Configuration 6.1. Initialization Scripts 6.1.1. Runlevels The following runlevels are used in CRUX (defined in /etc/inittab). ┌────────┬────────────────┐ │Runlevel│ Description │ ├────────┼────────────────┤ │0 │Halt │ ├────────┼────────────────┤ │1 (S) │Single-user Mode│ ├────────┼────────────────┤ │2 │Multi-user Mode │ ├────────┼────────────────┤ │3-5 │(Not used) │ ├────────┼────────────────┤ │6 │Reboot │ └────────┴────────────────┘ 6.1.2. Layout The initialization scripts used in CRUX follow the BSD-style (as opposed to the SysV-style) and have the following layout. ┌────────────────┬──────────────────────────────────────────────────┐ │ File │ Description │ ├────────────────┼──────────────────────────────────────────────────┤ │/etc/rc │System boot script │ ├────────────────┼──────────────────────────────────────────────────┤ │/etc/rc.single │Single-user startup script │ ├────────────────┼──────────────────────────────────────────────────┤ │/etc/rc.modules │Module initialization script │ ├────────────────┼──────────────────────────────────────────────────┤ │/etc/rc.multi │Multi-user startup script │ ├────────────────┼──────────────────────────────────────────────────┤ │/etc/rc.local │Local multi-user startup script (empty by default)│ ├────────────────┼──────────────────────────────────────────────────┤ │/etc/rc.shutdown│System shutdown script │ ├────────────────┼──────────────────────────────────────────────────┤ │/etc/rc.conf │System configuration │ ├────────────────┼──────────────────────────────────────────────────┤ │/etc/rc.d/ │Service start/stop script directory │ └────────────────┴──────────────────────────────────────────────────┘ Modify /etc/rc.modules, /etc/rc.local and /etc/rc.conf according to your needs. 6.1.3. Configuration Variables in /etc/rc.conf The following configuration variables are found in /etc/rc.conf. ┌────────┬───────────────────────────────────────────────────────────────┐ │Variable│ Description │ ├────────┼───────────────────────────────────────────────────────────────┤ │ │Specifies which console font to load at system startup. The │ │ │contents of this variable will be passed as argument to │ │FONT │setfont(1). The available fonts are located in │ │ │/usr/share/kbd/consolefonts/. │ │ │ │ │ │Example: FONT=default │ ├────────┼───────────────────────────────────────────────────────────────┤ │ │Specifies which console keyboard map to load at system startup.│ │ │The contents of this variable will be passed as argument to │ │KEYMAP │loadkeys(1). The available keyboard maps are located in │ │ │/usr/share/kbd/keymaps/. │ │ │ │ │ │Example: KEYMAP=sv-latin1 │ ├────────┼───────────────────────────────────────────────────────────────┤ │ │Specifies the timezone used by the system. The available zone │ │TIMEZONE│description files are located in /usr/share/zoneinfo/. │ │ │ │ │ │Example: TIMEZONE=Europe/Stockholm │ ├────────┼───────────────────────────────────────────────────────────────┤ │ │Specifies the hostname. │ │HOSTNAME│ │ │ │Example: HOSTNAME=pluto │ ├────────┼───────────────────────────────────────────────────────────────┤ │ │Specifies the system logging daemon(s) to run at startup. │ │SYSLOG │ │ │ │Example: SYSLOG=sysklogd │ ├────────┼───────────────────────────────────────────────────────────────┤ │ │Specifies which services to start at system startup. The │ │ │services specified in this array must have a matching │ │ │start/stop script in /etc/rc.d/. When entering multi-user mode │ │ │the specified scripts will be called in the specified order │ │SERVICES│with the argument start. At system shutdown or when entering │ │ │single-user mode these scripts will be called in the reverse │ │ │order with the argument stop. │ │ │ │ │ │Example: SERVICES=(crond lo net sshd) │ └────────┴───────────────────────────────────────────────────────────────┘ 6.1.4. Generating locales Starting with CRUX 2.5, glibc does not contain all possible locales anymore, thus you'll have to generate the locales you need/use. The following example is a typical setup for swedish users, replace sv_SE* with the locale you want: # localedef -i sv_SE -f ISO-8859-1 sv_SE # localedef -i sv_SE -f ISO-8859-1 sv_SE.ISO-8859-1 # localedef -i sv_SE -f UTF-8 sv_SE.UTF-8 6.1.5. Network Configuration The network configuration is found in the service script /etc/rc.d/net. To enable this service you need to add net to the SERVICES array in /etc/rc.conf. By default this service script configures a dynamic IP address. Example: #!/bin/sh # # /etc/rc.d/net: start/stop network interface # # Connection type: "DHCP" or "static" TYPE="DHCP" # For "static" connections, specify your settings here: # To see your available devices run "ip link". DEV=enp11s0 ADDR=192.168.1.100 MASK=24 GW=192.168.1.1 # Optional settings: DHCPOPTS="-h `/bin/hostname` -t 10" case $1 in start) if [ "${TYPE}" = "DHCP" ]; then /sbin/dhcpcd ${DHCPOPTS} else /sbin/ip addr add ${ADDR}/${MASK} dev ${DEV} broadcast + /sbin/ip link set ${DEV} up /sbin/ip route add default via ${GW} fi ;; stop) if [ "${TYPE}" = "DHCP" ]; then /sbin/dhcpcd -x else /sbin/ip route del default /sbin/ip link set ${DEV} down /sbin/ip addr del ${ADDR}/${MASK} dev ${DEV} fi ;; restart) $0 stop $0 start ;; *) echo "Usage: $0 [start|stop|restart]" ;; esac # End of file if you want to configure your system to use a static IP address, specify TYPE=static and the correct interface. You will also need to configure DNS settings in /etc/resolv.conf. Example: #!/bin/sh # # /etc/rc.d/net: start/stop network interface # # Connection type: "DHCP" or "static" TYPE="static" # For "static" connections, specify your settings here: # To see your available devices run "ip link". DEV=enp11s0 ADDR=192.168.1.100 MASK=24 GW=192.168.1.1 # Optional settings: DHCPOPTS="-h `/bin/hostname` -t 10" case $1 in start) if [ "${TYPE}" == "DHCP" ]; then /sbin/dhcpcd ${DHCPOPTS} else /sbin/ip addr add ${ADDR}/${MASK} dev ${DEV} broadcast + /sbin/ip link set ${DEV} up /sbin/ip route add default via ${GW} fi ;; stop) if [ "${TYPE}" == "DHCP" ]; then /sbin/dhcpcd -x else /sbin/ip route del default /sbin/ip link set ${DEV} down /sbin/ip addr del ${ADDR}/${MASK} dev ${DEV} fi ;; restart) $0 stop $0 start ;; *) echo "Usage: $0 [start|stop|restart]" ;; esac # End of file # # /etc/resolv.conf: resolver configuration file # search nameserver # End of file Note CRUX releases prior to 2.3 used ifconfig(8) and route(8) commands for network initialization; below we provide the previous templates as a reference. Manual ip configuration (CRUX < 2.3): #!/bin/sh # # /etc/rc.d/net: start/stop network # case $1 in start) /sbin/ifconfig lo 127.0.0.1 /sbin/ifconfig eth0 195.38.1.140 netmask 255.255.255.224 /sbin/ifconfig eth1 192.168.0.1 netmask 255.255.255.0 /sbin/route add default gw 195.38.1.129 ;; stop) /sbin/ifconfig eth1 down /sbin/ifconfig eth0 down /sbin/ifconfig lo down ;; restart) $0 stop $0 start ;; *) echo "usage: $0 [start|stop|restart]" ;; esac # End of file DHCP Configuration (CRUX < 2.3): #!/bin/sh # # /etc/rc.d/net: start/stop network # case $1 in start) /sbin/ifconfig lo 127.0.0.1 /sbin/dhcpcd eth0 [add additional options if needed] ;; stop) killall -q /sbin/dhcpcd /sbin/ifconfig lo down ;; restart) $0 stop $0 start ;; *) echo "usage: $0 [start|stop|restart]" ;; esac # End of file 6.2. Passwords CRUX uses SHA512 passwords by default. To change the password encryption method set the ENCRYPT_METHOD variable in /etc/login.defs to DES, MD5 or SHA256. Furthermore, when compiling programs that use the crypt(3) function to authenticate users you should make sure that these programs are linked against the libcrypt library (i.e. use -lcrypt when linking) which contains the SHA512 version of the crypt function (this version is backwards compatible and understands DES passwords as well). 6.3. Upgrading the Kernel The kernel source, which is found in /usr/src/linux-4.14.xx/ is not installed using pkgadd. If you decide to upgrade your kernel you can safely do so by manually replacing the kernel source with a newer version (or place it somewhere else). This will not make the package database inconsistent (since it's not installed with pkgadd) nor will it affect the kernel headers found in /usr/include/linux and /usr/include/asm since these are not symlinks to the kernel source, but instead contain copies of the headers. 7. Appendix 7.1. Troubleshooting Many common problems are answered in the FAQ document, so if you experience problems please check whether http://crux.nu/Main/Faq contains answers to your questions already. If you have further questions, there's a dedicated mailing list for CRUX, and an IRC channel. Actual information about these can be found on the Community page of our wiki. 7.2. GRUB installation CRUX versions 3.0 and up use GNU GRUB 2. GRUB 0.9x has become "GRUB Legacy" and is no longer actively developed. GRUB is the recommended bootloader if you intend to use btrfs as your root filesystem. 7.2.1. Precaution Installing a new boot manager is like modifying the partition table using fdisk or installing a new system kernel. Please create a rescue boot disk first! 7.2.2. Installation To install GRUB, use grub-install: # grub-install /dev/sdX Replace /dev/sdX with the appropriate device node for the drive on which you want to install the boot loader, for example /dev/sda. grub-install copies the appropriate GRUB image files into /boot/grub and runs grub-setup to install the boot loader into the boot sector of the specified drive. Once GRUB has been installed, a configuration file needs to be created. 7.2.3. Configuration file 7.2.3.1. Automatic creation GRUB can attempt to create a configuration file automatically with the grub-mkconfig tool. grub-mkconfig searches for installed kernels in a set of default locations. In order for grub-mkconfig to find the installed kernel it should be named something like the following: • /boot/vmlinuz-* • /vmlinuz-* • /boot/kernel-* For example, grub-mkconfig would be able to properly locate a kernel saved as /boot/vmlinuz-4.14.34 but NOT a kernel saved as /boot/linuxkernel-4.14.34. Once the kernel is saved in the proper location, run grub-mkconfig to automatically create the GRUB configuration file. grub-mkconfig outputs the file to the standard output (stdout) by default: # grub-mkconfig > /boot/grub/grub.cfg 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. For more information, see the GRUB manual at http://www.gnu.org/software/grub/manual/. 7.2.3.2. Manual creation If preferred, a grub.cfg file can be created manually. For more information see the GRUB manual at http://www.gnu.org/software/grub/manual/. A simple example configuration might look like the following: # Display the menu for 10 seconds set timeout=10 # Boot the first entry by default set default=0 # Boot entries follow # Default CRUX boot entry menuentry "CRUX 3.4" { linux (hd0,msdos2)/boot/vmlinuz-4.14.34 root=/dev/sda2 quiet } # Single-user recovery entry menuentry "CRUX 3.4 single-user mode" { linux (hd0,msdos2)/boot/vmlinuz-4.14.34 root=/dev/sda2 quiet single } # Memory test entry menuentry "MemTest86+ 4.20" { linux16 (hd0,msdos2)/boot/memtest86+-4.20.bin } Save the manual configuration file as /boot/grub/grub.cfg. Retrieved from https://crux.nu/Main/Handbook3-4 Page last modified on 2018-04-13 12:04