WebHosting Paid by #1Payday.Loans


   The ROCK Linux project has been discontinued in 2010. Here are the old data for the historical record!

ROCK Linux Guide (2nd edition)

Pjotr Prins pjotr@rocklinux.org

20 January 2003

Version 2.0-pre4 (20/01/2003)

Abstract:

This document aims to be a general guide to ROCK Linux. It covers an introduction for those who have never heard of ROCK before, some ROCK philosophy and a general run down on how to download and build ROCK. Furthermore it will introduce you to creating packages and creating your own DIY Linux distribution.

ROCK gives you all you ever wanted in a Linux distribution - and less!


Contents


List of Tables

1 Introduction

             ____   ___   ___ _  __  _
            |  _ \ / _ \ / __| |/ / | |   _ _ __  _   _ _  _
            | . _/| | | | |  | '_/  | |  |_| '_ \| | | | \/ |
            | |\ \| |_| | |__| . \  | |__| | | | | `_' |>  <
            |_| \_\ ___/ \___|_|\_\ |____|_|_| |_|\___/|_/\_|
         [============> https://www.rocklinux.org/ <============]

In front of you you have the second edition of the ROCK Linux Guide. The first edition gave a rundown on ROCK Linux as a distribution, including downloading, installation and several tips and work arounds. Since then a lot has happened with ROCK! Currently development is moving towards supporting a roll-your-own Linux distribution. It will get easier and easier to mould this wonderful Linux distribution into what you want it to be. Already we have people supporting multiple architectures, embedded systems, clusters, or just their own type of workstation and share that with the world. ROCK Linux makes it possible.

Consequently the ROCK Linux Guide has also evolved towards supporting users creating their own packages and modifying ROCK to roll a personal Linux distribution. Taking this wonderful operating system called Linux a step further:

ROCK Linux empowers the user!

This an attempt at creating a Guide to building your own Linux distribution. In the first part we'll download and build one of the ROCK targets. In the second part we'll learn how to create and maintain a ROCK package. In the third part we'll show you how to create your own target distribution (which may be rolled into mainstream ROCK!)[*].

In a way this document is an addition to the INSTALL, BUILD and FAQ manuals (see also [9]) which are decidedly lean and mean and dedicated to get you from A to Z. Quoting Groucho Marx:

I worked myself up from nothing to a state of extreme poverty

So you may find it doesn't help you a fat lot in the end. But it should be a load of fun. It is a journey of discovery...

A lot of material in this document was borrowed from articles and discussions about ROCK. Also it contains both duplicates of, and references to, the other ROCK documents.

At this point I would like to take the opportunity to take away a misconception. ROCK Linux is not hard to install. The binary distributions are really easy and there is really not much to the installation from source.

There are some areas where you need to be a fairly experienced Linux user, e.g. all the packages have to be turned on by hand and you have to be able to understand configuration files from the original packages. ROCK does not contain an intrusive set of system administration utilities. But think again if you see that as a problem. When using complex tools you don't get to understand the architecture of Linux and all its components.

ROCK is clean and aims to do things right. It also teaches you how to do things right. Most people who seriously try ROCK don't go back to other distributions.

This document is being modified every now and then. Do send me your ideas!

Hope you find it a joyful read! Collaboration is what made GNU/Linux great and it is in that spirit ROCK has been created and evolves.



Pjotr Prins 2000 - 2002


Note for Linux newbies: Installing and using Linux involves a steep learning curve. Nevertheless it is a very rewarding experience and after some months you will realise you will never look back. Make sure you have time to dive in and understand what it is all about. Linux is one of the best documented operating systems in the world! Make sure to tap those resources.

The ROCK Linux Guide was written with LATEX and is part of the ROCK Linux distribution. A (nice and printable) version of the ROCK Linux Guide can be created with the included Makefile. The development version of the ROCK Linux Guide can be found at https://www.rocklinux.org/people/pjotr/guide.DEV/.



Linux is a registered trademark of Linus Torvalds
ROCK Linux is Copyright (C) 1998 - 2002 Clifford Wolf
ROCK Linux Guide is Copyright (C) 2000 - 2002 Pjotr Prins
Read the file 'COPYING' for licensing details

2 What is ROCK Linux?

1 Introduction

ROCK Linux is a clean distribution especially intended for system administrators. It is a very good Linux edition for workstations too. ROCK Linux was developed from scratch and is maintained by a collaborative group of people. To quote Clifford Wolf:

It is really easy to create a new Linux distribution

With his experience he may think that obvious, but there are few distribution written from scratch. Most build on existing RedHat or Debian distributions.

2 ROCK is different

ROCK aims to use as few patches on packages as possible

ROCK is different, it takes the form of a group of scripts for building and installing the distributions. There are no fancy installers (though the scripts are very powerful) and one of the basic assumptions is that packages should be installed following the standards of their creators. This contrasts with the patched up systems created by the other distributions. ROCK only patches when absolutely necessary: security and bug fixes only.

ROCK makes no assumptions about the past

If you have been using one of the major distributions like SuSE or RedHat you'll realise a lot of items been patched in. This increases the dependency on those distributions (intended or not). It is hard for the larger distributions to revert on this practise because of backward compatibility issues (read upgrading). ROCK will patch some sources (for example when a package does not comply with the FHS).

ROCK contains the latest versions of packages

Packages, including the Linux kernel, get downloaded from the original repositories. For each package the ROCK distribution maintains a package file which points to the ftp location and filename. Sometimes the ftp site changes, more often the version numbering of a file changes. At that point the package file needs to be edited. After a successful download you may send the patch to the ROCK Linux maintainers - so others get an automatic update.

One great aspect of ROCK is that is usually points to the latest packages. And if you are using the development version of ROCK you will also be using one of the latest kernels.

It has been proven that the enormous struggle with the packages (treated individually as well in the aspects of a whole build) performed by the ROCK developers helps in finding bugs, reaching from very trivial to the very intricate.

One great benefit of Open Source software is software gets updated often. With ROCK you get a tool to update your entire distribution often - instead of regularly updating the kernel and packages by hand. Together with a tool like cfengine (GNU Configuration Engine, see [1]) you get an environment which can be updated easily. In fact ROCK users tend to run really up-to-date systems.

ROCK is built optimally

With ROCK all packages are built with the optimisations you want and the platform you target. Other distributions usually build for generic i386 or Pentium. With ROCK you can automatically build X and packages like the GIMP optimally for your architecture.

ROCK is cross-platform

Portability is a great advantage of ROCK Linux. It is possible to cross-compile easily or add new achitectures in a short time. There is support currently for PowerPC, Alpha, Sparc. It is possible to cross-compile for PowerPC from an Alpha (for example).

ROCK is ready to burn on a CDROM

After building ROCK from sources you can burn the (target) ROCK distribution directly onto CDROM (and pass it on to others). The full source distribution often fits on a single CD.

ROCK can easily be installed over a network

The installation process is terminal based. Installing remotely and configuring the new system over a network connection is not uncommon.

Services have to be turned on explicitly (added security)

Also packages and services have to be turned on by hand. When you boot a fresh ROCK installation you'll find the minimum of services installed.

From the system administrator's perspective this is ideal for new installations. It compares favourably with cleaning up and closing all services of a bloated commercial distribution.

ROCK adheres to standards

ROCK gets as close to standards as it can. But with a pragmatic view. For example it uses the FHS (File Hierarchy Standard), but with exceptions (mostly because the original source packages don't comply). For more information see the FAQ and the fhs.txt file [7].

ROCK is complete

The base distribution of ROCK is rather small - and you can get a compact functional system. Nevertheless, with the complete packages the distribution is rather complete. Included are, for example, the GNOME and KDE environments.

ROCK uses few resources

Most ROCK installation scripts are sh scripts (so can be interpreted from bash). This makes it possible to create single disk distributions like the rescue, telnet and router sub-distributions. A full ROCK distribution (all sources of the packages) still easily fits on a single CDROM.

Extending ROCK is easy

In the case you want to add a package to ROCK create an extension. If a base package has changed modify the puzzle file and send it in. Extending ROCK helps everyone.

At this point ROCK includes hundreds of packages including the full GNOME environment.

Scripting is power

Because of the fact that ROCK consists of a bunch of scripts it is easy to see what is happening under the hood. Also it gives possibilities to change the distribution for your own needs. The sub-distributions are just examples of such adaptions.

In fact the system proves very powerful just because of the scripting system. Wasn't that the original philosophy behind Unix?

ROCK comes with its own embedded scripting engine

/bin/sh (no kidding). In fact this has deeper implications then you might think. Shell scripting can be as powerful as any computer language (someone even wrote an assembler in bash a few years ago) and it comes with most flavours of Unix. Anywhere in the download and install scripts you can insert your own hooks. It is the reason why so many projects are spinning off ROCK.

ROCK is flexible

The package system is not specific to the ROCK Linux distribution. Because packages are built from sources it is possible to download the ROCK scripts and just download and install a package. E.g.:

./scripts/Download -package xemacs
./scripts/Build-Pkg xemacs

downloads and builds xemacs and all the packages that got included in the extension. This looks a bit easier than it is - you may have to build other packages to take care of dependencies, but the build output files should spell that out for you.

Partially updating an existing system is also possible this way.

Kent Skaar has created a library of GNU tools on top of Solaris this way. Very useful if you want to use the latest and greatest on propriety Unix systems.

In principle other package managers can be used on ROCK. So far not much effort has gone into that type of functionality, the ROCK package system appears to deliver what people need, though it may change in the coming year.

ROCK is the ultimate DIY distribution

The build and install system is easily accessible and modified to one's own needs. Furthermore the direction ROCK development has taken emphasises this particular strength of the distribution.

ROCK uses your hardware

Now this may be a geeky thing, but if your hardware has never truely been tested (and SETI is not good enough) try executing a ROCK build. You'll bring both CPU and hard disks to maximum temperature.

There is no other distribution like ROCK Linux

By now it should be clear ROCK does not look like any of the other distributions. Debian, while also a collaborative effort, is a great distribution but is in many ways more like the commercial editions. FreeBSD comes closer though it handles its package download from a single resource.

The only one that comes close is Gentoo Linux. It is interesting to see where the two build-it-yourself distributions compare and differ:

ROCK Gentoo
bash based Python based
chroot build chroot build
ROCK 'bash' package system 'Makefile' based package system
Admin oriented Desktop oriented

It has been stated ROCK Linux is more BSD with a GNU core than anything else: ROCK has a ports collection (called extensions), a make world (called ./scripts/Build-Target) and like OpenBSD prefers the disabled feature by default method. This may make OpenBSD ROCK's closest relative.

3 Sub-distributions and Targets

Before ROCK 1.7 sub-distributions where compiled out of a fully built distribution as a sub-set. Recently 'targets' have become a smarter way of dealing with specialisation. A target limits its download and build to what is really required.

Currently a number of ROCK based sub-projects/targets exist or are in development. These are implemented as sub-distributions:

1 Rescue

The rescue sub-distribution is a minimal ROCK distribution that can be used to build ROCK Linux. Very useful when you have to start from scratch, or when you need to build on an unwilling system.

The rescue distribution also can help you rescue a crashed system.

2 Router

The router sub-distribution is a minimal ROCK distribution for routers.

3 Telnet

The telnet sub-distributions can be run from a floppy and boots any Intel based system so you get a telnet session.

4 dROCK

Desktop ROCK. A beefed up version for the desktop with many nice features. dROCK is a target distribution in 1.7.

5 Other

Other sub-distributions are under development. One implemented by Clifford installs a full room of computers from a central server. Useful for training sessions. The scripts can be found on the main distribution.

4 Packages

ROCK carries its own package system. For a description of each packages see https://www.rocklinux.org/packages. While not as extensive as Debian or FreeBSD ports, it is complete and rather clean. One real benefit of ROCK is the ease of creating new packages (see part II).

5 Community

ROCK has a mailing list and an archive thereof. It is a good idea to subscribe and to voice your ideas and amendments. Not like Groucho:

It is better to remain silent and be thought a fool, than to open your mouth and remove all doubt.

At this point it is a low key affair. Clifford is very central to ROCK development & maintenance and spends part of the time improving the system and applying patches.

It is obvious after some time on the list that a lot of discussion takes place off-line, or in private E-mail conversations. Much of the philosophy of ROCK can be contributed to Clifford's adaptable insights and the fact that ROCK gets used in many production environments.

Often there is discussion on IRC:

irc.openprojects.net channel rocklinux

You can find a threaded digest of the mailing list at https://www.rocklinux.org/ or download the archives through:

# rsync rsync://www.rocklinux.org

which shows the rsync 'modules'. The following fetches/synchronises all the mailing lists:

rsync -vaz rsync://www.rocklinux.org/rocklinux-webpage/mailing-list/ rock

Then there is the ROCK Linux portal at https://www.rocklinux.net/which, apart from updates on Dilbert, gives updates on changes in ROCK and CERT updates (security notifications). This should be the home page on your browser.

Finally the ROCK Linux website contains a nice search facility which can be really helpful. In fact, before sending a mail to the mailing list, take a quick look first. It is likely someone has had the same problem before.

3 Download

1 Downloading the ROCK Linux distribution scripts

First thing to do is to find one of the ROCK Linux versions and download it from https://www.rocklinux.org/ (see also 'Which Version of ROCK' in appendix [*]). Stable versions are even numbered on the second digit (like ROCK 1.6.0) but can be a tad old. Development versions are uneven (like ROCK 1.7.0-DEV) and the current development version is called 'DEV'. A tar ball of the distribution scripts is a few Megabytes in size and downloads quickly.

ROCK's stable versions go hand-in-hand with stable Linux kernel versions. Nevertheless most ROCK users use the development versions of ROCK Linux anyway (see appendix [*]). One addicting feature of ROCK is that you get the latest version of every package, including the kernel. The development versions of ROCK have proven to be pretty robust. Nevertheless a development version can potentially be broken.

Untar the file and it unpacks documentation, installation scripts and the directories for the to-be-downloaded packages.

The size of ROCK Linux is so small because it is only contains the basic system (scripts) for downloading the kernel and packages from the Internet. The rest of the distribution gets downloaded in the next phase.

1 Using the scripts

Once you have unpacked the distribution you can see directories like:

The scripts are invoked from the ROCK directory. E.g.

# ./scripts/Config
# ./scripts/Download -required

The full options of ./scripts/Download are[*]:




Table : Output of scripts/Download (1.7):

Usage:

 ./scripts/Download [options] [ Filename(s) ]
 ./scripts/Download [options] -pattern Pattern(s)
 ./scripts/Download [options] -package Package(s)
 ./scripts/Download [options] -repository Repositories
 ./scripts/Download [options] { -all | -required }

 Where [options] is an alias for:
    [ -cfg <config> ] [ -nock ]  [ -alt-dir <AlternativeDirectory> ]
    [ -mirror <Mirror> | -check ]  [ -try-questionable ]
    [ -notimeout ]  [ -curl-opt <curl-option>[:<curl-option>[:..]] ]

 On default, this script auto-detects the best ROCK Linux
 mirror. Use '-mirror none' to use the original download
 locations instead of one of the ROCK Linux mirrors.

 Mirror can also be a local dir in the form of 'file:///<dir>'.

 ./scripts/Download -mk-cksum Filename(s)
 ./scripts/Download [ -list | -list-unknown | -list-missing | -list-cksums ]

ROCK comes with a nice help system. If you start a script without parameters it will tell you what to do. You can also call help directly. E.g.

# ./scripts/Help Download




Table : Output of ./scripts/Help Download (1.7):

The ./scripts/Download script is the tool for downloading the package sources.
Calling the script without any parameters prints out the help message.

You can download single files:
        ./scripts/Download download/P_base/linux/linux-2.4.18.tar.bz2

All files for a single package:
        ./scripts/Download -package linux

All files required for building the configured target:
        ./scripts/Download -required

Or simply everything:
        ./scripts/Download -all

If you don't specify a mirror using the -mirror option, the script will
contact www.rocklinux.org and auto-detect the best mirror.

Downloading all files required from a local (mounted) cdrom:
        ./scripts/Download -mirror file:///mnt/cdrom/ -required

2 Configuring ROCK

Since ROCK 1.7 running ./scripts/Config is required before a download to define the target [*].

Start the configuration with:

# ./scripts/Config

which compiles the configuration program (you need gcc installed for this).

Relevant targets are:

where dROCK gives wider functionality for desktop users. Generic ROCK Linux does include Xfree and GNOME, so it makes a minimal desktop too.

Finally, at this stage, under the expert menu it is possible to prepare selection of packages for the install phase. This allows for fine-tuning your install cycle.

Quitting ./scripts/Config the first time a directory config is created with the selected settings. These are text files, have a look.

The other configuration options are discussed in [*].

3 Downloading the ROCK distribution

Downloading the full ROCK Linux distribution takes a while - depending on how fast you can move up to 1Gb over your pipe. While waiting you may want to go out, sleep, work and go through that routine again.

I drink to make other people interesting

# ./scripts/Download -required

Downloads the selected packages with which you can build a running system. See [*] for some tips.

The Download script may complain you have the wrong version of bash and you need curl (see [*]).

1 INDEX and Puzzle

A complete list of the files to be downloaded for a target is generated in ./download/INDEX. This file is generated from the package definitions with the ./scripts/Puzzle script. This script needs to be run every time you change the contents of the package descriptions (download path/checksum).

2 Mirrors

Quite a few supporters of ROCK Linux have created mirrors for source tar balls. ./scripts/Download tries to select the fastest mirror.

Sometimes a mirror is incomplete or out-of-date. Running ./scripts/Download with the -mirror none option will fetch the sources from the original www or ftp sites. If some downloads fail from the mirror(s) try this.

# ./scripts/Download --mirror none -required

To select a specific mirror:

# ./scripts/Download -mirror \
    ftp.nluug.nl/pub/os/Linux/distr/ROCK/rocklinux/ROCK-Devel -required

3 Missing files?

When files are not found Download gives an error. It could be the file has changed version number or even moved to another site. This occurs regularly, but fortunately it is manageable.

Missing packages are not necessarily a problem. If you are aware what a package does and you know you don't actually need it you can pretty much ignore the error. For base packages it is usually a good idea to fetch them all.

Read the FAQ on 'I have problems downloading the source-code-package'.

It may be useful to download the most recent version of ROCK (stable or DEV) since it will reflect the most recent state of the original packages.

To actually find which files are missing run:

# ./scripts/Download -list-missing

4 Unknown files

When going through several cycles of upgrading and downloading packages (see also [*]) you'll find the same packages with different versions of tarballs in your download tree (e.g. apache-1.25 and apache-1.26). The older files (apache-1.25) are considered redundant and are named 'unknown files' in ROCK jargon.

# ./scripts/Download -list-unknown

To remove unknown files (stripping the Unknown file comment using sed try:

./scripts/Download -list-unknown|sed 's,^Unknown file: ,,g'|xargs rm -f

5 Fixing URL's

If a package fails to download because it is not on a mirror and the original has moved away you may want to fix the URL in the package directly.

Find the package in the package directory and modify the package.desc directly. Update the URL in the [D] field and set the checksum to 0. Also update the [V] version field if it has changed.

With the fixed URL run ./scripts/Puzzle followed by the
./scripts/Download -mirror none -required command.

Downloading a single package can be forced with

./scripts/Download -package packagename

If it worked and the package builds fine (see [*]) it is recommended you send in the change to the ROCK maintainers - to prevent other people from going through the same work (see [*] for more information). The one thing you'll have to do is to fix the checksum in the [D] field (see [*]).

6 Checksum

The Download script has a facility for checking the integrity of the downloaded packages:

# ./scripts/Download -check -all

walks through all the packages and checks for matching checksums. If a package got corrupted, one way or the other, it returns an error.

To get the checksum of a single tarball

./scripts/Download -mk-cksum path

7 Updating The ROCK Sources using Update-System

The Update-System script uses rsync to pull the latest version of scripts and packages of the development tree. Mind this is a dangerous feature - development trees can be broken.

4 Troubleshooting

1 cURL

From version 1.7 ROCK Linux needs cURL. If you don't have it download it from https://curl.haxx.se/ and run the commands

./configure
make
make install

5 Tips

Before starting a new download it is an idea to create the 'download' directory and mount it from elsewhere (a symbolic link will not work with the build phase later, though in this stage it will do) this way you can use the same repository when moving to a new version of the ROCK Linux scripts (check [*]). Remember to rerun ./scripts/Puzzle (see [*]).

4 Build

1 Preparing your build system

The first time you start building ROCK on a non-ROCK distribution it may be wise not to build in your normal working environment because it may require some kernel patching and changes to LILO, but to dedicate a special build host.

Most of the issues mentioned in this chapter disappear magically when building on ROCK itself. The most important reason being that some current Linux distributions are not based on devfs. This problem will disappear in the coming year when devfs gets fully adopted (it is already standard in the Linux kernel).

Furthermore you have to realise you have downloaded all necessary tools to build a ROCK distribution. All required packages are sitting in the ./download directory. Furthermore ./package contains all the hints to build these packages successfully.

Prerequisites for building ROCK are (from the FAQ):




Table : From the FAQ: prerequisites (1.7):


      

More information can be found in the trouble shooting section (see [*]).

2 Building ROCK

This section discusses the ROCK build system as it has been implemented since version 1.7 (for older versions see [*]).

1 Building your Target

To build the target (after selection see [*]) execute

./scripts/Build-Target

which starts building all the stages (see [*]). The output of the build can be found in
./build/default-*/logs.

2 Cleanup

Every package gets built in a directory named ./src.packagename.timeid. To remove these packages (if there is an error it can be useful to check the content of the partial build!) use

./scripts/Cleanup




Table : From Documentation/BUILD (1.7):

Simply type './scripts/Cleanup' to remove the src* directories. DO NOT REMOVE
THEM BY HAND! This directories may contain bind mounts to the rest of the
source tree and it is possible that you are going to remove everything in the
ROCK Linux base directory if you make a simple 'rm -rf' to remove them ..

Type './scripts/Cleanup --full' to also remove the build/ directory.

3 Build Broken

This happens often. Packages can break because the go out-of-date (dependencies don't work) or because the downloaded package mismatches the build scripts, or maybe, because there is something wrong with your build environment.

The output of the build process is captured in the directory ./build/default-*/root/var/adm/logs. All the packages with errors show the .err extension.

Check the content of the error files to see if you can fix the problem (see also [*]).

Before starting the rebuild tick 'Retry Broken Packages' in ./scripts/Config.

4 Build Stages

Stage 1: Builds the minimal set of packages for building packages (gcc etc.) on the build system's root

Stage 2-8: Chroot into the stage 1 environment and builds all packages

Stage 9: Rebuilds the full system to resolve possible dependencies

The packages that have to be build in every stage are defined in ./config/default/packages. ./scripts/Build-Target invokes ./scripts/Build-Pkg for every package chroot'd in the ./build directory.

5 Configuring Build

Useful options in ./scripts/Config are:

Abort when a package-build fails:
Deselect normally, so your build continues (there are always failing packages
Retry building broken packages:
When starting a rebuild (after fixing a package) the build retries the packages it could not build before
Always clean up src dirs (even on pkg fail):
Select when you need the disk space - though it can be useful to have the src dir when you need to troubleshoot
Print Build-Output to terminal when building:
Select for exiting output
Make rebuild stage (stage 9):
Select because it may solve dependencies between packages. The downside is a doubled total build time

3 Building a package

Running the ./scripts/Build-Pkg script will build and install a package into the root of the filesystem you initiate it on - i.e. standard it overwrites your current install. For example

./scripts/Download -package ruby
./scripts/Build-Pkg ruby

The results of the build can be found in /var/adm/log/packagename.log - or with the .err extension if it fails.

Options for ./scripts/Build-Pkg are




Table : Output of scripts/Build-Pkg (1.7):

Found 7 new/updated files in source tree:
-> Found new/updated file: config/default/.
-> Found new/updated file: config/default/config
-> Found new/updated file: config/default/packages
-> ** list truncated to save space on the terminal **

Re-running configuration:
-> Running ROCK Linux 1.7-snapshot configuration ...
-> New config written to config/default/*.
-> Cleaning up. Configuration finished.

Building tools in build/default-1.7-snapshot-ia32-pentium3-cross-generic-expert:
-> Building tools/wrapper/cc-wrapper.
-> Building tools/bin/getdu.
-> Building tools/bin/getfiles.
-> Building tools/bin/fl_wrparse.
-> Building tools/bin/fl_stparse.
-> Building tools/lib/fl_wrapper.so.
-> Testing tools/lib/fl_wrapper.so.
-> Creating tools/lib/parse-config.

Usage: ./scripts/Build-Pkg [ -0 | -1 | -2  ... | -8 | -9 ]           \
                           [ -v ]  [ -xtrace ]  [ -chroot ]          \
                           [ -root { <rootdir> | auto } ]            \
                           [ -cfg <config> ]  [ -update ]            \
                           [ -prefix <prefix-dir> ]  [ -norebuild ]  \
                           [ -noclearsrc ]  [ -pkgdir <pkgdir> ]     \
                           [ -id <id> ]  pkg-name(s)

Type './scripts/Help Build-Pkg' for details.

4 Troubleshooting

1 umount -d or -l Not Recognised

If your version of umount does not support the -d and/or -l option you can remove those options from the ./scripts/Build-Pkg and ./scripts/Cleanup scripts or, alternatively, update util-linux and/or your kernel.

2 No cleanup of source trees

When your version of umount does not support the -d -l options you need to remove them from the scripts (see [*]).

3 ERR: not a signal specification during Build

Upgrade bash on your build system.

4 devfs

ROCK builds on a kernel with devfs support. If you get the latest versions of the kernel (in ./download) devfs is included. Older systems probably have to be patched.

Unless you want to enable devfs at boot prompt (see below), don't forget to turn the 'Automatically mount at boot' option in the kernel menuconfig on (does only appear if you have already '/dev filesystem support' ticked.

A work around, if you have enough disk space, is to download one of the ROCK rescue binaries (<100 Mb) which give you a full build system. Install and boot into it and you are almost done. It may be even easier if you have a binary ROCK image on CDROM to kick off with. ROCK builds easily on an existing ROCK installation.

5 Free Disk Space

Another issue regarding building is that you need quite a bit of free disk space. After downloading all packages (1Gb) you need another 2.5 Gb to build everything. Thereafter you'll need enough space to install the newly built system on.

6 Building on a non-ROCK system

Non-ROCK installation take a little more preparation in general. If you have to build on a RedHat or SuSE system run, for example, menuconfig from /usr/src/linux and turn the (experimental) dev file system on. Also download (if not already in the ROCK archive) and build devfsd.

7 SCSI

SCSI users may find the 'devfs and SCSI' page helpful: https://www.torque.net/sg/devfs_scsi.html. On RedHat it required rebuilding the kernel and modules (on RedHat) with devfs turned on, and automount. Don't forget to include the SCSI drivers in the kernel and ramdisk (and if you are going to use nfs mounting include loopback and network block device support). For more information on configuring the kernel see section [*].

8 Bootfloppy images

If you don't succeed rebuilding your kernel and booting up because of one reason or another there is one more strategy. Download the ROCK floppy images so you can have a look at your disk partitions.

9 LILO settings on build system

With devfs all discs, whether SCSI, IDE or whatever, are placed under the /dev/discs hierarchy:

        /dev/discs/disc0        first disc
        /dev/discs/disc1        second disc

Each of these entries is a symbolic link to the directory for that device. The device directory contains:

        disc      for the whole disc
        part1..   for individual partitions

One thing to remember is that the outdated /dev/sda1 and /dev/hda1 numbering schemes are base 1 and that devfs is base 0 (except for the partition numbering - believe it or not).

Another thing to remember is that, on the Intel platform, IDE drives are numbered before SCSI drives.

To directly specify the first scsi or ide partition use:

        /dev/scsi/host0/bus0/target0/lun0/part1 
        /dev/ide/host0/bus0/target0/lun0/part1

My LILO settings for the original RedHat kernel and devfs kernel:

# boot=/dev/sda   - with non-devfs lilo
boot=/dev/discs/disc0/disc    

image=/boot/bzImage
  label=linux
  append="root=/dev/discs/disc0/part3"
  read-only

Where the kernel was compiled with devfs and mounts devfs at boot (note: some users have experienced the /dev/discs notation did not work while the alternative /dev/ide or /dev/scsi did).

These parameters can also be given at the lilo prompt (for more information see [6]):

lilo: rock root=/dev/ide/host1/bus0/target0/lun0/part1 devfs=mount,nocompat

10 Troubleshooting devfs

The following (useful) options are available from the boot prompt:

  devfs=mount,nomount,compat,nocompat 
  root=/dev/ide/discs/disc0/part1

The root parameter takes the place of your '/' position. If it was /dev/hda1 you can use devfs speak /dev/ide/discs/disc0/part1. For SCSI you can find /dev/sda1 at /dev/scsi/discs/disc0/part1 (or /dev/scsi/host0/bus0/target0/lun0/part1).

Which should overrule kernel compile settings/lilo configuration.

If it still doesn't work after trying to use nocompat and you get a 'Could not open initial console' error message. That means there is no /dev/console. Normally mounting /dev would be the first thing the init script does. devfs=mount forces the kernel to mount it automatically and so an initial console can be opened.

That probably wouldn't solve your problem, but will give you more information. (Like 'can't start init' or whatever. Maybe you have configured the wrong root partition in lilo.conf ...)

With the later kernels it is not necessary to use the devfs daemon (devfsd) if you use mount at boot.

Note: The combination building ROCK on an old lilo and non-devfs installation can be daunting. A RedHat installation succeeded after upgrading lilo itself. With an older SuSE installation I gave up and installed an older ROCK version from CDROM to execute the build phase. With the kernel move to devfs it should be easier using one of the latest distributions.

Note: Just to complicate matters devfs changed its naming convention at least once. Since ROCK was an early adopter of devfs the older editions (including stable 1.2.0) use a different notation:

    root=/dev/sda6                                Outdated original
    root=/dev/scsi/host0/bus0/target0/lun0/part6  Current
    root=/dev/sd/c0b0t0u0p6                       Other

Final remark: When having trouble running fsck on a boot partition (and the boot process rebooting automatically in an endless loop) the problem is that devfs can not mount on /dev - because root is mounted read-only and fsck is not able to 'fix' the filesystem. Running lilo with the -b rw option sorts that.

11 Fixing Broken Packages

With every version of ROCK Linux you'll encounter the phenomenon of broken packages. This is a natural evolution path of packages where download links go out of date when open source software gets updated with new versions (to fix these see [*]) or when a package fails to build because of dependency changes - or just bugs.

ROCK provides some useful tools to help you fix broken builds. In ./scripts/Config select:

*
Retry building broken packages
Always clean up src dirs (even on pkg fail)
*
Print Build-Output to terminal when building

When a package fails to build you'll see the a package build directory .src.packagename.dddddd... sitting in your ROCK tree. This contains the full build tree for a package until the point the compile stopped. In the tree you'll find a file named R.src/debug.buildenv which contains the environment settings during the build and a script debug.sh which loads those environment settings before a build.

These tools allow you to verify the environment and compile a package by hand.

5 Tips

1 Build for Speed

Recent versions of ROCK support some form of a distributed build.

@@FIXME

For less esoteric setups simply using RAID 0 (striping mode) using two IDE drives over two IDE channels speeds a build up significantly. This is because building packages is IO constrained. Upgrading a CPU may have less effect.

An obvious optimisation is to select a target which builds the fewest packages, exclude building ext packages and skip the final rebuild (stage 9).

5 Install

1 Introduction

This chapter of the Guide is still largely based on pre-1.7 installs and will be updated shortly.

With 1.7, if nothing else works, you should read [*].

@@FIXME

2 Preparing for an Install

After a successful BUILD it is time to install. Prepare a free partition for installation of your fresh ROCK distribution. Use fdisk and mkfs - also it may be an idea to run badblocks on an older system.

Partitioning the hard drive is a matter of taste. It is recommended practice to have a partition with a basic bootable Linux system - and a working lilo (which is great if you need something to fall back on). That can be very convenient when wanting to install a new version of ROCK. Some people like a small /boot partition for their kernels, an partition for swap space and a large partition for the rest.

To install burn ROCK to a CD (see [*]), make the bootable floppies or unpack one of the sub-distributions onto a partition.

At this point it is wise to read the INSTALL document provided with the ROCK Linux installation (see [7]).

3 Bootable CD

If you have a bootable CDROM, or if you have created one after building ROCK, installation is really straightforward (though you may have to tell your bios to do so). Boot it up!

If you have trouble in this phase read paragraph [*].

4 Bootable Floppies

The floppy images are in rock-base-<version>/<arch>-floppies. These images can also be found on some ROCK mirrors:

# dd if=boot-floppy.img of=/dev/fd0
# dd if=root-floppy.img of=/dev/fd0

Floppies can also be made with the mk-bootdisk.sh and mk-rootdisk.sh scripts that come with the distribution. This is convenient when you need to use a special type of kernel (Read the Linux Boot-disk HOWTO for more information [2]).

It is also possible to copy the floppy distribution to a disk partition and boot into that for installation.

For example (on a newly mounted partition):

# tar xvIf install-disks.tar.bz2
# mv boot-disk/* .
# mv root-disk/* .

The same can be achieved with (the recent edition of) the rescue sub-distribution of ROCK. Untar the contained directories and modify your existing lilo.conf to point to the new partition (for an example and devfs naming conventions see [*]).

With non-standard hardware you may have to install the Linux kernel sources and recompile the kernel using the chroot environment mentioned below. The rescue edition comes with the sources in /usr/src/kernel. Unpack the Linux tar ball in /usr/src, and (optionally) apply the patches and copy the supplied config file to .config before compilation.

If you are running a ROCK distribution you will find the instructions and files to build boot and root floppies in /usr/lib/boot-disk. Check the README file. Once you have a kernel image it is very straightforward.

Before rebooting from a changed lilo it may be a good idea to set the root password and create (and test) a rescue floppy for your existing system. Or use one of the images from: https://www.ibiblio.org/pub/Linux/system/recovery/!INDEX.html (see also [2]).

Edit lilo.conf and run lilo (chroot'ed).

If you have trouble in this phase read paragraph [*].

BTW: There exists a neat trick: If installed on a separate disk drive, you can use the (SCSI) bios to select what drive to boot to - preserving your old (non-devfs) installation. You can have different boot records on different disks.

5 Starting the Install

Use fdisk and the mk* commands to create the target partition and the swap space (see the INSTALL document [7]).

Turn on swap space. E.g.

# swapon /dev/discs/disc0/part3

Mount the target partition

# mount /dev/discs/disc0/part4 /trg

Mount the source (a combination with a symbolic link is possible - the Install script will tell you what the path should look like):

# mount /dev/discs/disc0/part1 /src

Run the Install script:

# Install

which invokes Install.bin with the src and target directories as its parameters. Checking the compiled ROCK image you'll find Install.bin in the root directory. This is the actual installation program and can be invoked directly.

You can type 'help' at the installer command line for the options. With the 'list' command you can see what packages are included in your install.

The quick route: type 'select */*' followed by 'install'. Extension packages can be listed with 'list-ext' and imported with the 'import' command. Alternatively you can install the extension packages later on the final system (see also [*]).

The Install script will lead you through a number of questions like keyboard mapping, language etc.

Before rebooting the minimum you have to do is change the root password and lilo.

# cd /trg
# chroot . /bin/bash --login
# passwd
# vi lilo.conf

Edit lilo.conf so it points to the right partitions. To be sure also include the entries for your old partition(s).

# lilo

Also you could kick off and start doing some other useful changes.

Add the following line to your /etc/conf/devfs file:

ln -sf  /dev/discs/disc0/part3       swap

Add the following line to your fstab file:

/dev/ide/host1/bus1/target0/lun0/part4 /home ext2 defaults 0 0 
/swap       swap                             swap defaults 0 0

And add the other entries that match your (devfs type) partitioning (otherwise you won't be able to boot).

If the machine you are installing on has no monitor it may be useful to set up serial support for lilo and init (for more information see appendix [*]).

Cross fingers: Reboot!

6 Direct Installation

Right after the build you basically have all the built binary packages sitting in tar files. To install ROCK Linux there is no real need to use the install program! It is quite cool just to create a target root directory (with or without NFS) and untar the packages you really need. Just as fast and often just as handy. You can even create your own script to achieve a minimal build (e.g. for a firewall).

cd target
tar xvIf listoftars

and run the setup scripts by hand in /etc/setup.d

chroot . /bin/bash --login
find /etc/setup.d/* -exec bash \{\} \;

Finally run lilo (see [*]).

7 Post Installation

After a successful installation the time comes for setting up the network environment, runlevels, services, X (using xf86cfg or xf86config) and extension packages.

The install procedure runs a number of scripts which will ask you for time-zone, keyboard, network configuration, ssh, libsafe etc. You can run these scripts later by hand from /etc/setup.d.

After running these scripts you can run runlvedit to change runlevel settings - what processes you want to be started at boot time.

It may also be useful to rebuild the Linux kernel for hardware support, networking options etc. For this you may want to create a new config file (e.g. using 'make menuconfig') and diff the original config file against it.

Since ROCK Linux users like to keep their systems up-to-date they usually make a copy of their /dev and /home directories and, with reasonable efficiency, duplicate the older settings.

To find configuration examples ROCK Linux provides an example-config tree which contains example configuration files of other users (e.g. colour settings for vim, mutt and sensible xterm configurations). It is a good source for getting ideas. If you want to contribute some of your configuration files send them in!

To automate rebuilding your configuration it is possible to use cfengine (the GNU Configuration Engine, see appendix [*]).

8 Managing Packages

Installing an extension package can be done during the regular build/install cycle, but also separately:

# ./scripts/Build-Pkg package

And untar the package by hand (if the installer hasn't done so):

# tar -C / xvIf package.tar.bz2

9 Troubleshooting

If the boot procedure, from CDROM or floppy, stops along the way you may have to rebuild the Linux kernel for your hardware (see [3]).

An immediate halt after 'loading Linux kernel' indicates your kernel has been built for the wrong CPU.

A 'can not load root' message indicates your kernel can not find the root partition (common when moving to devfs). Indicate a root partition at the boot prompt (see [*]).

A 'can not find tty' message indicates the supplied root partition hasn't got a proper /dev directory. This is usually caused by a non-devfs /etc/fstab file. Mount /dev by supplying a valid root path (of the /dev/ide or /dev/scsi type) and edit the fstab file once booted.

A kernel panic may imply are using a SCSI adaptor for your HDD which has not been compiled into the kernel.

And finally: if you don't have a CD drive and can't make an NFS mount you can select to prepare an install with only the Install.bin, base-pkgs and info copied on the hard drive. Because ROCK is so transparant procedures like these have saved me in the past!

1 Shared libraries error

A login error like:

shared libraries: /usr/lib/libshadow.so.0: undefined symbol: 
libshadow_md5_crypt

may indicate your shared libraries have not been found. Check /etc/ld.so.conf - the link to /usr/cpu-*/lib may need to be changed if you recompiled the kernel for a different CPU type.

Make sure to run ldconfig.

2 LILO

If, somehow, lilo is screwed and you can't boot into your system the best option is to boot from floppy or CD, mount the partition and run chroot:

mount /dev/discs/disc0/part7 /mnt
cd mnt
chroot . /bin/bash --login

Edit /etc/lilo.conf and rerun lilo.

6 The End

From the moment I picked your book up until I put it down I was convulsed with laughter. Some day I intend reading it!

You have read the first part of the ROCK Linux Guide. The other parts on creating packages and rolling your own distro should be completed later this year. The latest development version of this document can be found at https://www.rocklinux.org/people/pjotr/guide.DEV/.

PART II

7 Introduction to the ROCK Linux Architecture

This section is in the process of being written.

8 Extending ROCK

1 Introduction

ROCK is built around shell scripts. These scripts access the files in ./config to build the packages from source.

These scripts run with some environment settings (see Appendix [*]).

There will come a day when you want to contribute a package to the ROCK tree - because you find you are building that package from source every time you do a clean install.

Mastering the package system is a good idea if you deploy similar configurations across machines. If that is your daily work your job title may be 'system administrator'.

Packages that don't get accepted in the main tree (or as an extension) can still be useful. There are many examples of this. You can use the ROCK installation engine for whatever purpose you want. At some point you may find you are creating a new sub-distribution, or working on a cross-compile of GNU/linux/ to other architectures.

To get a grip on how the Build scripts work the best thing to do is take one of the smaller standard packages and build them by hand. Start changing parameters and see what happens in /var/adm/logs and the ./src trees.

# ./scripts/Build-Pkg package

By studying existing config files you'll find there are a number of interesting features.

A standard configure type build doesn't even need scripting. ROCK does that all for you.

When packages need special configuration parameters or command sequences write them directly into the shell script.

2 Preparing

Usually you have already compiled and installed the program you want to convert to a ROCK extension package.

Find and download the tar balls you need in a directory for that purpose.

At this point it is worth checking what the installation documents say. For example you may need to use configuration options like:

--prefix=/opt/package

Once you have downloaded the latest packages they are most likely not in the bz2 format. If you have slow lines and want to prevent a second download you may want to copy the tar balls directly into ext-archive. For example:

gzip -d /var/packages/package.tgz
bzip2 /var/packages/package.tar
mkdir ./ext-archive/package
cp /var/packages/package.tar.bz2 ./ext-archive/package

3 Package fields

1 Download descriptor [D]

The checksum can be generated with the help of the Download script:

./scripts/Download -mk-cksum /var/packages/packagename.tar.gz

Renders:

/var/packages/packagename.tar.gz: 4194917907

All tar, bzip and bzip2 versions of the tar ball render the same checksum.

4 Installation script

In case your package goes beyond standard configure or has its own uncompliant installation procedure some scripting is required.

It is quite possible you need to do some patching. In the case of xfig XPM was needed and after copying the original Imakefile to Imakefile.old it was changed and a diff was run:

diff -uN Imakefile.old Imakefile.old

And the output can be added as a patch into the configuration directory. ROCK automatically applies the patches.

5 Puzzle

After creating the package files you have to notify ROCK where to find it. This is achieved by running ./scripts/Puzzle.

./scripts/Puzzle

6 Testing

Before wrapping up your extension and sending it in test it exhaustingly through several package builds and make sure:

7 Sending it in!

1 Getting your package into ROCK

The first time you contribute an extension package you may want to send it in, as a file, to Clifford. Also send a file INSTALL.yourname with the pointers to your contribution.

Once it is included you should only send patches.

2 Patches

If you find a bug in a package, scripts or documentation it is usually a good idea to share your findings with others.

Currently most patches are judged and accepted/rejected by Clifford. Run diff against the original and the files you have changed and send it as a file to Clifford.

Contribute patches with (for example):

# diff -ruN old-tree/ new-tree/ > yourname-rock-patch-yyyymmdd

Or:

# ./scripts/Internal diff > yourname-rock-patch-yyyymmdd

which does the same and skips directories like pkg-archive.

Send the patch to Clifford for inclusion.

To apply a patch use the command:

# patch -i patch-filename -p1

If you have a lot of changes try and send in the patches as small hunks in separate E-mails to the Clifford or the appropriate ext package maintainer. Also do not send patches as E-mail attachments, but in the E-mail body prepended by a short note on what the patch does.

This is the same procedure as with patches that get sent to the Linux kernel maintainers.

8 Compiler Optimisations

With earlier versions of ROCK the (root) user could set CFLAGS (and others) in his shell before starting the build, and this resulted into problems.

These variables are cleared now in ./scripts/parse-config before building the packages. You still can define your own optimization using the gcc wrapper (a config file in arch-config/*/*).

Also a package still can set variables like CFLAGS, ASFLAGS or FFLAGS (ROCK does not even clear FFLAGS - so F77 is not effected at all). All it does is "protect" the scripts from variables which come from "outside".

9 Scripts

1 Introduction

The ROCK system can basically be divided into two parts: Download and Build. This section introduces both scripts and should make you comfortable with what happens at that level.

Not all the source code is included in this document. Please refer to your distribution for more information.

2 Download script

@@FIXME

3 Build script

@@FIXME

10 Linux Kernel

1 Introduction

The Linux kernel is the engine of the system. One reason for chosing ROCK Linux is running the latest versions of open source software.

Upgrading the kernel is a common phenomenon - especially for those wanting to run development versions.

2 Getting It

Fetch the latest version (possibly after updating your ROCK image):

# ./scripts/Download -package linux

3 Building

Running Build-Pkg immediately is not a good idea. Firstly because it will overwrite your existing source tree and secondly because you will want to tweak kernel settings.

Essentially the ROCK build scripts live in ./pkg-config/linux. The linux.conf script spells out what happens during the regular build process.

Read the script before continuing.

Verbally what it does is unpack the tar-ball in /usr/src/linux. Before you do that move the symbolic link to your new Linux version $ver. For example:

# /usr/src
# rm -f linux
# ln -s linux-$ver linux
# tar xvIf \$base\pkg-archive/linux-$ver.tar.bz2

Apply the patches that live in $base/misc/linux (make sure the patches are the ones that go with your kernel version - you can test the patch with the -dry-run option):

# cd /usr/src/linux
# ls $base/misc/linux
# patch -p1 -s < file.patch.each

Copy the default configuration and start configuring:

# cp $base/arch-conf/$arch/kernel.conf .config
# make menuconfig

At this point it is useful to compare your config file with the older one in your previous kernel source tree. For example:

# diff /usr/src/linux-old/.config .config|less

Otherwise you have to compare using make menuconfig in two windows.

4 Kernel Configuration

Minimally you need to configure the kernel to include:

If you have SCSI disks make sure to include SCSI in the kernel, including the low level driver (don't compile these as modules).

And add whatever network drivers etc. you have.

5 Compiling

As an example for getting the kernel in place:

make clean 
make dep
make bzImage
cp arch/i386/boot/bzImage /boot/bzImage_new
make modules
make modules_install

Add /boot/bzImage_new to your /etc/lilo.conf file and rerun lilo.

6 Modules

It is beyond the scope of this document to discuss the ins and outs of modules. When switching kernel versions make sure the right modules are loaded. See /etc/modules.conf and the man pages of depmod and modprobe.

At boot time modules can be loaded from /etc/conf/.

7 And ...

For further information on how to compile the Linux kernel see [3].

PART III

11 Building Your Own Target

1 Introduction

Apart from all the benefits you get from ROCK the really cool thing to do is build your own target.

@@FIXME

APPENDICES

A. Which Version of ROCK

1 Introduction

The easiest option is to do a binary install using one of the builds on the Web. But this is not necessarily the best option. You will want a more recent build that is optimised for your architecture.

ROCK Linux is a toolkit for creating distributions. Basically there are two levels of 'up-to-dateness' of ROCK:

  1. ROCK distribution scripts for download/build
  2. ROCK packages

2 Stable versus Development Scripts

ROCK distribution download/build scripts are under continuous development and the version number of the development edition is an odd number (e.g. ROCK 1.7.0-DEV). These scripts usually work well enough to download and build rock, but there is no guarantee that it is not broken.

The stable download/buildscripts are even numbered (e.g. ROCK 1.6.0) and are based on a successful edition of the distribution.

3 Stable versus Development Packages

The packages of the development edition tend to be more up to date than the stable ones (active maintenance of the packages continues as a group effort and the stable packages get maintained as a different effort). Sometimes the development edition will be in research mode building a latest kernel/gcc or glibc, but this is actually a rare occasion.

4 What to choose?

Your mileage may vary. Personally I tend to take a development snapshot and build that fixing problems on the way. It usually works very well. The philosophy of using the latest open source packages leads to a very stable system.

If you are less adventurous it may be a good idea to opt for the stable edition of ROCK. Though you may want to upgrade some packages.

5 ROCK version 1.7

Currently (summer 2002) versions 1.5.x and 1.7.x are worked on. 1.5 should stabilise into 1.6, sometime this year and should deliver a stable edition of ROCK.

This document is mostly about 1.7 since the new developments of ROCK deliver much more in terms of the 'DIY' promise (Do It Yourself). It is pretty much a complete rewrite of the build system. The scripts are coded in a more consitent fashion (clean 'bash' if you believe it), much has been done in rationalising command names and directory structure, there is good support for different 'targets', the package system is better and easier to maintain and much more.

One of the great things about open source software is that it will break compatibility for cleaner design. This caused a break between 1.5 and 1.7 which breaks the package system. The result is that 1.5 and 1.7 packages are not compatible and maintainers have a hard time keeping both going (most do not).

Nevertheless this should not discourage you to use ROCK. Both versions are supported by different groups and each is doing a great job.

B. Bootstrap Installation

1 Introduction

This section discusses several options for installing ROCK Linux on a new machine.

2 CDROM

If you have a CDROM this is by far the easiest option. Burn an ISO image on CD, configure the BIOS to boot from CD and there you go.

3 Network

If you have some version of Linux running on the box, a free partition, and access to the network it is straightforward to download the ROCK Linux install program and the binary tarballs from some source.

Locally (or remotely if you have NFS) run Install.bin (see the section on installing ROCK [*]).

4 Floppy

In case the machine is fresh and there is no CDROM, nor is the network card working, the only way to proceed is by using install floppies. Basically the idea is to get the network to work and copy the files across (see [*]).

There are several possibilities.

1 Standard boot/root floppies

Create a boot and root floppy using the images provided on a ROCK ftp server (see [*]). Boot and cross your fingers and hope the image provides support for your hardware.

2 Create your own boot/root floppies

If you use a non-mainstream network card or SCSI setup you may need to build your own floppies. Scripts are available in the ROCK tree at ./subdists/install-disks. Basically you have to create your own Linux kernel image (see section [*]), supporting your hardware, and burn it onto the boot floppy. This can be handled by mk-bootdisk.sh:




Table : Output of subdists/install-disks/intel/mk-bootdisk.sh (1.6.0pre3):

mkps.sh: line 58: subdists/install-disks/intel/mk-bootdisk.sh: No such file or directory

3 Create a single boot/root floppy

With some hardware (e.g. a USB floppy drive with faulty BIOS) you may have to use a single floppy.

It is possible to create a boot/root floppy with, for example, kermit - which allows transfers over serial cable. See the howto written by Michiel Hobbelman at https://www.rocklinux.org/people/hobbel/.

5 Hard disk

If you don't have a CDROM, network setup or floppy there are not many options left.

The last possibility is to use an IDE hard disk drive and install ROCK on it using another host. Make sure you understand master and slave settings of IDE hard disks before you start off.

C. LILO

1 Introduction

Getting your new system to boot right after installation can be tricky. If you make a mistake you may find you can't boot into the system, or you lose access to your Windows or other Linux partitions.

For a better understanding of LILO please the LDP LILO Howto [4].

2 Clean Install

@@FIXME

3 Installing LILO on a non-devfs Linux system

On a non-devfs system ROCK's lilo won't work. You have to trick the current lilo into booting into your new partition. Edit the current /etc/lilo.conf file, for example:

image = /boot/vmlinuz_rock
  root = /dev/hda7
  label = rock
  append = "root=/dev/ide/host1/bus0/target0/lun0/part7"
  read-only

and create a reference to the vmlinux on your ROCK partition (a symlink should work):

mv /rock/boot/vmlinux /rock/boot/vmlinuz_rock
cd /boot
ln -s /rock/boot/vmlinux_rock

run lilo and if it doesn't complain you may be alright rebooting.

Note: if the setup of sshd etc. did not work because of a missing devfs you can rerun the setup scripts in /etc/setup.d/ to set up the environment once booted into ROCK.

4 I have no root and I want to scream

The root is not properly defined when Linux boots. Edit the 'append' entry in the /script/lilo.conf. If you can't get to your file see [*].

5 Stuck

When you get stuck in the boot process you can give parameters to the lilo prompt. Wait for lilo to show and press TAB or ALT to see the boot options. Add a root definition for example with:

lilo: rock root=/dev/ide/host1/bus0/target0/lun0/part7

point to the partition you installed ROCK on.

As a last resort, if you are really badly off, boot from floppy or CDROM and mount the root file system. Edit the lilo.conf file and run lilo in a chroot environment as described in the install section [*].

D. NFS (Network File System)

1 Introduction

NFS comes in handy when wanting to run a file system of a remote host, for example to have all ROCK tar balls centrally stored, or to save space during the build phase of ROCK (the chroot environment can work from a mounted file system).

This is just a quick HOWTO. For more information see the NFS Howto [5].

2 Mounting a file system

Make sure to have NFS compiled into the kernel (see [*]).

Start up the portmapper and NFS on the server:

/etc/init.d/portmap start
/etc/init.d/nfsd start

Edit /etc/hosts.allow to allow for your client:

portmap: clienthost

Add an NFS export entry to /etc/exports. For example:

/usr/data 192.168.2.4(ro,insecure)
/usr/data clienthost(rw)

Re-export:

exportfs -r

Mount the file system on the client (make sure portmap is running):

mkdir /mnt/remote
mount remotehost:/usr/data /mnt/remote

Check the /var/log/messages file if you don't succeed.

Note: NFS is quite fussy about DNS lookups. It pays to have a solid DNS setup.

E. Deployment Tricks

1 Introduction

Once you have a binary image, or an installed ROCK system, you may want to deploy it across others.

2 Copy hard disks or partitions

Duplicating partitions can be done with dd:

dd if=/dev/discs/disc0/part7 of=/dev/discs/disc0/part5 count=1052226

Mind, this destroys everything on the target (part5) of size 1052226 blocks. Be very thoughtful in what you do here!

3 Using tar

A safer way is by tarring up the file system and untarring into the new one:

echo 'dev' > exclude.txt
echo 'proc' >> exclude.txt
echo 'mnt' >> exclude.txt
tar cvpI --exclude-from=exclude.txt -f tarball.tar.bz2 /

Untar and create the missing directories:

cd target
tar xvpf tarball.tar.bz2
mkdir dev ; mkdir proc ; mkdir mnt

4 Making it bootable

See [*] for getting the system ready for booting the new partition.

F. Environment

1 Introduction

@@FIXME

All scripts get run with certain environment variables set. This appendix lists them with their usage (based on ROCK 1.6.0):

Environment variables
Var Description Usage
$arch Architecture variable. Available architectures are listed as ./archconf/* i386, powerpc, sparc etc.
$arch_machine The system's CPU type  
$archdir Points to the location of the archive  
$base Points to the root location of the ROCK installation  
$confopt Options passed to ./configure by the build script. Standard setting is "-prefix=/opt/$pkg -host=$target"  
$pkg Package name  
$target Target host type  
$ver Package version number (first field)  
$extraver Package version numbers (all fields except for first)  

Build scripts are executed from $base/src.

G. Hacking with bash

1 Introduction

ROCK is written in shell scripts mostly. The reasons are:

This section gives some general information on hacking bash in addition to the man pages.

2 General

Writing shell scripts can be tricky - especially when nesting several layers of pipes. It is a good idea to such a structure one element at a time and printing output.

ROCK's scripts are a great source for ideas! Just cut and paste partial commands into your running shell.

3 Clifford's tips and tricks

1 Introduction

The only real debugging-tool the shell provides is the 'set -x' command. After this command is executed, all further commands will be printed to the terminal before they are executed until a 'set +x' command is found.

Recently a BASH debugger has been developed. This may make life easier for you. Check out https://bashdb.sourceforge.net/.

Everything else in this document is more or less a hack ..

2 How to watch the value of a variable while running a script

The easiest way to do that is to put 'echo $variable' in the script to output the variable or using 'set -x' and grepping for '=' in the debug output.

You also can use 'echo $variable > /tmp/somefile' - so /tmp/somefile contains the current value of the variable.

Simply use the commands 'set' or 'export' in the script to dump all variables or the exported variables of the shell process.

If you know the PID of the running shell script, you can also type "tr '
000' '
n' < /proc/PID/environ" to dump all exported variables of the shell process without modifying the script.

The last method can also be used to 'monitor' one variable. The variable needs to be exported to do that. If we want to watch the exported variable 'dummy' in the shell process with the PID 123:

        while : ; do
                tr '\000' '\n' < /proc/123/environ | grep '^dummy='
                sleep 1
        done

3 How to interrupt scripts based on conditions

if false ; then exit 1 ; fi

or

if false ; then 
  exit 1  
fi

or

false && {                                                              
  echo "Error" ; exit 1                                           
}

If you write everything in one line don't forgett the last semilicon:

                                                                
false && { echo "Error" ; exit 1 ; }

4 Exceptions

Aehhhm ...this is Shell - not C++

But you can use the 'trap' shell-builtin to catch signals (see the bash manpage for details). E.g. if you want to display the value of the variable 'dummy' whenever you send signal SIGUSR1, add this to the top of your script:

trap 'echo $dummy' SIGUSR1

Now start the script and get its PID. Let's say it has PID 123:

kill -SIGUSR1 123

5 How to skip part of a script while testing

The shell has no 'goto' statement. So you need to comment out the part you want to skip or surroundnd it with

if false ; then
  ...
fi

Additionally you can use the 'break' builtin to finish loops earlier than they would normally finish.

6 Convenient variables

$BASH_VERSION .. Set when shell is bash. Contains version number.
$PS4 ........... Prefix for 'set -x' debug output lines.
$SHLVL ......... Shell Level. Incremented by 1 for every new shell.
$- $SHELLOPTS .. Active shell options (also see 'set -o').
$$ ............. PID of the shell process.
$SECONDS ....... Seconds since shell invocation.

H. CFEngine - a configuration engine

1 Introduction

While cfengine has, by itself, little to do with ROCK Linux it is worth paying attention to in a post-installation context.

ROCK users update early and often and therefore find themselves doing repetitious configuration work (system administrators make a full-time job of it). cfengine, created by Mark Burgess, is a medicine against repetition.

You can set your system(s) up in such a way that you install ROCK Linux on a fresh partition, mount the cfengine scripts and reconfigure your machine(s) like before. Without manual intervention. Interesting?

That is especially interesting when you have to administer several machines.

This following section just give a quick overview. For more information read the extensive information that comes with the package (directory /opt/cfengine/share/cfengine/).

cfengine doesn't use if-then-else constructs. Logically functionality is grouped in classes (e.g. lanserver, workstation, laptop).

2 Install

cfengine comes as a ROCK Linux extension package. Download and build it:

./scripts/Download -package cfengine
./scripts/Build-Pkg cfengine

Create a symbolic link:

ln -s /opt/cfengine/sbin/cfengine /usr/local/sbin/cfengine

3 Run

Run cfengine:

cfengine -f \etc\cfengine\cfengine.conf -v -n

The -n option tells cfengine just to test the water. Important in this testing phase!

4 cron

Once you are convinced your cfengine configuration is sane you can run it hourly using cron.

I. Serial Connection

1 Introduction

When you have no keyboard/monitor connection to a box it can be useful to connect a serial cable and talk to the remote machine using minicom or kermit. This short appendix gives information how to connect to serial port 1 (COM1), also known as /dev/tts/0. The settings are 9600 bps, no parity, 8 bits.

ROCK Linux comes with serial support in the kernel.

2 inittab

Add the following line to the remote machine's /etc/inittab file:

S1:12345:respawn:/sbin/agetty -L -i 9600 tts/0 vt100

3 lilo

Add the following line to /etc/lilo.conf and rerun lilo:

serial=0,9600n8

4 Connect

Reboot the remote machine, start minicom or kermit on the local box, set the right speeds and you should see LILO come up.

J. Building ROCK 1.6

1 Introduction

With ROCK 1.7 a completely new build system was developed to support flexible targets. This appendix describes a build using the older versions of ROCKbased on 1.6.0pre3 .

2 Getting ROCK 1.6

Before any other mirrors are available the latest version of the 'STABLE' ROCK build system can be retrieved from ftp://194.47.210.193/unstable/. Other mirrors should become available (check the main website).

3 Download




Table : Output of scripts/Download (1.6.0pre3):

Usage:

 ./scripts/Download [download_options] Filename(s)
 ./scripts/Download [download_options] -pattern Pattern(s)
 ./scripts/Download [download_options] -package Package(s)

 ./scripts/Download [download_options] -all
 ./scripts/Download [download_options] -base
 ./scripts/Download [download_options] -ext

 Where download_options is an alias for:
    [ -nock ] [ -mirror Mirror | -check ]
    [ -passive-ftp ] [ -timeout n ]

 ./scripts/Download -mk-cksum Filename(s)

 ./scripts/Download -list
 ./scripts/Download -list-unknown
 ./scripts/Download -list-missing
 ./scripts/Download -alt-dir Path

Type './scripts/Help Download' for details.

4 Build

1 Building with COPY/LINK

At this point it makes sense to read the 'BUILD' documentation supplied with ROCK (see [7]).

Once you have the build system you can start building. Create a Config file in your ROCK directory by running the command:

# ./scripts/Config menu

or on older ROCK versions:

# ./scripts/Config all

And invoke the Build-All command. The Build-All script has the following options:




Table : Output of scripts/Build-All (1.6.0pre3):

Usage: ./scripts/Build-All NFS-Mount

  or   ./scripts/Build-All COPY

  or   ./scripts/Build-All LINK

Type './scripts/Help Build-All' for details.

# ./scripts/Build-All COPY

Which creates the ./distr/ directory where the entire distribution will be stored. You'll need enough disk space for that (larger than 2.5Gb).

Alternatively you can use the LINK edition of Build-All which creates symbolic links instead of copying the full archives:

# ./scripts/Build-All LINK

If you want to build on a different partition (or machine) you can use the NFS way if building ROCK. In fact it is the common way of building ROCK Linux, because it uses less disk space and it can be run over a network.

2 Building over the Network Filesystem (nfs)

Building over nfs (using loopback) has the advantage of using less disk space. The NFS mount makes it possible to access the ROCK sources from the chroot partition in which ROCK builds.

Building over nfs requires a number of steps. To setup NFS read appendix [*] and the help pages of:

# ./scripts/Help Create-Links
# ./scripts/Help Build-All

One (optional) step is to separate the package archive (which can be a read-only) from the working directory.

Three directories are needed. An nfs exported directory with the original distribution scripts and the downloaded packages. In this example it is named host:/rock-orig. Where host can be localhost or a remote host.

Create the working directory /rock-linux (possibly on a new partition). To run the installation from /rock-linux you can create the necessary symbolic links with:

# cd /rock-orig
# ./scripts/Create-Links /rock-linux
# cd /rock-linux
# ls -l

The package directory has to be reachable through nfs. So for that purpose we create another directory rock-src locally and mount host:/rock-orig on that:

# mount host:/rock-orig /rock-src

Also you need to add

# ---- /etc/exports
/rock-orig localhost(ro)

to the /etc/exports file.

For further information on NFS read appendix [*].

After setting up the directories you need to create the configuration file:

# cd /rock-linux
# ./scripts/Config menu

Select the options for building ROCK Linux. If you are compiling for an architecture other than the one you are compiling on, refer to the file BUILD-CROSS.

You are ready to compile ROCK Linux!

# ./scripts/Build-All localhost:/rock-src

And now sit back and enjoy. This can take days if your hardware is slow enough.

There's one thing I always wanted to do before I quit...retire!

3 Build phase

When the building breaks you can restart it without deleting everything by creating the file _nodel_ (mind you will need a lot of disk space to use this option and normally you won't need it since ROCK does not remove the final build targets when a compilation has succeeded):

# touch _nodel_

During the build phase the compiler output is redirected to files in the ./distr/var/adm/logs directory for each package. This can prove very useful when trouble shooting.

Especially with the development snapshots there may be packages which don't compile properly - or when you haven't downloaded all packages the build may break too. You can instruct ROCK to ignore those by setting 'abortonerror=0' using ./scripts/Config. After finalising the build check the logs directory for failed packages with the .err extension.

Check the following carefully:

# ls dist/var/adm/logs/[1-5]*.err

since these errors refer to packages in the base distribution. If you need to rebuild some packages you may have to delete the 00-dirtree.tar.bz2 file first.

4 Build stages

The ROCK build goes through several stages. The first stage builds the compiler environment for the chroot environment.

Phases 2-5 are built after a chroot.

The ext packages are built in the 'e' phase.

You can build phases separately with the command:

# ./scripts/Build-Stage [1-5]

5 Post building

ROCK creates a directory with the name rock-arch-version which contains the binaries (with a full root path for every file) in the form of tar balls.

The info/logs directory contains the build logs. You can find information on build errors here.

rock-arch-version also contains the CD install bin (Install.bin) and floppy and rescue images (to create the CD image see [*]).

6 Building packages

Packages can be built independently of the ROCK base distribution. After building and installing ROCK Linux you may find you want to add another package, or more, from the ext-archive.

To build any of them simply invoke:

# ./scripts/Build-Pkg package-name

The Build-Pkg script has the following options:




Table : Output of scripts/Build-Pkg (1.6.0pre3):

Usage: ./scripts/Build-Pkg [ -1 -2 -3 -4 -5 -E ] [ -noclearsrc ] [ -maketar ]  \
                           [ -norebuild ] [ -savesrc ] pkg-name(s)

Type './scripts/Help Build-Pkg' for details.

7 Troubleshooting

Check your running kernel configuration (see [*]).

On some non-ROCK build systems you may get an error like 'cannot open linker script file libgcc.map'. You may try and build with 'useflwrapper=0' in your ./Config file.

To build the install disks and rescue system ROCK needs loopback support. Make sure loopback in compiled into your kernel or load the module:

# insmod loop

He may look like an idiot and talk like an idiot but don't let that fool you. He really is an idiot

Also there is a problem with older version of LILO after building the install disks so the image can not be written to floppy on some systems. One trick is to unpack the install floppy disk image in a fresh partition and boot into that directly (after pointing LILO to that partition). The floppy disk images comes with the complete install procedure - it works.

Finally the build may fail because you haven't got bison and/or flex installed on your system. Fix that by downloading and installing bison and flex from one of the GNU mirrors.

5 Create-CD ISO Image

After a build you can create an ISO image which can be burnt on CDROM[*]:

./scripts/Create-CD intel base

drops the base binaries into an ISO image.

./scripts/Create-CD intel ext

creates an image with the ext packages.

An iso CDROM image can be created of either the source packages or the binary packages (with the same name as the image tree with the .iso extension).

You can test the iso image by mounting it on loopback. For example:

# mkdir test
# mount -t iso9660 -o loop rock-i586.iso test

Use a suitable CD burning tool to make the CDROM(s).

Note: The minimum you need to copy to a binary build repository is Install.bin, the packages you need from base-pkgs and the accompanying info directory. That will fit on one CDROM (recent versions of ROCK need two CD's).

K. Running ROCK Linux on an UltraSparc

This section was written by Armijn Hemel.

1 Preparing your machine

A few steps have to be taken before you can start building ROCK on an UltraSparc. In this document, $ROCK refers to the directory that contains the ROCK build system and $ROCKBOOT refers to the partition with the freshly built ROCK system.

1 Upgrading the OpenBoot PROM (optional)

Before you start building ROCK Linux, you might want to upgrade the OpenBoot PROM. Patches are available on the SunSolve website. Check to see if there is a newer version available and upgrade. Be warned though, don't do this if you don't know exactly what you're doing! It might also be necessary to run Solaris to do this.

2 Install a Linux distribution

You will need to install a decently working Linux distribution on your UltraSparc. Good candidates are Splack, Debian 3.0, Aurora and Gentoo. Make sure that you are running a 2.4 kernel, with DevFS and RAM disk enabled. Probably you will have to recompile a kernel for that.

3 Recompile a new kernel suitable for ROCK Linux (optional)

Good chance you will have to recompile your kernel before you can build ROCK Linux. The Linux kernel on UltraSparc is compiled with a special compiler called sparc64-linux-gcc. Depending on your distribution this might either be gcc3 or egcs64, which is a special version of the egcs2.92.11 compiler for compiling Linux UltraSparc kernels. Right now egcs64 is still the preferred kernel compiler and you might have to install it prior to compiling the kernel.

Install it in a place other than your normal gcc, because it will overwrite it. See $ROCK/base-config/egcs64/ for the right build options and patches. Make sure this version is in your path before another version of sparc64-linux-gcc (if any).

After building a new kernel, change the old /dev entries to DevFS style entries in /etc/fstab and /etc/inittab. Add the following rule to /etc/devfsd.conf:

REGISTER    .*     MKOLDCOMPAT

Add an entry for your new kernel in /etc/silo.conf (use the new DevFS style here as well) and run silo. Reboot and see if it works. If your distribution does not start devfsd (the daemon) automatically, you will need to start devfsd in a startup script (distribution specific) or start it manually. The reason for this is that SILO does not yet support DevFS (booting is no problem, but when you run the silo program it needs the old style /dev entries).

4 Download ROCK sources

Download all the ROCK sources and packages as described earlier in this document.

5 Configuring and building ROCK

Choose during configuration ultrasparc as your platform and sparcv9 for the optimization. At the moment, just the base packages are guaranteed to work. Work is underway to get the optional and extension packages working as well.

Make sure that if you have two versions of sparc64-linux-gcc that the directory for the one you want to use is searched first! By default, ROCK 1.5.* first searches /bin, then /usr/bin, then /usr/local/bin and completely ignores $PATH. You might want to make a symlink called sparc64-linux-gcc in either /bin or /usr/bin to your preferred version.

Next, start the build as described earlier in the document and wait until everything is built, which might take quite long.

6 Booting ROCK

After building, make sure that your freshly built ROCK system (everything that ends up in $ROCK/dist) is on a seperate partition ($ROCKBOOT). Copy over the necessary files from /etc, such as passwd, shadow, silo.conf and fstab to $ROCKBOOT/etc.

Change $ROCKBOOT/etc/fstab in such a way that $ROCKBOOT is mounted on / (with all the right options of course, to prevent filesystem corruption). Change /etc/silo.conf to boot with your new partition as root partition and reboot. If everything boots fine you have ROCK running on your UltraSparc.

No References!

Bibliography

1
Cfengine,
Mark Burgess, https://www.gnu.org/software/cfengine/cfengine.html

2
Linux Bootdisk-Howto,
Tom Fawcett, https://www.google.com/search?q=linux+bootdisk+howto

3
Linux Kernel-Howto,
Brian Ward, https://www.google.com/search?q=linux+kernel-howto

4
Lilo mini-Howto,
Cameron Spitzer and Alessandro Rubini, https://www.google.com/search?q=linux+lilo+howto

5
NFS Howto,
https://www.google.com/search?q=linux+nfs+howto or
https://www.linuxdoc.org/HOWTO/NFS-HOWTO.html

6
Linux BootPrompt-HowTo,
Paul Gortmaker, https://www.google.com/search?q=linux+bootprompt+howto

7
ROCK Linux Distribution,
Clifford Wolf et al., https://www.rocklinux.org/

8
ROCK Linux, Linux Journal, October 2000, pp 12,
SSC, October 2000

9
ROCK Linux FAQ,
Clifford Wolf, Dag Bakke et al., https://www.rocklinux.org/

10
ROCK Linux: Not for woozies!,
Jos Visser, E-zine https://e-zine.nluug.nl/hold.html?cid=59, March 2000

11
Rock Linux Philosophy,
Clifford Wolf, E-zine https://e-zine.nluug.nl/hold.html?cid=1, November 1999

12
Using Rock Linux on a Sony ultra portable laptop,
Pjotr Prins, E-zine https://e-zine.nluug.nl/hold.html?cid=75, March 2000

About this document ...

ROCK Linux Guide (2nd edition)

This document was generated using the LaTeX2HTML translator Version 2002-2 (1.70)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -no_images -scalable_fonts -local_icons -no_navigation -split 0 -show_section_numbers -dir /home/wrk/cvs/fs2/texoutput/html main.tex

The translation was initiated by on 2003-01-20


Footnotes

...ROCK!)[*]
Currently only part one is more or less complete. Part two and three should become available later this year (see [*])
... are[*]
Run ./scripts/Download without options to get a list (versions before ROCK 1.7.0-DEV see [*])
... target[*]
If Config hangs remove the config directory and its contents
... CDROM[*]
You don't need an ISO image to install ROCK Linux!


2003-01-20