Site map
System tools
Bootable USB
Package list
Boot options
Disk install

Configuring SystemRescue


SystemRescue comes with options which allows users to change the way it runs. For example, there are options for controlling which keyboard of layout to use, whether the system must be run from memory or from the boot device, whether or not to automatically start the graphical environment, and so on. You can follow the link to see the list of boot options which are supported on the command line.

These options are set on the boot command line. To change these options, you can either manually edit the boot command line from the boot loader at run time, or you can make the changes persistent by editing the configuration file of the boot loaders, which are either isolinux if you start in BIOS mode or Grub if you start in UEFI mode.

Configuration features

Since SystemRescue version 9.00 there is another way to configure SystemRescue. You can now edit a YAML file on the boot device in order to configure it. This configuration file has been introduced to make it easy to make persistent configuration changes, and these options are effective for both the BIOS mode and UEFI mode.

The SystemRescue configuration YAML files are located in the sysrescue.d folder located on the boot device.

SystemRescue comes with a default YAML configuration file, so it provides a good example of such a file, which you can use as a starting point. You can edit it to replace the options with your own preferences.

These yaml configuration files support multiple scopes. The main scope is called global and is contains general configuration entries. The autorun scope is used to define configuration entries which are used by autorun.

Configuration entries

Below is an example of a valid yaml configuration file. In this example there are entries in both the global and autorun scopes. The copytoram option is enabled so the system is fully copied to memory at boot time, the checksum option is also enabled so the system checks its integrity at boot time, as well as the dostartx option in order to automatically start the graphical environment. Both the nofirewall and loadsrm options are left disabled, so the firewall will not be turned off and SRM modules will not be loaded. The setkmap option is used to configure a french keyboard layout. All these general options belong to the global scope. The autorun scope contains entries to determine how autorun scripts will be executed. These options are only useful if you wish to use autorun to run custom scripts automatically.

    copytoram: true
    checksum: true
    nofirewall: false
    loadsrm: false
    setkmap: fr-latin1
    dostartx: true
    dovnc: false
    rootshell: /bin/bash
    rootpass: MyRootPassword123
    vncpass: MyVncPassword456

    ar_disable: false
    ar_nowait: false
    ar_nodel: false
    ar_attempts: 1
    ar_ignorefail: false
    ar_suffixes: 0,1,2,3,4,5

Status of this feature

At this stage only a few essential options are supported in the configuration file. Only the options shown is the example above are supported at this stage. Please refer to boot options to find a full description of each general option.

The plan is to add support for more options or services in the future. Also you can take advantage of this mechanism and use these yaml configuration files to configure your own scripts that are executed from SystemRescue. You should create new scopes in your configuration files if you plan to do so.

How to use the yaml configuration file

To be able to configure SystemRescue using this YAML configuration files, you must edit the existing YAML file located in sysrescue.d on the boot device, or you can create additional YAML files in the same location.

Files must have a .yaml extension (not .yml), otherwise the file will be ignored. Also make sure you follow the yaml syntax correctly. Key and values are separated by colons, not equal signs, and the indentation is very important.

The system reads any file with a yaml extension located in the correct folder, and it is case insensitive. Files are processed in the alphabetical order, so the settings in the file which come last can override settings which have been defined before. Default configuration yaml files are provided with file names starting with numbers so it is easy to control the sequence in which these files are loaded. You should create custom files with a higher number if you want to be sure these settings will take precedence over different settings from default yaml files. Please note that options passed on the boot command line will take precedence over options in any yaml configuration file.

The simplest way to create or edit the configuration file is to install SystemRescue on a writable device (such as a USB memory stick) with a writable file system (such as FAT32). If you install SystemRescue on a USB stick using either dd or any other tool which performs a physical copy of the ISO image, it will not produce a writable file system, and you will not be able to edit the configuration file on the device. Hence it is highly recommended to install SystemRescue on a USB memory stick using rufus, and you must choose to use the ISO mode rather than the DD mode when prompted.

You can also use sysrescue-customize to create a custom version of the SystemRescue ISO image. The customisation process allows you to add your own yaml configuration files (along with other additional files if you want to) to the ISO image. You can then write your custom ISO image on any type of boot device, it does not need to contain a writable file system.

Implementation details

Support for options located in the YAML configuration file are implemented in multiple places:

First archiso hooks run some code to process options such as copytoram and checksum which must be processed at an early stage during the boot process, as part of the initramfs.

Then provides support for options that are processed during the second phase of the system initialisation.

Manual (EN)
LVM Guide
Disk partitioning

Git repository
Website sources
Bug tracker