CRUX Handbook


Last modified: 2002-10-12

This handbook covers installation, configuration and administration of CRUX. Please note that this handbook only covers topics that are specific to CRUX. For further information about Linux see the Linux Documentation Project.

Table of Contents

1. Introduction
1.1. What is CRUX?
1.2. Why use CRUX?
1.3. License
1.3.1. Packages
1.3.2. Build Scripts
2. Installing CRUX
2.1. Supported Hardware
2.2. Installing From CD-ROM
2.3. Alternative Installation Methods
2.3.1. Building Your Own Bootkernel
2.3.2. Network Installation
3. The Package System
3.1. Introduction
3.2. Using the Package System
3.2.1. Installing a Package
3.2.2. Removing a Package
3.2.3. Upgrading a Package
3.2.4. Querying the Package Database
3.3. Creating Packages
3.4. Package Guidelines
3.4.1. General
3.4.2. Directories
3.4.3. Remove Junk Files
3.4.4. Pkgfile
4. The Ports System
4.1. Introduction
4.1.1. What is a Port?
4.1.2. What is the Ports System?
4.2. Using the Ports System
4.2.1. Synchronizing Your Local Ports Structure
4.2.2. Listing Local Ports
4.2.3. Listing Version Differences
4.2.4. Building and Installing Packages
4.3. Contributing Ports
4.3.1. Introduction
4.3.2. Contrib Maintainers
4.3.3. Quick CVS Manual
4.3.4. CVS Guidelines
5. Configuration
5.1. Initialization Scripts
5.1.1. Runlevels
5.1.2. Layout
5.1.3. Configuration Variables in /etc/rc.conf
5.2. Passwords
5.3. Upgrading the Kernel
6. Frequently Asked Questions
6.1. General
6.2. Installation
6.3. Configuration

Chapter 1. Introduction

Table of Contents

1.1. What is CRUX?
1.2. Why use CRUX?
1.3. License
1.3.1. Packages
1.3.2. Build Scripts

1.1. What is CRUX?

CRUX is a lightweight, i686-optimized Linux distribution targeted at experienced Linux users. The primary focus of this distribution is “keep it simple”, which is reflected 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.

1.2. Why use CRUX?

There are many Linux distributions out there these days, so why would this distribution be any better than the others? Well, it's all about taste really. I can give you a hint about my taste, and perhaps you share that taste, or you don't. First of all, I want a distribution that is made with simplicity in mind from the beginning to the end. Further, I want my packages to be up-to-date, not the latest bleeding-edge-alpha version, but the latest stable version of all packages. I want it to be easy to create new and update old packages (updating a package in CRUX is often just a matter of typing pkgmk -d -u). I want packages to be optimized for my processor (think -march=i686). I don't want my filesystem cluttered with files I never use (think /usr/doc/*, etc. If I need more information about a specific program, other than information found on the man-page, I'll find it on the net). And finally, I want to be able to use new features offered by recent Linux kernels (think devfs, reiserfs, ext3fs, etc).

If you are a somewhat experienced Linux user that wants a clean and solid Linux distribution as the foundation of your installation, prefers editing configuration files with an editor rather than using a GUI, and doesn't hesitate to download and compile programs yourself, then this distribution might suit you well.

1.3. License

1.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 what license a particular package is licensed have a look at its source code.

1.3.2. Build Scripts

All package build scripts in CRUX (in package categories base and opt) are Copyright 2000-2002 by Per Lidén and is licensed through the GNU General Public License.


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.

Chapter 2. Installing CRUX

2.1. Supported Hardware

CRUX is compiled with optimization for i686 (Pentium-Pro/Celeron/Pentium-II) or better processor. Do NOT try to install it on an i586 (Pentium, AMD K6/K6-II/K6-III) or lower, since it simply will not work. 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
IDE Generic PCI IDE chipset
SCSI 7000FASST, ACARD, Adaptec AHA152X/2825, Adaptec AHA1542, Adaptec AHA1740, Adaptec AIC7xxx, AdvanSys, AM53/79C974 PCI, BusLogic, Generic NCR5380/53c400, Initio 9100U(W), Initio INI-A100U2W, NCR53c406a, NCR53C8XX, Simple 53c710, Symbios 53c416, Tekram DC390(T) and Am53/79C974, UltraStor
USB USB device filesystem, UHCI (Intel PIIX4, VIA, ...) support, USB Human Interface Device (full HID) support

To be able to install CRUX your disk controller must be present in the list above. If your CD-ROM drive does not support bootable ISO images you can boot using a floppy drive instead. Just use dd to dump the file /boot/boot.img (found on the CRUX ISO) onto a floppy disk. Insert both the floppy and the CD when booting.

If you hardware is not supported or if you have other problems installing CRUX you might find a solution in Section 2.3.

2.2. Installing From CD-ROM

  1. Download the CRUX ISO image (crux-X.X.X.iso). To ensure that the download was successful you should examine its checksum using md5sum. Run

    $ md5sum crux-X.X.X.iso

    and compare the output with the file crux-X.X.X.md5sum, which can be found in the same directory as the ISO image on the ftp-site. If the checksums match the download was successful and you can continue with burning the ISO image on a CD.

  2. The ISO image is bootable, just insert the newly burned CD and reboot your computer. Press enter at the lilo boot prompt.

  3. Login as root (no password required).

  4. Create (if necessary) and format the partition(s) you want CRUX to be installed on, e.g.:

    # fdisk /dev/discs/disc?/disc
    # mkreiserfs /dev/discs/disc?/part?
    # mkswap /dev/discs/disc?/part?

    The amount of disk space you need depends on how many packages you choose to install. I recommend you to at least have a 1G root partition (CRUX will use about 200MB-500MB depending on your configuration).

    Using reiserfs or ext3fs is recommended, but there is of course support for ext2fs as well. Further, I highly recommend you to separate the system 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 reinstall your system.

    [Note] Note

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

  5. Mount the partition you want this distribution to be installed on, e.g.:

    # mount /dev/discs/disc?/part? /mnt

    If you want the installation to be put on more than one partition, then mount these partitions as well. E.g. if you want to have a different partition for /var, then do like this:

    # mkdir /mnt/var
    # mount /dev/discs/disc?/part? /mnt/var
  6. Activate your swap partition(s) using the swapon command, i.e.:

    # swapon /dev/discs/disc?/part?
  7. Type Setup (with capital S) to start the package installation script. The script will ask you where you mounted your new root partition and which packages you want to install. Just select the packages you want and nothing else will be installed. However, I recommend you to at least install all packages marked base.

    When the Setup script has installed the selected packages an installation log will be displayed. Make sure the last line in the log says “0 error(s)”.

    If you at a later stage find that you need some additional packages you can just mount the CRUX CD-ROM and use pkgadd to install them.

    [Note] Note

    There is no package dependency checking. This means that it is up to you to figure out that if you for example install the sendmail package you also need to install the db package.


  8. Edit /mnt/etc/fstab to configure your filesystem(s).

  9. Edit /mnt/etc/rc.conf to configure keyboard, network, daemons, and timezone.

  10. Edit /mnt/etc/hosts and /mnt/etc/resolv.conf and add your ip/hostname/domain/dns.

  11. Reboot your system (boot from the CRUX CD-ROM again) and type CRUX root=device at the lilo prompt. Replace device with the name of your new CRUX root partition. Remeber that CRUX uses devfs, thus the name of your root device should be something like /dev/discs/disc?/part?. When CRUX is booting using your new root for the first time there might be some error messages printed to the console. These errors are most often not vital, but you should keep an eye on them. If you reach the login prompt you are most likely home safe.

  12. Login as root (no password required).

  13. Go to /usr/src/linux-X.X.X, configure and compile a new kernel. Remember to enable the following kernel options:

    Code maturity level options  --->
          [*] Prompt for development and/or incomplete code/drivers
    File systems  --->
          [*] /dev file system support
          [*]   Automatically mount at boot
  14. Edit /etc/lilo.conf to boot the kernel you just compiled and run lilo to make the new system bootable.

  15. Remove the CRUX CD-ROM from your drive and reboot from harddisk.

2.3. Alternative Installation Methods

2.3.1. Building Your Own Bootkernel

If you are unable to install CRUX from CD-ROM because your hardware is not supported by the bootkernel you can build your own bootkernel and add whatever hardware support you need. To do this you need a 1.44Mb floppy disk, access to another Linux box and the CRUX ISO image burned on a CD. Basic knowledge about how to configure and compile the Linux kernel is of course also required.

  1. Build a new kernel which has support for your hardware. Use the kernel configuration used by the existing bootkernel as a starting point (you can find it here) and add the hardware support you need. If the kernel gets too big it is safe to remove SCSI and USB drivers (unless you need them of course), but do not remove any filesystem related options.

  2. Download the boot floppy creation kit and unpack it.

  3. Go into the bootfloppy directory and execute the mkbootfloppy script (as root). This script requires one argument, the kernel image you want to place on the floppy image. Before you do this, make sure you do not have anything mounted on /mnt since the mkbootfloppy script will use that as a mount point. I.e.

    # cd mkbootfloppy
    # ./mkbootfloppy /path/to/kernel/linux/arch/i386/boot/bzImage
    1440+0 records in
    1440+0 records out
    mke2fs 1.27 (8-Mar-2002)
    Added CRUX *
  4. Write the resulting boot.img file to a floppy disk (i.e. dd if=boot.img of=/dev/fd0).

  5. Insert both the floppy disk and the CRUX CD into the system you want to install CRUX on and reboot.

  6. Install CRUX.

2.3.2. Network Installation

If you do not have a CD burner, is unable to boot you machine using the CRUX CD-ROM or for any other reason is unable to install CRUX the normal way (Section 2.2) you might want to check out CRUX Network Setup Guide by Martin Opel or HOWTO install CRUX via NFS by Jürgen Daubert.

Chapter 3. The Package System

3.1. Introduction

The package system 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 name#version-release.pkg.tar.gz, where name is the name of the program, version is the version number of the program, and release 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(8). This way it is easy to tell packages apart from other tar.gz files.

pkgadd(8), pkgrm(8), pkginfo(8), and pkgmk(8) are the package management utilities. With these utilities you can install, uninstall, inspect, make packages and query the package database.

When a package is installed using pkgadd(8) a new record is added to the package database (stored in /var/lib/pkg/db). The 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 following chapters will in short describe how to use the package utilities. Additional information about these utilities can be found on their respective man page.

3.2. Using the Package System

3.2.1. Installing a Package

Installing a package is done by using pkgadd(8). This utility requires at least one argument, the package you want to install. For example:

# pkgadd bash#2.05-1.pkg.tar.gz

When installing a package the package manager will ensure that no already installed files are overwritten. If conflicts are found an error message will be printed and pkgadd(8) 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
pkgadd error: listed file(s) already installed
    (use -f to ignore and overwrite)

To force the installation (i.e. overwrite the conflicting files) you can use the option -f (or --force). For example:

# pkgadd -f bash#2.05-1.pkg.tar.gz

The package system only allowes 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 beeing installed. Directories can however be owned by more then one package.

[Warning] 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 the this option with extreme care, preferably not at all.

As said earlier the package file itself does not contain any meta-data at all. 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(8) 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(8) will abort without installing the package.

3.2.2. Removing a Package

Removing a package is done by using pkgrm(8). This utility requires one argument, the name of the package you want to remove. For example:

# pkgrm bash
[Warning] 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).

3.2.3. Upgrading a Package

Upgrading a package is done by using pkadd(8) with the -u option. For example:

# pkgadd -u bash#2.05-1.pkg.tar.gz

This will replace the previously installed bash package with the new one. If bash has not been previously installed an error message will be printed. The package system will not care about the version number of the package in the sense that you can “upgrade” version 2.05-1 with version 2.04-1 (or even with version 2.05-1 itself). All that happens is just that the installed package will be replaced with the new one.

Upgrading a package is equivalent to executing pkgrm(8) followed by pkgadd(8) with one (big) exception. When upgrading a package (with pkgadd -u) you have the option to preserve some of the already installed files and prevent them from getting replaced. This is typically useful when you want to preserve configuration and log files.

When executing pkgadd(8) 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 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/XF86Config$    NO

# End of file

The above example will cause pkgadd(8) 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/XF86Config. The default rule is to upgrade everything, rules in this file are exceptions to that rule.

[Note] 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(8) finds that a specific file should not be upgraded it will install it under /var/lib/pkg/rejected/. The user is then free to examine, use and/or remove that file manually. Files in this directory are never added to the package database.

Example (with above /etc/pkgadd.conf used):

# pkgadd -u bash#2.05-1.pkg.tar.gz
pkgadd: rejecting etc/profile, keeping existing version
$ ls /var/lib/pkg/rejected/
$ ls /var/lib/pkg/rejected/etc/

3.2.4. Querying the Package Database

Querying the package database is done by using pkginfo(8). This utility has a few options to answer different queries.

-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 file List owner of file.


$ 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
$ pkginfo -l grep#2.5-1.pkg.tar.gz
$ pkginfo -o /bin/ls
fileutils 4.1-1

3.3. Creating Packages

Creating a package is done by using pkgmk(8). 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.

# Specify the version of the package.

# Specify the package release.

# The source(s) used to build this package.

# The build() function below will be called by pkgmk(8) 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.

   # 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:

# $Id: Pkgfile,v 1.2 2002/01/23 19:27:21 per Exp $
# Maintainer: Per Lidén


build() {
  cd $name-$version
  ./configure --prefix=/usr --disable-nls
  make DESTDIR=$PKG install
  rm -rf $PKG/usr/info
[Note] Note

The build() function in the example above is just an example of how grep(1) is compiled. The contents of the function can differ significantly if the program is build in some other way, e.g. does not use autoconf(1).

When the build() function has been executed the $PKG directory will be made into a package named name#version-release.pkg.tar.gz. Before the package creation is completed pkgmk(8) 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 should contain a list of all files that should be in the package if the build was successful. 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(8) and try it out. I highly recommend you to look at the Pkgfile in other packages, since looking at examples is a great way to learn.

3.4. Package Guidelines

3.4.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 CVS repository the excact same name should be use for the name of the directory in the ports structure, i.e. /usr/ports/contrib/eterm.

  • Do not combine several separately distributed programs/libraries into the same packages. Make several packages instead.

3.4.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 above directory structure as close as possible.

    Directory Description
    /usr/bin/ Command/application binaries
    /usr/lib/ Libraries
    /usr/include/ Header files
    /usr/lib/prog/ Plug-ins, addons, etc
    /usr/man/ Man pages
    /usr/share/prog/ Data files
    /usr/etc/prog/ Configuration files
    /usr/sbin/ System binaries (daemons, etc)
    /etc/ Configuration files for system software (daemons, etc)
  • /usr/X11R6 and /usr/???/X11 are reserved for XFree86 only. X related programs that are not shipped with XFree86 should be placed under /usr and NOT under /usr/X11R6 or /usr/???/X11.

  • /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 something there. Use /usr/lib/prog/ instead.

3.4.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).

3.4.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(8) are name, version, release, and source. Other names could be in conflict with internal variables in pkgmk(8).

  • Use the $name and $version variables to make the package easier to modify/update/maintain. E.g. source=($name-$version.tar.gz) is better than source=( 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=...

Chapter 4. The Ports System

4.1. Introduction

4.1.1. What is a Port?

A port is a directory containing the files needed for building a package using pkgmk(8). 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 platform or system. The word can sometimes be a bit misleading since most programs require no actual porting to run on CRUX (or on Linux in general).

4.1.2. What is the Ports System?

The term Ports System refers to a CVS repository containing ports and a client program capable of downloading ports from that CVS repository. CRUX users use the ports(8) utility to download ports from the CVS repositorty and place them in /usr/ports/. The ports(8) utility uses CVSup to do the actual downloading/synchronization.

4.2. Using the Ports System

4.2.1. Synchronizing Your Local Ports Structure

When CRUX is installed for the first time the local ports structure (/usr/ports/) is empty (well, almost empty, there are some configuration files in there). To bring your local ports structure up to date you use the ports(8) utility with the -u option. I.e.

# ports -u

The -u option means update, and tells ports(8) to contact the ports CVS repository and download new and updated ports. The output from this execution is something like this:

Connected to
Updating collection base/cvs
Updating collection opt/cvs
Updating collection contrib/cvs
Finished successfully

The output reveals which files are downladed, updated and deleted.

4.2.2. Listing Local Ports

When the local ports structure has been updated the directory /usr/ports/ will contain three package categories, base, opt and contib. 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. Doing cd /usr/ports/base/; ls will give you something like:

autoconf/   filesystem/  man/            sh-utils/
automake/   fileutils/   man-pages/      shadow/
bash/       findutils/   modutils/       sysklogd/
bin86/      flex/        nasm/           sysvinit/
binutils/   gawk/        ncurses/        tar/
bison/      gcc/         net-tools/      tcp_wrappers/
bsdinit/    glibc/       netkit-base/    tcsh/
bzip2/      grep/        patch/          textutils/
cpio/       groff/       perl/           time/
db/         gzip/        pkgutils/       traceroute/
dcron/      kbd/         procps/         util-linux/
devfsd/     less/        psmisc/         vim/
diffutils/  libtool/     readline/       wget/
e2fsprogs/  lilo/        reiserfsprogs/  which/
ed/         m4/          sed/            zlib/
file/       make/        sendmail/

You can also use ports(8) with the -l option to list all local ports. I.e.:

$ ports -l

The output from the above command will be something like this:


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.

4.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. I.e.:

$ ports -d

If version differences are found, the output from the above command could look something like this:

Collection  Name     Port     Installed
base        glibc    2.2.5-1  2.2.4-2
opt         xfree86  4.2.0-1  4.1.0-2

If no version differences were found, i.e. the system is in sync with the ports structure. Then output will simply be:

No differences found

4.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(8) to build it. E.g.:

# cd /usr/ports/base/sendmail
# pkgmk -d

The -d option means download missing source files and tells pkgmk(8) 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(8) to install or upgrade it. E.g.:

# pkgadd sendmail#8.11.6-2.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) when executing pkgmk(8). I.e.:

# pkgmk -d -i


# 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.

4.3. Contributing Ports

4.3.1. Introduction

The ports system has three sections base, opt and contrib. Sections base and opt are maintained by me (Per Lidén) while the contrib section is maintained by trusted port contributors (contrib maintainers) which have been given write access to the CVS repository. People that create ports are encuraged to publish them on the web and send the URL to the mailinglist to inform others about their work. The contrib maintainers will (when time permits) have a look at them. If they find that the ports are properly made, follow the guidelines and add a real value to CRUX they might decide to add them to the CVS contrib section. Please keep in mind that just because someone has made a port it does not mean that it will be included in the contrib section. The ports that go into the contrib section are carefully selected by the contrib maintainers.

4.3.2. Contrib Maintainers

The table below contains the names and e-mail addresses of the people that currenty has write permissions to the contrib section of the ports repository.

Name E-mail
Jürgen Daubert (jue)
Markus Ackermann (maol)
Jussi Mäki (valen)

4.3.3. Quick CVS Manual

This section is a quick introduction on how to add a port to the CRUX CVS repository. For more information about CVS, see

[Note] Note

Only trusted port contributors with a CVS account can access the repository this way. Regular CRUX users access the repository (read only) using the ports system.


$ export
$ export CVS_RSH=ssh

Checking out/Updating the contrib tree:

$ cvs checkout -r \
>  STABLE-X_X_X contrib
get a fresh copy of the contrib tree
$ cvs update -d -r \
>  STABLE-X_X_X contrib
update an already checked out tree

Adding a new port to the contrib tree:

$ cd crontrib
$ mkdir myport
$ cvs add myport
add port directory
$ cd myport
create Pkgfile, .footprint, .md5sum, etc
$ cvs add Pkgfile .footprint .md5sum
schedule files for addition
$ cvs commit -m "Comment..."
commit changes/additions

4.3.4. CVS Guidelines

  • The name of a port directory should always be the same as the package name specified in the Pkgfile (i.e. lowercase).

  • At least, have the following two lines in the top of your Pkgfile:

    # $Id$
    # Maintainer: Your Name
  • Never add any binary files (like .gz) to the repository, only plain text ASCII files are allowed.

  • Please think twice before adding/committing/tagging files.

Chapter 5. Configuration

5.1. Initialization Scripts

5.1.1. Runlevels

The following runlevels are used in CRUX (and are defined in /etc/inittab).

Runlevel Description
0 Halt
1 (S) Single-user Mode
2 Multi-user Mode
3-5 (Not used)
6 Reboot

5.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.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/ Daemon start/stop script directory

5.1.3. Configuration Variables in /etc/rc.conf

The following configuration variables are found in /etc/rc.conf.

Variable Description

Specifies which keyboard map to load at system startup. The contents of this variable will be passed as argument to loadkeys(1). The available keyboard maps are located in /usr/share/keymaps/.



Specifies the timezone used by the system. The available zone description files are located in /usr/share/zoneinfo/.



Specifies the hostname.



Specifies network interface configuration commands. When entering multi-user mode the strings specified in this array will one by one be passed as arguments to ifconfig(8).


             "eth0 netmask" \
             "eth1 netmask")

Specifies network interface shutdown commands. At system shutdown or when entering single-user mode the strings specified in this arrat will one by one be passed as arguments to ifconfig(8).


IFCONFIG_DOWN=("lo down" "eth0 down" "eth1 down")

Specifies network route configuration commands. When entering multi-user mode the strings in specified in this array will one by one be passed as arguments to route(8).


ROUTE=("add default gw")

Specifies which daemons to start at system startup. The daemons 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 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.


DAEMONS=(crond identd sshd sendmail)

5.2. Passwords

Starting with CRUX version 0.9.3 MD5SUM passwords are used by default. This can be turned off if you instead want to use the traditional DES passwords. Note however that DES passwords are considered less secure. To disable MD5SUM passwords change the MD5_CRYPT_ENAB variable in /etc/login.defs to no.

Further, 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 MD5SUM version of the crypt(3) function (this version is backwards compatible and understands DES passwords as well).

5.3. Upgrading the Kernel

The kernel source, which is found in /usr/src/linux/ is not installed using pkgadd(8). 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(8)) 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.

Chapter 6. Frequently Asked Questions

Table of Contents

6.1. General
6.2. Installation
6.3. Configuration

6.1. General

  1. Why the name “CRUX”?

    Well, if you look it up in a dictionary you'll find something like “the basic, central, or critical point or feature”, but the word CRUX also has a UNIX/Linux-ish sound to it.... and I guess that's why I chose it.

  2. When will the next version be released?

    Well, the standard answer to this question is “when it's done”. New versions are however usually released every 3 or 4 months. Between releases, updated packages are made available through the ports system.

6.2. Installation

  1. Will CRUX work with AMD K6/K6-II/K6-III?

    Yes and No. AMD K6, K6-II and K6-III have an i586 (Pentium) compatible instruction set. Packages on the official CRUX ISO are compiled with -march=i686, which means that CRUX requires a processor which has an i686 compatible instruction set (i.e. Intel PPro/Celeron/PII/PIII/P4 or AMD K7/Athlon). However, Jürgen Daubert maintains an i586 version of the CRUX ISO image which can be found here. The i586 version of the CRUX ISO works on AMD K6/K6-II/K6-III.

  2. When booting from the CRUX CD-ROM I get a kernel panic saying “VFS: Unable to mount root fs”. What's wrong?

    This can happen if you have more than one CD-ROM drive. Make sure you boot from then "first" CD-ROM drive, i.e. /dev/cdroms/cdrom0. If you must boot from a different drive (i.e. not the first one) you can still do that but you have to type CRUX root=/dev/cdroms/cdrom1 at the lilo boot prompt (cdrom1 indicates that it is the second drive, cdrom2 that it is the third, and so on).

  3. When booting CRUX for the first time I get the error “Unable to open initial console”. What's wrong?

    You most likely forgot to enable devfs or didn't tell the kernel to mount devfs at boot. The installation instructions (Section 2.2) tell you how to enable it.

  4. When logging in to my newly installed CRUX for the first time it asks for a password, but the installation guide says “Login as root (no password required)”. What's wrong?

    You most likely forgot to edit /mnt/etc/fstab before you rebooted or you entered the wrong name of your new root parition at the lilo prompt.

6.3. Configuration

  1. How do I configure CRUX to be a DHCP client?

    First you need to install the opt/dhcpcd package. Then insert dhcpcd as the first daemon in the DAEMONS variable in your /etc/rc.conf. Remove any references to the device that you want to configure using DHCP (e.g. eth0) from IFCONFIG_UP and IFCONFIG_DOWN (leave the lo device) and clear the ROUTE variable. That is it. Depending on you needs/preferences you might want to edit /etc/rc.d/dhcpcd to pass special paramaters to dhcpcd(8). Example of /etc/rc.conf:

    IFCONFIG_DOWN=("lo down")
    DAEMONS=(dhcpcd crond identd)
  2. How do I get sshd running?

    You have to edit /etc/hosts.deny and/or /ets/hosts.allow to specify which hosts are allowed/denied access. To allow anyone to connect to your machine you can add sshd: ALL to /etc/hosts.allow. See the hosts_access(5) man-page for further information about the file format. When this is done you can start sshd by entering the command /etc/rc.d/sshd start and/or edit /etc/rc.conf and add sshd to the DAEMONS array, i.e. DAEMONS=(... sshd ...), which means that sshd will be started when the system boots.