COOKBOOK

= The Saboteur's Cookbook

a guide to running Sabotage for the experienced user.


== Installing the system

There are various ways you can install a sabotage system:
- by bootstrapping
- from a USB stick
- from the network

The bootstrapping approach is explained in the chapter "Bootstrapping
the system".

To install from a USB stick, get sabotage-full* or
sabotage-netinstall* from a mirror, gunzip and dd it onto a stick.

To install from network, setup a TFTP server, grab pxelinux.0 and boot
the kernel sabotage-install-YYYY-MM-DD.rd.

After booting, you will need to partition your harddisk with fdisk
(don't forget to make the root partition bootable) and format the root
partition with mkfs.ext4.  If you want to netinstall, now setup your
network connection using ifconfig.  Don't forget to set a nameserver
in /etc/resolv.conf.  Then mount the root file system at /mnt.

Run "sabotage-install".  Enter /installed if you want to install from
the sabotage-full* disk, or enter the prefix of a mirror.  Pressing
return will accept the default value, shown in [braces].
Usually, you then want to choose the latest release.
Next, you will need to select sets:

  base   - base system, REQUIRED
  comp   - compilers
  doc    - documentation
  etc    - configuration files, REQUIRED
  kernel - kernel and modules, REQUIRED
  xorg   - partial X.org distribution

Accept installing extlinux unless you already have a bootloader.
If you install on a fresh partition, you'll also need to install a MBR
like this:

  dd if=/usr/lib/syslinux/mbr.bin of=/dev/DISK conv=notrunc

Now reboot into your freshly installed Sabotage system!


== Bootstrapping the system

Git clone the sabotage repository.  Copy "KEEP/config.stage" to "config"
and adjust the variables:

  $K  directory with patches
  $S  where sources are compiled (stage0: ~700MB, stage1: ~2.1GB)
  $R  root file system, potentially loopback-mounted or on a real partition

Next steps:

  % . ./config       # required!

  % ./build-stage0   # build toolchain (~15min on a modern machine)
  % ./enter-chroot   # enter $R chrooted, needs root password

Inside the chroot, you need to build stage1:

  # cd /tmp/src/sabotage   # absolute path required!
  # mk stage1        # rebuild stuff, build kernel (~1h)

You can now really boot the system (potentially install extlinux), or
continue in the chroot:

  # mk pkg           # additional stuff
  # mk xorg          # build X.org


== Making a release

Build everything (mk world is a shortcut).  Check that all files are there:

  # mk check-sets

Especially check that there are no files that belong to the distribution
in the list of "superfluous" files (/tmp/cs-superfluous).  Else, edit
the set files in sets/*.

Rules:

xorg   contains everything related to X.org, including libs and manpages.
doc    contains all documentation: manpages, Info and HTML.
comp   contains everything related to compiling, and static libraries.
etc    contains configuration files that should not be overwritten by an upgrade.
kernel contains the kernel and modules.
base   contains the rest.

The built sets reside in dist/sabotage-YYYY-MM-DD.


== Making the installer

  # mk installer

... wait ... look into /tmp/src/installer ... copy stuff around.


== Adding a package

Decide where to place the package:

  stage1 - things elementary to build Sabotage in the chroot/before first boot
  pkg    - usual packages
  xorg   - things related to X.org, things which need a GUI
  extra  - stuff not packaged, for users to build themselves

Update "deps" to depend on *build dependencies* *inside the set*.
pkg can depend that stage1 is built, xorg can depend that pkg is built.

In $dir/$name, you should make use of the "tarxf" function to retrieve sources:

  tarxf $REMOTEDIR $PKGNAME $SUFFIX [$DIRNAME]

Configure stuff with --prefix=/ and don't forget to set the DESTDIR to $R
to allow seperate release building in later versions, e.g.:

  tarxf http://www.greenwoodsoftware.com/less/ less-436 .tar.gz
  ./configure --prefix=/
  make
  make DESTDIR=$R install

You can test your build with "mk rebuild-$pkg" which will not rebuild
build dependencies.


== System administration

Sabotage does things a bit differently than your usual Linux
distribution!

=== The file system

Sabotage does not follow FHS.  /usr is a legacy symlink to /, /sbin is
a legacy symlink to /bin.  Software should be installed with
--prefix=/.  The times of a seperate root partition are long over.

Everything below /local is yours, use it wisely.  Software not
packaged by Sabotage should not touch stuff outside, it could possibly
break on updates.

Use /srv/$SERVICE/$VHOST for all server data.

=== The init system

Sabotage uses runit as init system (not entirely, so far we use
Busybox init to start runsvdir).  This is cool, see
http://busybox.net/~vda/init_vs_runsv.html.

The base system has a few services, which you find in /var/service
(note that these are symlinks to /etc/service):
  
  dmesg - logs kernel messages
  sshd  - opensshd, down by default
  tty2, tty3, tty4 - three gettys
  crond - cron daemon

You can start services with "sv u $SERVICE" or take them down with "sv
d $SERVICE".  By default, all services in /var/service start at boot
time, unless they have a "down" file in their directory---then you'll
have to start them manually.  If you don't want to use a service at all,
best remove the symlink to /etc/service.

You can find out whats running and what is not with

  # sv s /var/service/*

Look into the service directories to find out how to add your own
services---note that you must tell them not to daemonize!

For the rest of runit, I'll refer you to the documentation at
http://smarden.org/runit/index.html

=== Logging

There is no syslog support so far, services should use "svlogd" (see
runit docs) to log into directories below /var/log.
You can inspect the logs by looking at /var/log/$SERVICE/current,
Kernel messages are found in /var/log/dmesg/current.

You can quickly look at all logs with

  # sort /var/log/*/current  |less