CRUX HandbookRELEASE 0.9.3Copyright © 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 1 Introduction 1 Introduction1.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 License1.3.1 PackagesSince 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 ScriptsAll 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 WARRANTYCRUX 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. 2 Installing CRUX2.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:
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.2 Installing From CD-ROM
2.3 Alternative Installation Methods2.3.1 Building Your Own BootkernelIf 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 InstallationIf 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. 3 The Package System3.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 System3.2.1 Installing a PackageInstalling 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 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! 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 PackageRemoving 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
as glibc). 3.2.3 Upgrading a PackageUpgrading 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
database. Example (with above /etc/pkgadd.conf used): $ pkgadd -u bash#2.05-1.pkg.tar.gz 3.2.4 Querying the Package DatabaseQuerying the package database is done by using pkginfo(8)
. This utility has a few options to answer different
queries.
Examples: $ pkginfo -i $ pkginfo -l bash $ pkginfo -l grep#2.5-1.pkg.tar.gz $ pkginfo -o /bin/ls 3.3 Creating PackagesCreating 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 Package Guidelines3.4.1 General
3.4.2 Directories
3.4.3 Stripping/Compression
3.4.4 Remove Junk Files
3.4.5 Pkgfile
4 The Ports System4.1 Introduction4.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 Using the Ports System4.2.1 Synchronizing Your Local Ports Structure When CRUX is installed for the first time the local ports structure
( The$ ports -u -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:
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/ ports(8)
with the -l option to
list all local ports. I.e.:
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 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 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 -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.:
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 -i (for install) or -u
(for upgrade) when executing pkgmk(8)
. I.e.:
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 4.3 Contributing Ports4.3.1 IntroductionThe 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 MaintainersThe 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 ManualThis 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. Settings: $ 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
5 Configuration5.1 Initialization Scripts5.1.1 RunlevelsThe following runlevels are used in CRUX (and are defined in /etc/inittab).
5.1.2 LayoutThe 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.confThe following configuration variables are found in /etc/rc.conf
.
5.2 PasswordsStarting 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 KernelThe 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. 6 Frequently Asked Questions6.1 General
6.2 Installation
6.3 Configuration
CRUX Handbook - Copyright © 2001-2002 by Per Lidén
|