Copyright © 2001-2002 by Per Lidén
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
Last modified: 2002-07-14
Table of Contents
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.
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.
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.
1.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.
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:
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 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.
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
you might want to check out CRUX Network Setup Guide by Martin Opel or HOWTO install CRUX via NFS by Jürgen Daubert.
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
, 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
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.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.
$ 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
To force the installation (i.e. overwrite the conflicting files)
you can use the option -f (or --force).
$ 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! 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! 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
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:
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! 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
Example (with above /etc/pkgadd.conf used):
$ pkgadd -u bash#2.05-1.pkg.tar.gz
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
$ pkginfo -i
$ pkginfo -l bash
$ pkginfo -l grep#2.5-1.pkg.tar.gz
$ pkginfo -o /bin/ls
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.
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 $
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 execute some sanity
and regression tests on the package. These are:
If the package passes all tests, 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.4 Remove Junk Files
4.1.1 What is a Port?
A port is a directory containing the files needed for building
a package using
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
4.2.1 Synchronizing Your Local Ports Structure
When CRUX is installed for the first time the local ports structure
The$ ports -u
The output reveals which files are downladed, updated and deleted.Connected to cvsup.fukt.bth.se
4.2.2 Listing Local Ports
When the local ports structure has been updated the directory
You can also useautoconf/ dcron/ flex/ libdb/ ncurses/ reiserfsprogs/ tcsh/
The output from the above command will be something like this:$ ports -l
If you are looking for a specific package it might be easier to use this approach (e.g.base/autoconf
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
If version differences are found, the output from the above command could look something like this:$ ports -d
If no version differences were found, i.e. the system is in sync with the ports structure. Then output will simply be:Collection Name Port Installed
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
The$ cd /usr/ports/base/sendmail
To make life a bit easier these two steps can be made into one by using the options$ pkgadd sendmail#8.11.6-2.pkg.tar.gz
or$ pkgmk -d -i
This will download, build and then install/upgrade the package. Note that the package will only be installed/upgraded if the build is successful.$ pkgmk -d -u
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.
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 http://www.cvshome.org/docs/ . 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 CVSROOT=:ext:<username>@cvs.fukt.bth.se:/home/per/crux/ports
Checking out/Updating the contrib tree:
$ cvs checkout contrib (get a fresh copy of the contrib tree)
Adding a new port to the contrib tree:
$ cd contrib
Setting STABLE tag:
By default, when executing ports -u only versions tagged STABLE will be downloaded (this can be changed in /etc/ports/supfile ). Thus, for others to see your changes you need to tag the port like this:
$ cd contrib
4.3.4 CVS Guidelines
The following runlevels are used in CRUX (and are defined in /etc/inittab).
The initialization scripts used in CRUX follow the BSD-style (as
opposed to the SysV-style) and have the following layout.
5.1.1 Configuration Variables in /etc/rc.conf
The following configuration variables are found in /etc/rc.conf
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).
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.
CRUX Handbook - Copyright © 2001-2002 by Per Lidén