The autorun feature allows you to run scripts or binary programs automatically at startup of the system. Each autorun script can manage a task. For example, you can create a backup script that makes a backup of a database, another for cleaning a system, …
By default, the autorun script(s) can be copied in the autorun
directory of the ISO image
or boot device, outside of the squashfs compressed image file, but other sources
are available too: local file system, network share, an HTTP/HTTPS server.
SystemRescue offers two methods to configure autorun programs:
autorun
in a set of locations
are loaded and executed. This is the old style of configuring autorun.Both methods are fully supported and are planned to stay available in future releases.
Synopis:
---
autorun:
exec:
200:
url: "http://web-server/adminscripts/some-script"
parameters:
- "foo"
- "bar"
shell: false
wait: always
waitmode: 15
on_error: break
300:
path: "rclone"
parameters:
- "copy"
- "myserver:/scripts/"
- "/root"
wait: on_error
on_error: break
Configuration is done through entries in the YAML configuration
using exec
entries in the autorun
scope. The keys in the exec
Mapping / dictionary
(200
and 300
in the example above) are names for each autorun program. The programs are
executed in lexicographic order of these names.
Options for each exec
entry:
url
or path
entry, but may not have bothnfs://hostname:/path/script
smb://hostname/share/path
. Be aware that only public guest shares without password are supported./dev/sda1/usr/bin/script
or
/dev/disk/by-label/mylabel/usr/bin/script
./run/archiso/bootmnt/autorun/
to access scripts in the autorun
directory on the boot media.copytoram
option while other parts of the boot media are not available when using copytoram
.false
) controls if the program is executed directly or through the /bin/sh
shell.
always
, on_error
or never
, default is on_error
. Controls if/when to wait directly after
execution of this one script.key
for requiring a keypress or a number, indicating the number of seconds to wait. You can press a key to
continue before the given number of seconds is expired. Default is 30
.break
or continue
, with ar_ignorefail
controlling the default. Defines what to do with the
following scripts after this script failed (returned a non-zero status).Scripts to execute are searched using a list of rules (see below).
If scripts are found, entries in the exec
Mapping / dictionary are created for them.
This allows to use YAML based autorun and name based autorun programs to be used together.
/dev/sda1
), an nfs share
(nfs://192.168.1.1:/path/to/scripts
), a samba share (smb://192.168.1.1/path/to/scripts
),
or an http/https directory (http://192.168.1.1/path/to/scripts
).
Please note this parameter contains the address of the folder which
contains some autorun script. This is not the full address of a particular
script, as the name of the script will be added at the end of the source.ar_suffixes=0,2,7
then the following autorun scripts will be executed:
autorun0
, autorun2
, autorun7
, and scripts with other suffixes will be
ignored. Use ar_suffixes=no
to disable all the autorun scripts with a suffix.At startup, a list of locations is checked against the presence of autorun files. They are, successively:
If autorun files are found in some location, they are added to the exec
Mapping / dictionary
and the following locations are ignored.
In each source location, there are two possible modes of operation :
autorun
is found, it is runautorun#
scripts are found (# is a digit from
0 to 9 or letter A to F) and either
ar_suffixes=
boot parameter was NOT specified, orar_suffixes=
boot parameter value contains #Example: With ar_suffixes=0,1,4
only autorun0
, autorun1
and autorun4
scripts will be executed if present. Other scripts, such as autorun2
and
autorun3
will be ignored.
A script with the filename autorun
will get the name 1000-autorun
within the exec
Mapping / dictionary.
autorun0
will get 1010-autorun0
, autorun1
will be 1011-autorun1
and so on until 1025-autorunF
.
This naming scheme allows to control the execution order when using YAML config based autorun together
with name based autorun.
These options are used to control the general behaviour of autorun. They can be specified either on the boot command line or through YAML configuration files
/var/autorun/tmp
after execution (default: false)The easiest method to get autorun programs onto a SystemRescue media is usually to
create a writable USB boot media for SystemRescue. This can be done with
Rufus or SystemRescue USB writer as described here.
You can mount the USB media afterwards and copy the autorun scripts into
the autorun
directory using a regular file manager.
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 copy autorun scripts to the device.
If creating a writeable USB media is not possible, you can modify the ISO image with sysrescue-customize.
To write programs to the /root
or /usr/share/sys.autorun
directory, you have
to modify not the boot media, but the the filesystem that SystemRescue boots to (airootfs).
This can be best be achieved by using SystemRescue Modules (SRM) or
with a permanent backing store.
The script can be any script using an installed interpreter like shell, Python, Perl, … It must have a shebang (#!) at the beginning to indicate the interpreter to use. ELF binaries are also supported.
Autorun programs are executed on the main system console. All their output is written to
the console and input from the console is passed to the program. Escape sequences are not
passed through, so using a curses based text UI (for example like setkmap
) is not supported.
For programs with user interaction, using autoterminal
is the preferred solution over autorun.
Since SystemRescue 9.00, you can find a general autorun log file in
/var/log/sysrescue-autorun.log
to determine what has gone wrong. Use this log
file if you have a general autorun issue, for example if your script has not
been executed. The autorun output is also logged to the systemd journal.
Each autorun script additionally creates its own log file and a file with the returncode in /var/autorun/log
.
Use these logs to investigate issues affecting a particular autorun script.
For debugging it can be helpful to rerun autostart later when the system is already running. You can do this by calling /etc/systemd/scripts/sysrescue-autorun
.