RUNTIME.md

GNU OS Cross-Compiler - Using the GNU System

The purpose of this document is to briefly explain some basic usage information and unique features of the GNU operating system created by the gnuxc build system project.

For documentation on the build procedure, see the BUILD.md file.

The Bootloader - GNU GRUB

When booting the disk on a standard PC BIOS system, a graphical GRUB menu will be displayed with a few boot options. A GRUB command line environment can be activated by pressing c, and menu entries can be inspected or customized by highlighting one and pressing e.

Boot Options

The first menu item initializes Hurd in a standard fashion. It uses GNU Shepherd to start system services, including the login prompts. To boot to a non-default login environment, press e to edit this menu entry and append one of the following numbers to the multiboot line.

• 1 will only start the runttys service. This results in a single login prompt being available on the GNU Mach console.

• 3 will start the console service, which also starts runttys as a dependency. This provides multiple virtual consoles using the Hurd console client with login prompts on each of them. This is the default.

• 5 will start the xdm service, which also starts console as a dependency. This is the full graphical desktop login interface.

There are two more options that can change the init system behavior.

• -f will skip the file system checks. Currently, fsck is what changes the root file system to writable, so this option will run the OS with a read-only root file system.

• -s will change to a root shell instead of starting system services. (The following two menu items use this option.)

The second menu item boots directly to a root shell; i.e. PID 1 is bash. No services are started by Shepherd. This is useful for rescuing a system that is misconfigured, or when a password reset is needed.

The third menu item boots to a root shell as well, but the root file system is mounted read-only. This is useful for running fsck on a potentially damaged root file system.

The last menu item offers to boot a virtual machine. It is intended to be used to run the OS on physical hardware that is unsupported by Mach and Hurd. It boots a GNU Linux-libre kernel, which then runs the Hurd-based OS in QEMU for compatibility. Currently, the Linux-libre kernel is configured as the EFI bootloader, so this option is effectively used automatically when EFI-booting the disk. See The HAL section for more information on this environment.

Configuration Files

The main GRUB configuration file is /boot/grub/grub.cfg, but this file should not be updated directly. It is generated by the regular upstream tools, namely by running the following command.

sudo grub-mkconfig -o /boot/grub/grub.cfg

Settings for the configuration file (such as timeout length or the theme used) are read from /etc/default/grub. The grub-mkconfig command will need to be run again after changing the settings to take effect.

The boot menu options are generated by executing the files in /etc/grub.d in order. They try to detect all installed operating systems to add boot entries for each usable OS. In this case, the files 10_hurd and 39_hal provide all of the default menu items for this disk.

The HAL - GNU Linux-libre

Due to Hurd's extremely limited hardware support, a special boot option is provided that can have the disk boot itself virtually with emulated hardware known to work with Hurd. For example, a USB wireless interface is presented as a regular Ethernet device, and a touchscreen display is presented as a PS/2 mouse. This allows the OS to be fairly portable without requiring any modern hardware drivers for Hurd.

The virtual host operating system is GNU Linux-libre using QEMU with KVM (if possible). The Linux-libre kernel is responsible for driving the system's physical hardware, and QEMU is responsible for running Hurd on simple emulated devices. Together, they form the world's most inefficient hardware abstraction layer. (For originality points, the HAL project's name stands for Hurd Atop Linux-libre.)

Aside from a few additional configuration and debugging features, the Linux-libre host OS should be transparent, allowing regular usage of the Hurd guest OS as if it was booted natively.

Consoles

The Linux-libre environment provides four virtual consoles.

1. tty1 is the guest VM's display. On hardware with framebuffer support, the guest's VGA screen is fully drawn at its native resolution. Press Ctrl+Alt+S to scale it to fit the physical display's resolution. On hardware without framebuffer support, a curses-based text interface renders the guest's screen while it is in VGA text-mode. This is the default console; press Ctrl+Alt+F1 to return to it.

2. tty2 is the QEMU monitor console. It is used for diagnostics and control of the VM. See its help command for details. Press Ctrl+Alt+F2 to switch to this console.

3. tty3 is a serial device connected to the guest VM. For example, Hurd has read/write access to it through /dev/com0. Press Ctrl+Alt+F3 to switch to this console.

4. tty4 is a (very) limited shell on the Linux-libre host. It can be used for debugging or various administrative tasks, such as reconfiguring the host's network connection while the guest is running. Press Ctrl+Alt+F4 to switch to this console.

Pressing Ctrl+Alt+Esc while on tty1 will immediately terminate the VM and drop to a host system shell. After any debugging, running either poweroff or reboot is probably what you will want to do in this situation.

Runtime Configuration

The HAL's init program supports two methods of customizing host and guest settings from their defaults or automatically detected values. The kernel command-line passed from the bootloader is checked for variables specifying new settings, and a series of prompts can be triggered before the VM starts.

Command-line Variables

Settings can be specified as arguments on the Linux-libre command-line of a GRUB prompt or an EFI shell to use them for a single boot, or they can be made persistent by editing /etc/grub.d/39_hal before regenerating the GRUB configuration. These arguments will have the form of e.g. gnuxc.memory=3072.

The following variables modify the virtual machine settings.

• gnuxc.boot takes the path of the host disk device to boot as the virtual guest. It will attempt to find the correct disk based on file system labels by default, or it will fall back to /dev/sda if unsuccessful.

• gnuxc.cores takes a positive integer specifying how many CPU cores the virtual machine will use. It will use a single core by default.

• gnuxc.memory takes a positive integer specifying how many MiB of RAM the virtual machine will use. It will use approximately 75% of the host's available RAM by default.

• gnuxc.fbdev takes either 1 or 0 to enable or disable the framebuffer display. When this is disabled, the guest's screen is presented in a text interface when it is in VGA text-mode. It is enabled by default only when the hardware supports a framebuffer device.

• gnuxc.kvm takes either 1 or 0 to enable or disable KVM acceleration for the virtual machine. It is enabled by default only when the hardware supports KVM.

The following variables modify the network configuration of the host system. Currently, the host address configuration will always use DHCP.

• gnuxc.iface takes the name of the network interface on the host system that should carry the guest's traffic. If this is empty, it will try to automatically detect a usable network interface, which is the default. To disable networking at the host level, set this variable to lo.

• gnuxc.ssid takes the SSID to use when the network interface is a wireless device. If this is empty, the network interface is assumed to be Ethernet, which is the default.

• gnuxc.pass optionally takes the WPA-PSK password for connecting via WPA2.

Prompts

A sequence of prompts for the above settings can be triggered by holding Ctrl while the HAL is initializing. The default value used by each prompt is inherited from the command-line variables, or their defaults when unspecified. Pressing Enter at a prompt with an empty value will keep the default. (Note that tty4 has a shell to inspect detected hardware for these prompts.)

When all of the prompts have been answered, a summary of the settings will be printed along with a confirmation prompt. If any of the values are incorrect, specifying no at the confirmation prompt will restart the sequence.

If the kernel command-line contains the argument gnuxc.ask, the prompts will also be triggered regardless of the Ctrl key. Writing this to the bootloader configuration is a way to prompt for VM settings on every boot.

The Init System - GNU Shepherd

The standard init program at /sbin/init is a symlink pointing to the GNU Shepherd executable. This is the program that gets called as the Hurd servers are finishing their bootstrap process, and it is responsible for starting the system's user space services.

Service Management

The herd command is used for interacting with Shepherd's defined services at runtime. Note that it will attempt to communicate with user-specific Shepherd instances, so it should always be run as sudo herd to work with the system services. Output from Shepherd and herd is logged to /var/log/shepherd.log with time stamps.

The command is normally run as sudo herd $action $service, where $service is the name of any defined service, and $action is usually one of the following words.

• start will launch the named service in the background.

• stop will kill the named service that is already running.

• restart is effectively a shortcut for stop and then start as above.

• status displays some current attributes of the service, such as its PID (if it's running), its alternate names, any service dependencies, etc.

• doc shows a brief summary statement of what the service does.

The special service names shepherd or root allow interacting with Shepherd itself. (The two names are equivalent.) To get a list of all currently known services, run sudo herd status shepherd or just sudo herd status.

New service definitions can be loaded at runtime with the shepherd service's eval action, which runs strings of Guile code. For example, if you have a service definition file at /tmp/example.scm, run the following command to register its service.

sudo herd eval shepherd '(register-services (load "/tmp/example.scm"))'

The new service should be available and listed by sudo herd status immediately. If you want to remove a service at runtime, use unload.

sudo herd unload shepherd example

The service named example will be stopped and undefined immediately.

Configuration Files

Shepherd is written in Guile, and all of its configuration files are executed as Guile scripts.

System Initialization

Shepherd's main configuration file is /etc/shepherd.scm, which is executed when the system boots. It is basically a Guile reimplementation of Hurd's initialization shell scripts with some additions for service loading. Aside from the services, its main functions are to check file systems on boot and create any temporary file system structures needed by installed packages.

Note that the default GRUB menu item has --readonly on the root file system program. This is for /etc/shepherd.scm to be able to call fsck on it without the file system being modified in the process. Once fsck finishes its validation, it remounts the file system as writable for regular usage.

At the beginning of /etc/shepherd.scm, the variable default-runlevel is defined. This can be changed to 1, 3, or 5 to choose a preferred set of services to start automatically on boot. These sets of services are defined by adding links in the directories /etc/rc3.d, /etc/rc5.d, etc. The contents of the files in these directories is not currently used; their file names are collected to define the list of services.

Service Definitions

All service definitions are read on boot by /etc/shepherd.scm from the files in /etc/shepherd.d. Each of these files must be a Guile script that ends with the creation of a service object, so the service object is the result of evaluating the script.

See the Shepherd manual for a more complete list of service object slots, but new service objects should at least define the following.

• start is a Guile procedure that runs the service. It will usually be the returned value of make-forkexec-constructor called with a list of command argument strings to be executed.

• stop is a Guile procedure that kills the service. It will usually be the returned value of make-kill-destructor.

• provides is a list of symbols that can be used as the service name.

• requires is a list of symbols naming other services that must be running before this service is started.

• docstring is a string that describes the service. It is the output of sudo herd doc $service where $service is a name listed in provides.

Another useful slot is actions, which defines new commands that can be run on the service. Consider if the following was defined on a service example.

#:actions (make-actions
 (reload "Reload the service's configuration files."
  (lambda (running)
   (if running
    (kill running SIGHUP)
    (local-output "This service is not running.")))))

This will allow running sudo herd reload example to send a SIGHUP to the service's main process, which commonly triggers reloading configuration files.

The Console - GNU Hurd

When using all default settings, the system will finish its boot/initialization process at a login prompt on the Hurd console. Two usable accounts are provided from a fresh install, root and gnu. The gnu account is a regular user with unrestricted sudo abilities.

Usage

There are six virtual consoles by default. With Alt+Left or Alt+Right you can switch to an adjacent console, and Alt+n will jump to the console numbered n.

The virtual consoles store 10,000 lines of output by default. To scroll up and down in the text by half the screen, press Shift+PgUp and Shift+PgDn, respectively. The consoles can also be scrolled by a single line with Shift+Up and Shift+Down. Press Alt+Home to jump to the earliest line, and press Alt+End to jump to the last line.

Pressing Ctrl+Alt+Backspace will terminate the Hurd console client and return to the GNU Mach console. The console service should be used to gracefully stop and start the Hurd console, however. This command will use GNU Shepherd to return to the more basic GNU Mach console.

sudo herd stop console

Configuration

The Hurd console's configuration is mostly handled by changing command line arguments for the server and client. The server is started by a translator record on /dev/vcs, and the client command is defined as a Shepherd service in /etc/shepherd.d/console.scm. See also /etc/ttys for the list of all virtual consoles that get started by the runttys service.

Keymaps

X11 keymaps are used by the Hurd console client's pc_kbd driver, and its default is /usr/share/X11/xkb/keymap/hurd. It can be changed by setting the driver's options --xkbdir, --keymapfile, and --keymap in the console client's service file.

Fonts

Custom BDF fonts can be used on the Hurd console by setting the vga driver options --font, --font-bold, --font-bold-italic, and --font-italic in the service file. These options override the following default files.

• /usr/share/hurd/vga-system.bdf
• /usr/share/hurd/vga-system-bold.bdf
• /usr/share/hurd/vga-system-bold-italic.bdf
• /usr/share/hurd/vga-system-italic.bdf

Note that the system font will be used in place of any missing fonts, so it may be preferable to omit some of them to improve the console startup time.

Colors

The default colors can be changed with translator options on /dev/vcs. To change them persistently, alter the translator record. For example, this will make the Hurd console appear as a black-on-white display.

sudo settrans -acfgp /dev/vcs \
    /hurd/console --lines=10000 --foreground=black --background=white ; \
sudo herd restart console

Be sure to restart the client on the same command as above, so it reconnects to the server as it is replaced. Also note that the --lines=10000 argument preserves the setting that stores 10,000 lines of console output.

The Desktop - GNU Window Maker

Most methods of logging into the graphical X environment will launch wmaker by default. Running startx from the Hurd console will directly present the user's desktop, and starting the xdm service will provide a graphical login prompt allowing different users to log into their desktop environment. Setting default-runlevel to 5 in /etc/shepherd.scm will make XDM the default login prompt when the system boots.

Usage

Applications can be accessed easily from the desktop's right-click menu, as can adding new workspaces, changing themes, etc. Pressing Alt+F2 will display a window prompting for a command to execute.

The default key configuration is fairly consistent with the Hurd console. To switch workspaces, use Alt+Left, Alt+Right, and Alt+n for workspace n. X can be terminated with Ctrl+Alt+Backspace to return to the Hurd console, but it is preferable to stop the xdm service to gracefully quit the display server.

Windows can be moved by clicking on their title bars and dragging or by holding Alt and clicking anywhere and dragging. They are automatically maximized when dragged to the top of the screen, and moving a maximized window will unmaximize it. They can also be dragged to the left or right of the screen to change to an adjacent workspace.

To pin a running application's icon to the desktop to use it as a launcher later, dragging its icon to the right side of the screen will pin it to all workspaces, and dragging it to the paperclip icon will pin it to only the current workspace. Drag the icon away from the tray areas to remove it.

To return to the XDM login screen, choose to exit Window Maker on the desktop's right-click menu.

Configuration

User-specific settings are saved under GNUstep in the user's home directory. Their default values are based on the global configuration files stored in /etc/WindowMaker.

Most of Window Maker's behavior can be configured through its graphical program WPrefs. Running the command WPrefs is equivalent to launching the icon at the lower right corner of the desktop or selecting the configuration item of the right-click menu.

The individual application launchers' settings can be modified from their right-click menus.

Window Maker can be restarted from the desktop's right-click menu to save all configuration changes to disk and verify that they are loaded properly when it starts.