Configuring the Boot Process

This page describes the boot process and how to configure your GoboLinux system by editing the configuration files used for startup.

General architecture

The BootDriver script (/Programs/BootScript/<version>/bin/BootDriver) manages boot-related tasks. The init program (from the Sysvinit package) running as PID 1 calls BootDriver as specified in /System/Settings/inittab.

BootDriver first loads the boot theme file specified in /System/Settings/BootOptions. Then BootDriver runs the appropriate boot script for the task at hand (startup, shutdown, etc.)

Boot Scripts

GoboLinux boot scripts initialize and configure the system, manage daemons, and perform shutdown. They are located at /System/Settings/BootScripts.

• BootUp, the primary startup script, is invoked when you turn on the power and the system boots. It contains generic initializations common to most Linux systems. Additional scripts are provided to support particular boot scenarios.
  • Console runs BootUp and performs initializations required for a console session.
  • Graphic runs BootUp and starts X to provide a login window.
• Shutdown is the primary shutdown script, analogous to BootUp. It is used by the following termination scripts:
  • Reboot runs Shutdown to terminate system services then reboots the machine.
  • Halt runs Shutdown and turns off the power, if possible. Otherwise it halts the processor.

Each of these scripts contains lines of the form:

Exec "Message..." SomeCommand [ parameters ]

For example, to adjust the keyboard delay and repeat rate in the console, you can add this line to /System/Settings/BootScripts/Console:

Exec "Making keyboard speedy..." kbdrate -r 30 -d 250

GoboLinux also provides “boot tasks” as a more sophisticated way of managing services.

Configuration options

When GoboLinux boots, the boot scripts launch programs to configure the keyboard, set the system clock, initialize the network, etc.

The parameters for calling these programs are placed in /System/Settings/BootOptions and /System/Settings/NetworkOptions. Both files contain entries of the form:

Option=value

Note that no space is allowed before or after the = character. This is shell syntax, allowing the options to be imported into the boot scripts using the source command.

The following sections document options available in /System/Settings/BootOptions and /System/Settings/NetworkOptions.

Clock mode

GoboLinux needs to know if your hardware clock is set to GMT or local time. Specify this by editing the ClockMode option. Set ClockMode=GMT if your hardware clock is set to GMT. Set ClockMode=LocalTime if your hardware clock is set to local time.

For obtaining time zone information, Linux applications rely on information provided by Glibc, the C library. Glibc, on its turn, uses the localtime symlink in its Settings directory (/Programs/Glibc/Settings/localtime) to indicate the active time zone. This symlink is created by the installer according to the time zone you selected. You can set this setting manually, by pointing the localtime symlink to a different file under /Programs/Glibc/Current/Shared/zoneinfo.

The ClockMode information is used for the hwclock utility, which is launched at boot time through the SetClock task.

Console setup

Fonts

Fonts in GoboLinux are stored under /System/Index/share/consolefonts and /System/Index/share/fonts. They provide character typefaces for the Linux console, the X Window System, and ghostscript, the Linux postscript interpreter.

Font path configuration for X can be found in /System/Settings/X11/xorg.conf and /System/Settings/fonts/fonts.conf.

To change the default console font used by GoboLinux, use the ConsoleFont option in /System/Settings/BootOptions.

You can also change the console font using the setfont utility. See man setfont for details.

Remember that this setting changes only the console font. On X, applications have their own font settings.

Keymap

Use the KeymapLayout option in /System/Settings/BootOptions to select an appropriate console keyboard layout.

The available keymaps are in the KBD package; they are the .map files. You can set the console keyboard layout at any time by running loadkeys. For example, to set the Dvorak keymap, just type in:

loadkeys dvorak.map

Mouse

The MouseType and MouseDevice options in /System/Settings/BootScripts/BootUp configure mouse support on the console. They are disabled by default.

Graphical display setup (X server)

Keymap

The keyboard layout for programs running under the window manager is mapped according the InputDevice section in /System/Settings/xorg.conf when the graphic display (X server) starts. With the window manager running, you can change keyboard mappings and display settings using setxkbmap, xmodmap, and xset tools. To select a Dvorak keyboard layout, type setxkbmap dvorak in a terminal. These commands can also be placed in $HOME/.xinitrc.

Some desktop environments also offer graphical tools for setting the keyboard layout. For example, in KDE you can configure this at the KDE Control Center.

Mouse

The mouse pointer for the graphical display is defined in an InputDevice section in /System/Settings/xorg.conf. The Installer should correctly detect your hardware and set suitable defaults for your system. If not, you can always try a failsafe setup such as:

Section "InputDevice"
Identifier  "Mouse0"
Driver      "mouse"
Option      "Protocol" "auto"
Option      "Device" "/dev/input/mice"
Option      "ZAxisMapping" "4 5"
EndSection

There is nothing GoboLinux-specific about mouse setup on X. You can find HOWTOs and tutorials around the net that can give you more detailed instructions about this. (But feel free to drop by at the mailing list if you’re still stuck!)

Kernel modules

Through the use of Udev, GoboLinux is capable of loading kernel modules (e.g. device drivers) automatically at boot. In cases Udev doesn’t load some wanted drivers, the user can explicitly request them.

One way is to edit /System/Settings/modprobe.conf (similar to other Linux distributions), however a simpler way in GoboLinux is to list desired modules in /System/Settings/BootOptions. This is how to load the i810_audio audio driver and sk98lin ethernet driver:

UserDefinedModules=(
    "i810_audio"
    "sk98lin"
)

The startup scripts read this array and run modprobe each line. The entries may include additional parameters.

Network configuration

Wi-Fi

If you are using Wi-Fi, just select your network using the GoboNet widget in the AwesomeWM system tray:

Wired network

If you have a wired network, initialize it on boot using standard Linux commands in your bootscripts sequence.

First, check which are your network interfaces typing

ifconfig

You should have a network interface named something like eth0 or enp0s3.

Edit the /System/Settings/BootScripts/BootUp script. If you are using DHCP, just add this:

dhcpcd eth0 &

If you have a static network configuration, place commands similar to the following in BootUp.

ifconfig eth0 192.168.1.5 netmask 255.255.255.0
route add default gateway 192.168.1.1 metric 1 dev eth0

The nameserver can be specified in /etc/resolv.conf (/System/Settings/resolv.conf). To use Google’s nameservers, you can edit resolv.conf to:

nameserver 8.8.8.8
nameserver 8.8.4.4

Automated login

If you wish to use an automated login, there are several ways to achieve this goal.

For KDE (or KDM, it also has a configuration which allows you to tweak it a lot) you can use this:

1. Open Control Center in administrative mode.
2. Select Login Manager.
3. Under the Convenience tab check “Enable auto-login” and select which user you should log in as.
4. Click “Apply”.

If you do not use KDE or want a non-GUI based solution, one way is to use rungetty.

1. In your inittab file (for example, nano /etc/inittab) find the line which includes tty1 (it’s your first terminal, the default showing up on login).
2. Now, you will see agetty in there - change this agetty line to rungetty tty1 --autologin your_username.

Of course, replace your_username with the user you want to login as.

Using another tty than 1 may be useful too.

Printers

GoboLinux comes with CUPS installed by default.

Audio

Note that ALSA is muted by default, to automatically save and restore changes done in e.g. alsamixer, add these lines to your boot scripts.

Done: Exec "Storing ALSA settings..."
alsactl store

Boot Script Tasks

Your boot scripts can make use of “boot tasks”, which are little service scripts that can be shipped by programs. A program includes its tasks under Resources/Tasks, and they’re linked in /System/Tasks. This is roughly equivalent to the /etc/init.d scripts found in many distributions.

You can launch or stop tasks from the command line, using StartTask and StopTask. For example, the following command will load the SSH daemon:

StartTask OpenSSH

Within boot scripts, you don’t need to use these launchers, but you have to add a parameter indicating whether the task is being started or stopped:

Exec "Initializing OpenSSH server..." OpenSSH Start

Creating tasks

Strictly speaking, a task is simply a shell script put in the appropriate directory, which accepts start and stop parameters. In this imaginary example, one could have a file /Programs/Foo/1.0/Resources/Tasks/Foo with these contents:

#!/bin/sh

case "$1" in
[Ss]tart)
    # actions to start foo go here
    foo --silly-walk
    ;;
[Ss]top)
    # actions to stop foo go here
    killall foo
    ;;
esac

It’s a good idea to use the above example as a template for tasks you create. The [Ss] syntax ensures that both start and Start are recognized, which is nice to avoid typos.

Boot Themes

GoboLinux is flexible enough to offer you a choice of themes to control how your GoboLinux looks when starting up.

You can select a theme by setting BootTheme=<ThemeName> in /System/Settings/BootOptions. Available themes include:

• CheckList - Shows tasks and others that depend on them, then checks them off.
• Hat - A Red-Hat look-alike: lots of colored [ OK ]s and [FAILED]s are echoed as things are initialized.
• Progress, Progress-II, or Progress-III - Fancy themes that stress your terminal with tons of escape codes.
• Quotes - Prints short random quotes to indicate success or failure of every initialized item.
• Slack - This theme is inspired by the feel of old-school Slackware boots: no distracting messages, no colors, no special effects.

Check /Programs/BootScripts/Current/Themes/ to see all the available themes.

You can use the TestBootTheme script to see how a boot theme looks like without actually rebooting your computer. TestBootTheme is described on section Testing a boot theme.

You can also set the boot theme from GRUB by adding BootTheme=<ThemeName> to the boot line. This can be handy if BootOptions file specifies a broken or nonexistent theme, because GoboLinux will not boot without a valid one.

Physically, a GoboLinux boot theme is a single script file located in /Programs/BootScripts/*<version>*/Themes.

The theme file is loaded by the boot scripts core, and is called once for every runlevel change. Although interesting stuff can be done in the script body, a compliant boot script has only to implement the following functions:

• ThemeInit
• ThemeFile
• ThemeBefore
• ThemeAfter
• ThemeFinish

These functions are the hotspots that glue the theme and the boot scripts core together.

• Creating a boot theme
• Implementing a boot theme
• Testing a boot theme

Notes on Command-Line switches

Many scripts accept command-line options. All options feature a short, one-letter form, and a long form. Following the GNU conventions, short form options are preceded by a single hyphen (as in -a, -b) and long form options are preceded by two hyphens (as in --foo, --bar).

Order of Command-Line Arguments

All command-line options have to be passed first, before other types of arguments (file names, package names, etc). In other words,

FooScript -m Foo

works, but

FooScript Foo -m      # WRONG! Switches must come first.

does not.

Switches taking arguments

Some command-line options accept arguments. These arguments must be passed as the word following the argument, both in short and long forms. For example, say that -s and --long are options that take a parameter. This is the correct way to use them:

FooScript -s value --long another

These are not recognized:

FooScript -s=value --long another      # WRONG! Use distinct tokens.

Do not conglomerate

Each option should be passed in a separate token, even when in short mode. If -a, -b and -c are options for an imaginary FooScript, then

FooScript -a -b -c blah.txt

is correct, but

FooScript -abc blah.txt      # WRONG! Options must be separated.

is not.

Help

All scripts have a --help option (or, in short form, -h). When a program that needs arguments is run without arguments, the help text will be displayed. (Note: Actually, not all scripts conform to this yet, but this is being worked on).

GoboPath

This script is used everywhere inside many scripts. It exports shell variables such as $goboExecutables, $goboUsers, $goboKernel, and so on, which contains a string specifying where in the file system these entries are (/System/Index/bin, /Users, /System/Kernel, and so on).

For example, in the Scripts package, within the bin/ subdirectory are files such as ScriptFunctions or SuggestUpdates, among others. These source GoboPath via:

. GoboPath

This is normally within the Scripts package, at bin/GoboPath. The whole GoboLinux hierarchy is kept as referential prefix in that file. The variable $goboPrefix keeps track as to where GoboLinux is mounted at.

Let’s avoid hardcoding things, sourcing this file and using these variables makes the world a better place :-)

Guidlines for script authors

This section documents the coding style used in GoboLinux shell scripts.

It’s important to note that not all scripts follow these guidelines, because of historical baggage (some of the scripts are older than GoboLinux itself). Patches to correct the non-conformities are welcome.

Indentation and block organization

A few rules of thumb:

• Three spaces for indentation. Avoid joining do and then in the same line with ;, instead put it on a line by itself, aligned with for, while or if.
• Prefer using if rather than idioms like && { }, but apply your common sense.
• Be generous in you use of quotes whenever referring or defining variables, and the ${x} syntax when merging variables inside strings.
• Bear in mind that esac is ridiculous.
• When doing weird stuff such as functional-like programming with eval, hide it in a pretty function to pretend it is a bit more readable. Eventually we might make a Functional module. By now, Map() is defined in the Array module.

It’s hard to believe, but the only shell module containing GoboLinux-specific stuff is the one aptly called GoboLinux. Keep that in mind when submitting functions for inclusion in one of the modules.

Names

The idea in the naming convention is to orthogonally describe scope and purpose of each name. We define “local scope” as names that are specific to a given script, and “library scope” as names defined in Scripts modules such as GoboPath, ScriptFunctions or one of the imported function modules.

These are the guidelines:

• Function names have underscores between words

Example: local_function, Library_Function

• Variable names do not, they’re just connected

Example: localvariable, LibraryVariable

• Library names (for functions and variables) have capital letters

Example: Library_Function, LibraryVariable

• Local names (for functions and variables) are in all-lowercase

Example: local_function, localvariable

• All-uppercase variables are reserved for standard Unix usage

Example: PATH, LD_LIBRARY_PATH

• Configuration variables used in .conf files start with the script name in lowercase, resulting in a case style similar to that used in Java variables

Example: compileRecipeDirs, editKeymapLayout

Files that cannot be symlinks

Symbolic links play a major role in a GoboLinux system, but some programs don’t behave as expected when they are used. This section lists the files that cannot be symlinks.

“That is the reason why /System/Settings is not /System/Index/Settings: it does not only contain links, by definition (or, better put, by necessity)” – Hisham Muhammad

• /System/Settings/sudoers

The configuration file for sudo must be a regular file. If it is not, sudo will complain and do nothing.

• /System/Settings/passwd and friends

The settings files used by the Shadow package are quite interesting. Theoretically, they can be symlinks, but there is a caveat: utilities like useradd don’t just modify these files; they remove and recreate them as regular files. Hence, in practice, they cannot be symbolic links.

Sandboxing under GoboLinux

The build system in GoboLinux uses sandboxing to ensure that all the filesystem writes during the software install phase are limited to an appropriate part of the filesystem. GoboLinux 016 ships with two different sandbox implementations.

UnionSandbox is a modern implementation which uses file system unions to achieve isolation. It is the default sandbox installer.

FiboSandbox is a fallback method used when a union-filesystem implementation is not available in the running kernel. It sets up an isolated environment and commands are run by a special user (named fibo) without root privileges.

During the installation phase of the software build process, most build systems call the install program to copy files to their destination directories with the proper ownership and attributes. install belongs to the CoreUtils package.

Since user fibo lacks authority to change file ownership, the link at /System/Index/bin/install points to a wrapper script in the Scripts package.

Under UnionSandbox, this wrapper script translates the superuser name if necessary and calls real_install, a symlink to the CoreUtils install utility, passing along the modified arguments.

Under FiboSandbox, the wrapper discards change-of-owner directives before calling real_install.

Replacements for standard commands

GoboLinux has its own replacements for a few standard commands like su and make. The reasons for making a replacement ranges from adding necessary functionality (su) to making prettier output (make).

While having these “replaced programs” is not a problem in itself (in fact, most provide enhanced functionality which adds to the GoboLinux experience), it’s important to point out these differences here so that you can know what’s going on with these perhaps unexpected behaviors.

The replacements are provided by several different packages. All except install are handled by making an alias in the shell initialization scripts. This way, you can easily disable the alias and restore the original version of a program, if you so wish. They can be often found in their own subdirectory Resources/Wrappers inside the program directory.

• su - aliased to Su in the Shadow package to handle names other than root as super user
• sudo - aliased to Sudo in the Sudo package to handle names other than root as super user
• top - aliased to htop in the Htop package
• make - aliased to ColorMake in the Scripts package to produce colorful output
• info - aliased to Info in the Pinfo package
• man - aliased to Man in the Pinfo package
• install - install in CoreUtils has been renamed to real_install with install in the Scripts package as a wrapper (see section Sandboxing under GoboLinux for a detailed explanation)
• which - the Scripts package provides a “which” script which resolves symlinks in the path of the returned program, so that it indicates the /Programs path the binary refers to.

Aliases enabling “enhanced replacements” such as Htop and Pinfo are set in the Environment section of these packages. This way, if you want to stick to plain top and/or info, all you need to do is to remove (or just not install) these replacements.