sysdig

title: sysdig(8)

text:
# sysdig(8)

### NAME
sysdig - the definitive system and process troubleshooting tool

### SYNOPSIS
sysdig [option]... [filter]

### DESCRIPTION
Note: if you are interested in an easier to use interface for the sysdig functionality, use the csysdig command line utility.

sysdig is a tool for system troubleshooting, analysis and exploration. It can be used to capture, filter and decode system calls and other OS events. sysdig can be both used to inspect live systems, or to generate trace files that can be analyzed at a later stage.

sysdig includes a powerful filtering language, has customizable output, and can be extended through Lua scripts, called chisels.

Output format

By default, sysdig prints the information for each captured event on a single line, with the following format:

*%evt.num %evt.time %evt.cpu %proc.name (%thread.tid) %evt.dir %evt.type %evt.info

where:

•

evt.num is the incremental event number

•

evt.time is the event timestamp

•

evt.cpu is the CPU number where the event was captured

•

proc.name is the name of the process that generated the event

•

thread.tid id the TID that generated the event, which corresponds to the PID for single thread processes

•

evt.dir is the event direction, > for enter events and < for exit events

•

evt.type is the name of the event, e.g. 'open' or 'read'

•

evt.args is the list of event arguments.

The output format can be customized with the -p switch, using any of the fields listed by 'sysdig -l'.

Using -pc or -pcontainer, the default format will be changed to a container-friendly one:

*%evt.num %evt.time %evt.cpu %container.name (%container.id) %proc.name (%thread.tid:%thread.vtid) %evt.dir %evt.type %evt.info

Trace Files

A trace file can be created using the -w switch:

$ sysdig -w trace.scap

The -s switch can be used to specify how many bytes of each data buffer should be saved to disk. And filters can be used to save only certain events to disk:

$ sysdig -s 2000 -w trace.scap proc.name=cat

Trace files can be read this using the -r switch:

$ sysdig -r trace.scap

Filtering

sysdig filters are specified at the end of the command line. The simplest filter is a basic field-value check:

$ sysdig proc.name=cat

The list of available fields can be obtained with 'sysdig -l'. Filter expressions can use one of these comparison operators: =, !=, <, <=, >, >=, contains, icontains, in and exists. e.g.

$ sysdig fd.name contains /etc $ sysdig "evt.type in ( 'select', 'poll' )" $ sysdig proc.name exists

Multiple checks can be combined through brackets and the following boolean operators: and, or, not. e.g.

$ sysdig "not (fd.name contains /proc or fd.name contains /dev)"

Chisels

sysdig's chisels are little scripts that analyze the sysdig event stream to perform useful actions. To get the list of available chisels, type

$ sysdig -cl

To get details about a specific chisel, type

$ sysdig -i spy_ip

To run one of the chisels, you use the -c flag, e.g.

$ sysdig -c topfiles_bytes

If a chisel needs arguments, you specify them after the chisel name:

$ sysdig -c spy_ip 192.168.1.157

If a chisel has more than one argument, specify them after the chisel name, enclosed in quotes:

$ sysdig -c chisel_name "arg1 arg2 arg3"

Chisels can be combined with filters:

$ sysdig -c topfiles_bytes "not fd.name contains /dev"

### OPTIONS
-A, --print-ascii Only print the text portion of data buffers, and echo end-of-lines. This is useful to only display human-readable data.

-b, --print-base64 Print data buffers in base64. This is useful for encoding binary data that needs to be used over media designed to handle textual data (i.e., terminal or json).

-c chiselname chiselargs, --chisel=chiselname chiselargs run the specified chisel. If the chisel require arguments, they must be specified in the command line after the name.

-C filesize Break a capture into separate files, and limit the size of each file based on the specified number of megabytes. The units of filesize are millions of bytes (10^6, not 2^20). Use in conjunction with -W to enable automatic file rotation. Otherwise, new files will continue to be created until the capture is manually stopped.

Files will have the name specified by -w with a counter added starting at 0.

-cl, --list-chisels lists the available chisels. Sysdig looks for chisels in the following directories: ./chisels, ~/.chisels and /usr/share/sysdig/chisels.

-d, --displayflt Make the given filter a display one. Setting this option causes the events to be filtered after being parsed by the state system. Events are normally filtered before being analyzed, which is more efficient, but can cause state (e.g. FD names) to be lost.

-D, --debug Capture events about sysdig itself, display internal events in addition to system events, and print additional logging on standard error.

-E, --exclude-users Don't create the user/group tables by querying the OS when sysdig starts. This also means that no user or group info will be written to the tracefile by the -w flag. The user/group tables are necessary to use filter fields like user.name or group.name. However, creating them can increase sysdig's startup time. Moreover, they contain information that could be privacy sensitive.

-e numevents Break a capture into separate files, and limit the size of each file based on the specified number of events. Use in conjunction with -W to enable automatic file rotation. Otherwise, new files will continue to be created until the capture is manually stopped.

Files will have the name specified by -w with a counter added starting at 0.

-F, --fatfile Enable fatfile mode. When writing in fatfile mode, the output file will contain events that will be invisible when reading the file, but that are necessary to fully reconstruct the state. Fatfile mode is useful when saving events to disk with an aggressive filter. The filter could drop events that would cause the state to be updated (e.g. clone() or open()). With fatfile mode, those events are still saved to file, but 'hidden' so that they won't appear when reading the file. Be aware that using this flag might generate substantially bigger traces files.

--filter-proclist apply the filter to the process table. A full dump of /proc is typically included in any trace file to make sure all the state required to decode events is in the file. This could cause the file to contain unwanted or sensitive information. Using this flag causes the command line filter to be applied to the /proc dump as well.

-G numseconds Break a capture into separate files, and limit the size of each file based on the specified number of seconds. Use in conjunction with -W to enable automatic file rotation. Otherwise, new files will continue to be created until the capture is manually stopped.

Files will have the name specified by -w which should include a time format as defined by strftime(3). If no time format is specified, a counter will be used.

-h, --help Print this page

-H pluginname[:initconfig], --plugin pluginname[:initconfig] Registers a plugin, using the passed init config if present. A path can also be used as pluginname. The format of initconf is controlled by the plugin, refer to each plugin's documentation to learn about it.

-I pluginname[:openparams], --input pluginname[:openparams] Capture events using the plugin with name pluginname, passing to the plugin the openparams string as parameters. The format of inputargs is controller by the plugin, refer to each plugin's documentation to learn about it. The event sources available for capture vary depending on which plugins have been installed. You can list the plugins that have been loaded by using the -Il flag.

-Il, --list-inputs List the loaded plugins. Sysdig looks for plugins in the following directories: ./plugins, ~/.plugins, /usr/share/sysdig/plugins.

--plugin-config-file Load the plugin configuration from a Falco-compatible yaml config file. Mixing this option with '-H' or '-I' is unsupported. See the plugin section in <https://falco.org/docs/configuration/> for additional informations.

-i chiselname, --chisel-info=_chiselname_ Get a longer description and the arguments associated with a chisel found in the -cl option list.

-j, --json Emit output as json, data buffer encoding will depend from the print format selected.

-k, --k8s-api Enable Kubernetes support by connecting to the API server specified as argument. E.g. "<http://admin:password@127.0.0.1:8080>". The API server can also be specified via the environment variable SYSDIG_K8S_API.

-K btfile | certfile:keyfile[#password][:cacertfile], --k8s-api-cert=_btfile | certfile:keyfile[#password][:cacertfile]_ Use the provided files names to authenticate user and (optionally) verify the K8S API server identity. Each entry must specify full (absolute, or relative to the current directory) path to the respective file. Private key password is optional (needed only if key is password protected). CA certificate is optional. For all files, only PEM file format is supported. Specifying CA certificate only is obsoleted - when single entry is provided for this option, it will be interpreted as the name of a file containing bearer token. Note that the format of this command-line option prohibits use of files whose names contain ':' or '#' characters in the file name. Option can also be provided via the environment variable SYSDIG_K8S_API_CERT.

-L, --list-events List the events that the engine supports

-l, --list List the fields that can be used for filtering and output formatting. Use -lv to get additional information for each field.

--list-markdown Like -l, but produces markdown output

-m url[,marathon-url], --mesos-api=_url[,marathon-url]_ Enable Mesos support by connecting to the API server specified as argument (e.g. <http://admin:password@127.0.0.1:5050>). Mesos url is required. Marathon url is optional, defaulting to auto-follow - if Marathon API server is not provided, sysdig will attempt to retrieve (and subsequently follow, if it migrates) the location of Marathon API server from the Mesos master. Note that, with auto-follow, sysdig will likely receive a cluster internal IP address for Marathon API server, so running sysdig with Marathon auto-follow from a node that is not part of Mesos cluster may not work. Additionally, running sysdig with Mesos support on a node that has no containers managed by Mesos is of limited use because, although cluster metadata will be collected, there will be no Mesos/Marathon filtering capability. The API servers can also be specified via the environment variable SYSDIG_MESOS_API.

-M num_seconds Stop collecting after reaching

-n num, --numevents=num

Stop capturing after num events

--page-faults Capture user/kernel major/minor page faults

-P, --progress

Print progress on stderr while processing trace files.

-p outputformat, --print=outputformat

Specify the format to be used when printing the events. With -pc or -pcontainer will use a container-friendly format. With -pk or -pkubernetes will use a kubernetes-friendly format. With -pm or -pmesos will use a mesos-friendly format. Specifying -pp on the command line will cause sysdig to print the default command line format and exit.

-q, --quiet

Don't print events on the screen. Useful when dumping to disk.

-r readfile, --read=readfile

Read the events from readfile.

-R, --resolve-ports Resolve port numbers to names.

-S, --summary

print the event summary (i.e. the list of the top events) when the capture ends.

-s len, --snaplen=len

Capture the first len bytes of each I/O buffer. By default, the first 80 bytes are captured. Use this option with caution, it can generate huge trace files.

-t timetype, --timetype=timetype

Change the way event time is displayed. Accepted values are h for human-readable string, a for absolute timestamp from epoch, r for relative time from the first displayed event, d for delta between event enter and exit, and D for delta from the previous event.

-T, --force-tracers-capture

Tell the driver to make sure full buffers are captured from /dev/null, to make sure that tracers are completely captured. Note that sysdig will enable extended /dev/null capture by itself after detecting that tracers are written there, but that could result in the truncation of some tracers at the beginning of the capture. This option allows preventing that.

--unbuffered

Turn off output buffering. This causes every single line emitted by sysdig to be flushed, which generates higher CPU usage but is useful when piping sysdig's output into another process or into a script.

-v, --verbose

Verbose output. This flag will cause the full content of text and binary buffers to be printed on screen, instead of being truncated to 40 characters. Note that data buffers length is still limited by the snaplen (refer to the -s flag documentation) -v will also make sysdig print some summary information at the end of the capture.

--version

Print version number.

-w writefile, --write=writefile

Write the captured events to writefile.

-W num

Turn on file rotation for continuous capture, and limit the number of files created to the specified number. Once the cap is reached, older files will be overwritten (ring buffer). Use in conjunction with the -C / -G / -e options to limit the size of each file based on number of megabytes, seconds, and/or events (respectively).

-x, --print-hex

Print data buffers in hex.

-X, --print-hex-ascii

Print data buffers in hex and ASCII.

-z, --compress

Used with -w, enables compression for tracefiles.

### EXAMPLES
Capture all the events from the live system and print them to screen

$ sysdig

Capture all the events from the live system and save them to disk

$ sysdig -w dumpfile.scap

Capture all the events in the latest 24 hours and save them to disk organized in files containing 1 hour of system activity each

$ sysdig -G 3600 -W 24 -w dumpfile.scap

Read events from a file and print them to screen

$ sysdig -r dumpfile.scap

Prepare a sanitized version of a system capture

$ sysdig -r dumpfile.scap 'not evt.buffer contains foo' -w cleandump.scap

Print all the open system calls invoked by cat

$ sysdig proc.name=cat and evt.type=open

Print the name of the files opened by cat

$ sysdig -p"%evt.arg.name" proc.name=cat and evt.type=open

List the available chisels

$ sysdig -cl

Use the spy_ip chisel to look at the data exchanged with 192.168.1.157:

$ sysdig -c spy_ip 192.168.1.157

### FILES
/usr/share/sysdig/chisels

The global chisels directory.

~/.chisels

The personal chisels directory.

### BUGS
•

sysdig and its chisels are designed to be used with LuaJIT in Lua 5.1 mode. While it is possible to use sysdig with LuaJIT in Lua 5.2 mode or regular Lua, some chisels may not work as expected.

### AUTHOR
Draios Inc. aka sysdig <info@sysdigcloud.com>

### SEE ALSO
csysdig(8), strace(8), tcpdump(8), lsof(8)


syslog-ng

package: syslog-ng

title: syslog-ng(8)

summary: syslog\-ng system logger application

text:
# syslog-ng(8)

## NAME
syslog-ng - syslog-ng system logger application

## SYNOPSIS
syslog-ng [options]

## DESCRIPTION
This manual page is only an abstract, for the complete documentation of syslog-ng, see The Administrator Guide[1] or the official syslog-ng website[2].

The application is a flexible and highly scalable system logging application. Typically, syslog-ng is used to manage log messages and implement centralized logging, where the aim is to collect the log messages of several devices on a single, central log server. The different devices - called syslog-ng clients - all run syslog-ng, and collect the log messages from the various applications, files, and other sources. The clients send all important log messages to the remote syslog-ng server, where the server sorts and stores them.

## OPTIONS
--caps

Run process with the specified POSIX capability flags.

•If the --no-caps option is not set, and the host supports CAP_SYSLOG, uses the following capabilities: "cap_net_bind_service, cap_net_broadcast, cap_net_raw, cap_dac_read_search, cap_dac_override, cap_chown, cap_fowner=p cap_syslog=ep"

•If the --no-caps option is not set, and the host does not support CAP_SYSLOG, uses the following capabilities: "cap_net_bind_service, cap_net_broadcast, cap_net_raw,cap_dac_read_search, cap_dac_override, cap_chown, cap_fowner=p cap_sys_admin=ep"

For example:

```
/usr/sbin/syslog-ng -Fv --caps cap_sys_admin,cap_chown,cap_dac_override,cap_net_bind_service,cap_fowner=pi
```

Note that the capabilities are not case sensitive, the following command is also good: /usr/sbin/syslog-ng -Fv --caps CAP_SYS_ADMIN,CAP_CHOWN,CAP_DAC_OVERRIDE,CAP_NET_BIND_SERVICE,CAP_FOWNER=pi

For details on the capability flags, see the following man pages: cap_from_text(3) and capabilities(7)

--cfgfile <file> or -f <file>

Use the specified configuration file.

--chroot <dir> or -C <dir>

Change root to the specified directory. The configuration file is read after chrooting so, the configuration file must be available within the chroot. That way it is also possible to reload the syslog-ng configuration after chrooting. However, note that the --user and --group options are resolved before chrooting.

--control <file> or -c <file>

Set the location of the syslog-ng control socket. Default value: /var/run/syslog-ng.ctl

--debug or -d

Start syslog-ng in debug mode.

--enable-core

Enable syslog-ng to write core files in case of a crash to help support and debugging.

--fd-limit <number>

Set the minimal number of required file descriptors (fd-s). This sets how many files syslog-ng can keep open simultaneously. Default value: 4096. Note that this does not override the global ulimit setting of the host.

--foreground or -F

Do not daemonize, run in the foreground. When running in the foreground, starts from the current directory ($CWD) so it can create core files (normally, starts from $PREFIX/var).

--group <group> or -g <group>

Switch to the specified group after initializing the configuration file.

--help or -h

Display a brief help message.

--module-registry

Display the list and description of the available modules. Available only in and later.

--no-caps

Run syslog-ng as root, without capability-support. This is the default behavior. On Linux, it is possible to run syslog-ng as non-root with capability-support if syslog-ng was compiled with the --enable-linux-caps option enabled. (Execute syslog-ng --version to display the list of enabled build parameters.) To run with specific capabilities, use the --caps option.

--persist-file <persist-file> or -R <persist-file>

Set the path and name of the syslog-ng.persist file where the persistent options and data are stored.

--pidfile <pidfile> or -p <pidfile>

Set path to the PID file where the pid of the main process is stored.

--preprocess-into <output-file>

After processing the configuration file and resolving included files and variables, write the resulting configuration into the specified output file. Available only in and later.

--process-mode <mode>

Sets how to run syslog-ng: in the foreground (mainly used for debugging), in the background as a daemon, or in safe-background mode. By default, syslog-ng runs in safe-background mode. This mode creates a supervisor process called supervising syslog-ng , that restarts syslog-ng if it crashes.

--stderr or -e

Log internal messages of syslog-ng to stderr. Mainly used for debugging purposes in conjunction with the --foreground option. If not specified, syslog-ng will log such messages to its internal source.

--syntax-only or -s

Verify that the configuration file is syntactically correct and exit.

--user <user> or -u <user>

Switch to the specified user after initializing the configuration file (and optionally chrooting). Note that it is not possible to reload the syslog-ng configuration if the specified user has no privilege to create the /dev/log file.

--verbose or -v

Enable verbose logging used to troubleshoot syslog-ng.

--version or -V

Display version number and compilation information, and also the list and short description of the available modules. For detailed description of the available modules, see the --module-registry option.

--worker-threads

Sets the number of worker threads can use, including the main thread. Note that certain operations in can use threads that are not limited by this option. This setting has effect only when is running in multithreaded mode. Available only in and later. See The 3.32 Administrator Guide for details.

## FILES
/usr/

/etc/syslog-ng/syslog-ng.conf

## SEE ALSO
syslog-ng.conf(5)

Note

For the detailed documentation of see The 3.32 Administrator Guide[3]

If you experience any problems or need help with syslog-ng, visit the syslog-ng mailing list[4].

For news and notifications about of syslog-ng, visit the syslog-ng blogs[5].

## AUTHOR
This manual page was written by the Balabit Documentation Team <documentation@balabit.com>.

## NOTES
1.

The Administrator Guide

https://www.balabit.com/support/documentation/

2.

the official syslog-ng website

https://www.balabit.com/log-management

3.

The 3.32 Administrator Guide

https://www.balabit.com/documents/syslog-ng-ose-latest-guides/en/syslog-ng-ose-guide-admin/html/index.html

4.

syslog-ng mailing list

https://lists.balabit.hu/mailman/listinfo/syslog-ng

5.

syslog-ng blogs

https://syslog-ng.org/blogs/


sysklogd

package: syslogd

title: sysklogd(8)

summary: Linux system logging utilities.

text:
# sysklogd(8)

## NAME
sysklogd - Linux system logging utilities.

## SYNOPSIS
syslogd [ -4 ] [ -6 ] [ -A ] [ -a socket ] [ -c ] [ -d ] [ -f config file ] [ -h ] [ -i IP address ] [ -l hostlist ] [ -m interval ] [ -n ] [ -p socket ] [ -P directory ] [ -r ] [ -s domainlist ] [ -u username ] [ -j chroot_dir ] [ -v ]

## DESCRIPTION
Sysklogd provides two system utilities which provide support for system logging and kernel message trapping. Support of both internet and unix domain sockets enables this utility package to support both local and remote logging.

System logging is provided by a version of syslogd(8) derived from the stock BSD sources. Support for kernel logging is provided by the klogd(8) utility which allows kernel logging to be conducted in either a standalone fashion or as a client of syslogd.

Syslogd provides a kind of logging that many modern programs use. Every logged message contains at least a time and a hostname field, normally a program name field, too, but that depends on how trusty the logging program is.

While the syslogd sources have been heavily modified a couple of notes are in order. First of all there has been a systematic attempt to insure that syslogd follows its default, standard BSD behavior. The second important concept to note is that this version of syslogd interacts transparently with the version of syslog found in the standard libraries. If a binary linked to the standard shared libraries fails to function correctly we would like an example of the anomalous behavior.

The main configuration file /etc/syslog.conf or an alternative file, given with the -f option, is read at startup. Any lines that begin with the hash mark (``#'') and empty lines are ignored. If an error occurs during parsing the whole line is ignored.

## OPTIONS
-4

Force syslogd to use IPv4 addresses only.

-6

Force syslogd to use IPv6 addresses only.

-A

Ordinarily, syslogd tries to send the message to only one address even if the host has more than one A or AAAA record. If this option is specified, syslogd tries to send the message to all addresses.

-a socket

Using this argument you can specify additional sockets from that syslogd has to listen to. This is needed if you're going to let some daemon run within a chroot() environment. You can use up to 19 additional sockets. If your environment needs even more, you have to increase the symbol MAXFUNIX within the syslogd.c source file. An example for a chroot() daemon is described by the people from OpenBSD at <http://www.guides.sk/psionic/dns/>.

-c

Disable the repeating line compression that normally suppresses the repeated lines and logs a message such as 'last message repeated 124 times'. With this option, all repeated lines will be logged.

-d

Turns on debug mode. Using this the daemon will not proceed a fork(2) to set itself in the background, but opposite to that stay in the foreground and write much debug information on the current tty. See the DEBUGGING section for more information.

-f config file

Specify an alternative configuration file instead of /etc/syslog.conf, which is the default.

-h

By default syslogd will not forward messages it receives from remote hosts. Specifying this switch on the command line will cause the log daemon to forward any remote messages it receives to forwarding hosts which have been defined. This can cause syslog loops that fill up hard disks quite fast and thus needs to be used with caution.

-i IP address

If syslogd is configured to accept log input from a UDP port, specify an IP address to bind to, rather than the default of INADDR_ANY. The address must be in dotted quad notation, DNS host names are not allowed.

-l hostlist

Specify a hostname that should be logged only with its simple hostname and not the fqdn. Multiple hosts may be specified using the colon (``:'') separator.

-m interval

The syslogd logs a mark timestamp regularly. The default interval between two -- MARK -- lines is 20 minutes. This can be changed with this option. Setting the interval to zero turns it off entirely. Depending on other log messages generated these lines may not be written consecutively. The -- MARK -- message is only written if the log file hasn't been touched in interval/2 minutes.

-n

Avoid auto-backgrounding. This is needed especially if the syslogd is started and controlled by init(8).

-p socket

You can specify an alternative unix domain socket instead of /dev/log.

-P directory

Using this argument you can specify directory with symlinks to additional sockets from that syslogd has to listen to. This is convenient method if you're going to let several daemons run within different chrooted environments.

-r

This option will enable the facility to receive message from the network using an internet domain socket with the syslog service (see services(5)). The default is to not receive any messages from the network. This option is introduced in version 1.3 of the sysklogd package. Please note that the default behavior is the opposite of how older versions behave, so you might have to turn this on.

-s domainlist

Specify a domainname that should be stripped off before logging. Multiple domains may be specified using the colon (``:'') separator. Please be advised that no sub-domains may be specified but only entire domains. For example if -s north.de is specified and the host logging resolves to satu.infodrom.north.de no domain would be cut, you will have to specify two domains like: -s north.de:infodrom.north.de.

-u username

This causes the syslogd daemon to become the named user before starting up logging. Note that when this option is in use, syslogd will open all log files as root when the daemon is first started; however, after a SIGHUP the files will be reopened as the non-privileged user. You should take this into account when deciding the ownership of the log files.

-j chroot_dir

Tells syslogd daemon to chroot(2) into this directory after initializing. This option is only valid if the -u option is also used to run syslogd without root privileges. Note that the use of this option will prevent SIGHUP from working which makes daemon reload practically impossible.

-v

Print version and exit.

## SIGNALS
Syslogd reacts to a set of signals. You may easily send a signal to syslogd using the following:

```
kill -SIGNAL `cat /var/run/syslogd.pid`
```

SIGHUP

This lets syslogd perform a re-initialization. All open files are closed, the configuration file (default is /etc/syslog.conf) will be reread and the syslog(3) facility is started again.

SIGTERM

The syslogd will die.

SIGINT, SIGQUIT

If debugging is enabled these are ignored, otherwise syslogd will die.

SIGUSR1

Switch debugging on/off. This option can only be used if syslogd is started with the -d debug option.

SIGCHLD

Wait for childs if some were born, because of wall'ing messages.

## CONFIGURATION FILE SYNTAX DIFFERENCES
Syslogd uses a slightly different syntax for its configuration file than the original BSD sources. Originally all messages of a specific priority and above were forwarded to the log file.

For example the following line caused ALL output from daemons using the daemon facilities (debug is the lowest priority, so every higher will also match) to go into /usr/adm/daemons:

```
	# Sample syslog.conf
	daemon.debug			/usr/adm/daemons
```

Under the new scheme this behavior remains the same. The difference is the addition of four new specifiers, the asterisk (*) wildcard, the equation sign (=), the exclamation mark (!), and the minus sign (-).

The * specifies that all messages for the specified facility are to be directed to the destination. Note that this behavior is degenerate with specifying a priority level of debug. Users have indicated that the asterisk notation is more intuitive.

The = wildcard is used to restrict logging to the specified priority class. This allows, for example, routing only debug messages to a particular logging source.

For example the following line in syslog.conf would direct debug messages from all sources to the /usr/adm/debug file.

```
	# Sample syslog.conf
	*.=debug			/usr/adm/debug
```

The ! is used to exclude logging of the specified priorities. This affects all (!) possibilities of specifying priorities.

For example the following lines would log all messages of the facility mail except those with the priority info to the /usr/adm/mail file. And all messages from news.info (including) to news.crit (excluding) would be logged to the /usr/adm/news file.

```
	# Sample syslog.conf
	mail.*;mail.!=info		/usr/adm/mail
	news.info;news.!crit	/usr/adm/news
```

You may use it intuitively as an exception specifier. The above mentioned interpretation is simply inverted. Doing that you may use

```
	mail.none
```

or

```
	mail.!*
```

or

```
	mail.!debug
```

to skip every message that comes with a mail facility. There is much room to play with it. :-)

The - may only be used to prefix a filename if you want to omit sync'ing the file after every write to it.

This may take some acclimatization for those individuals used to the pure BSD behavior but testers have indicated that this syntax is somewhat more flexible than the BSD behavior. Note that these changes should not affect standard syslog.conf(5) files. You must specifically modify the configuration files to obtain the enhanced behavior.

## SUPPORT FOR REMOTE LOGGING
These modifications provide network support to the syslogd facility. Network support means that messages can be forwarded from one node running syslogd to another node running syslogd where they will be actually logged to a disk file.

To enable this you have to specify the -r option on the command line. The default behavior is that syslogd won't listen to the network.

The strategy is to have syslogd listen on a unix domain socket for locally generated log messages. This behavior will allow syslogd to inter-operate with the syslog found in the standard C library. At the same time syslogd listens on the standard syslog port for messages forwarded from other hosts. To have this work correctly the services(5) files (typically found in /etc) must have the following entry:

```
	syslog          514/udp
```

If this entry is missing syslogd neither can receive remote messages nor send them, because the UDP port cant be opened. Instead syslogd will die immediately, blowing out an error message.

To cause messages to be forwarded to another host replace the normal file line in the syslog.conf file with the name of the host to which the messages is to be sent prepended with an @.

For example, to forward ALL messages to a remote host use the following syslog.conf entry:

```
	# Sample syslogd configuration file to
	# messages to a remote host forward all.
	*.*			@hostname
```

To forward all kernel messages to a remote host the configuration file would be as follows:

```
	# Sample configuration file to forward all kernel
	# messages to a remote host.
	kern.*		@hostname
```

If the remote hostname cannot be resolved at startup, because the name-server might not be accessible (it may be started after syslogd) you don't have to worry. Syslogd will retry to resolve the name ten times and then complain. Another possibility to avoid this is to place the hostname in /etc/hosts.

With normal syslogds you would get syslog-loops if you send out messages that were received from a remote host to the same host (or more complicated to a third host that sends it back to the first one, and so on). In my domain (Infodrom Oldenburg) we accidently got one and our disks filled up with the same single message. :-(

To avoid this no messages received from a remote host are sent out to another (or the same) remote host anymore. If you experience are setup in which you need this behaviour, please use the -h command line switch. However, this option needs to be handled with caution since a syslog loop can fill up hard disks quite fast.

If the remote host is located in the same domain as the host, syslogd is running on, only the simple hostname will be logged instead of the whole fqdn.

In a local network you may provide a central log server to have all the important information kept on one machine. If the network consists of different domains you don't have to complain about logging fully qualified names instead of simple hostnames. You may want to use the strip-domain feature -s of this server. You can tell the syslogd to strip off several domains other than the one the server is located in and only log simple hostnames.

Using the -l option there's also a possibility to define single hosts as local machines. This, too, results in logging only their simple hostnames and not the fqdns.

The UDP socket used to forward messages to remote hosts or to receive messages from them is only opened when it is needed. In releases prior to 1.3-23 it was opened every time but not opened for reading or forwarding respectively.

## OUTPUT TO NAMED PIPES (FIFOs)
This version of syslogd has support for logging output to named pipes (fifos). A fifo or named pipe can be used as a destination for log messages by prepending a pipy symbol (``|'') to the name of the file. This is handy for debugging. Note that the fifo must be created with the mkfifo command before syslogd is started.

The following configuration file routes debug messages from the kernel to a fifo:

```
	# Sample configuration to route kernel debugging
	# messages ONLY to /usr/adm/debug which is a
	# named pipe.
	kern.=debug			|/usr/adm/debug
```

## INSTALLATION CONCERNS
There is probably one important consideration when installing this version of syslogd. This version of syslogd is dependent on proper formatting of messages by the syslog function. The functioning of the syslog function in the shared libraries changed somewhere in the region of libc.so.4.[2-4].n. The specific change was to null-terminate the message before transmitting it to the /dev/log socket. Proper functioning of this version of syslogd is dependent on null-termination of the message.

This problem will typically manifest itself if old statically linked binaries are being used on the system. Binaries using old versions of the syslog function will cause empty lines to be logged followed by the message with the first character in the message removed. Relinking these binaries to newer versions of the shared libraries will correct this problem.

Both the syslogd(8) and the klogd(8) can either be run from init(8) or started as part of the rc.* sequence. If it is started from init the option -n must be set, otherwise you'll get tons of syslog daemons started. This is because init(8) depends on the process ID.

## SECURITY THREATS
There is the potential for the syslogd daemon to be used as a conduit for a denial of service attack. Thanks go to John Morrison (jmorriso@rflab.ee.ubc.ca) for alerting me to this potential. A rogue program(mer) could very easily flood the syslogd daemon with syslog messages resulting in the log files consuming all the remaining space on the filesystem. Activating logging over the inet domain sockets will of course expose a system to risks outside of programs or individuals on the local machine.

There are a number of methods of protecting a machine:

1.

Implement kernel firewalling to limit which hosts or networks have access to the 514/UDP socket.

2.

Logging can be directed to an isolated or non-root filesystem which, if filled, will not impair the machine.

3.

The ext2 filesystem can be used which can be configured to limit a certain percentage of a filesystem to usage by root only. NOTE that this will require syslogd to be run as a non-root process. ALSO NOTE that this will prevent usage of remote logging since syslogd will be unable to bind to the 514/UDP socket.

4.

Disabling inet domain sockets will limit risk to the local machine.

5.

Use step 4 and if the problem persists and is not secondary to a rogue program/daemon get a 3.5 ft (approx. 1 meter) length of sucker rod* and have a chat with the user in question. Sucker rod def. — 3/4, 7/8 or 1in. hardened steel rod, male threaded on each end. Primary use in the oil industry in Western North Dakota and other locations to pump 'suck' oil from oil wells. Secondary uses are for the construction of cattle feed lots and for dealing with the occasional recalcitrant or belligerent individual.

## DEBUGGING
When debugging is turned on using -d option then syslogd will be very verbose by writing much of what it does on stdout. Whenever the configuration file is reread and re-parsed you'll see a tabular, corresponding to the internal data structure. This tabular consists of four fields:

number

This field contains a serial number starting by zero. This number represents the position in the internal data structure (i.e. the array). If one number is left out then there might be an error in the corresponding line in /etc/syslog.conf.

pattern

This field is tricky and represents the internal structure exactly. Every column stands for a facility (refer to syslog(3)). As you can see, there are still some facilities left free for former use, only the left most are used. Every field in a column represents the priorities (refer to syslog(3)).

action

This field describes the particular action that takes place whenever a message is received that matches the pattern. Refer to the syslog.conf(5) manpage for all possible actions.

arguments

This field shows additional arguments to the actions in the last field. For file-logging this is the filename for the logfile; for user-logging this is a list of users; for remote logging this is the hostname of the machine to log to; for console-logging this is the used console; for tty-logging this is the specified tty; wall has no additional arguments.

## FILES
/etc/syslog.conf

Configuration file for syslogd. See syslog.conf(5) for exact information.

/dev/log

The Unix domain socket to from where local syslog messages are read.

/var/run/syslogd.pid

The file containing the process id of syslogd.

## BUGS
If an error occurs in one line the whole rule is ignored.

Syslogd doesn't change the filemode of opened logfiles at any stage of process. If a file is created it is world readable. If you want to avoid this, you have to create it and change permissions on your own. This could be done in combination with rotating logfiles using the savelog(8) program that is shipped in the smail 3.x distribution. Remember that it might be a security hole if everybody is able to read auth.* messages as these might contain passwords.

## SEE ALSO
syslog.conf(5), klogd(8), logger(1), syslog(2), syslog(3), services(5), savelog(8).

## AUTHORS
The system log daemon syslogd is originally taken from BSD sources, Greg Wettstein <greg@wind.enjellic.com> performed the port to Linux, Martin Schulze <joey@infodrom.org> fixed some bugs, added several new features and took over maintenance.


package: sysstat

title: sa1(8)

text:
# sa1(8)

## NAME
sa1 - Collect and store binary data in the system activity daily data file.

## SYNOPSIS
/usr/lib64/sa/sa1 [ --boot | --rotate [ iso ] | --sleep | interval count ]

## DESCRIPTION
The sa1 command is a shell procedure variant of the sadc command and handles all of the flags and parameters of that command. The sa1 command collects and stores binary data in the current standard system activity daily data file.

The standard system activity daily data file is named saDD unless sadc's option -D is used, in which case its name is saYYYYMMDD, where YYYY stands for the current year, MM for the current month and DD for the current day. By default it is located in the /var/log/sa directory.

The interval and count parameters specify that the record should be written count times at interval seconds. If no arguments are given to sa1 then a single record is written.

The sa1 command is designed to be started automatically by the cron command.

## OPTIONS
--boot

This option tells sa1 that the sadc command should be called without specifying the interval and count parameters in order to insert a dummy record, marking the time when the counters restart from 0.

--rotate [ iso ]

Use this option to tell sa1 to insert a record of statistics to the standard saDD system activity daily data file of the previous day. This should be done shortly after midnight (on day DD+1) in order to make sure that the data file covers the whole day, including the last interval of time just before midnight. Adding the iso keyword tells sa1 to use saYYYYMMDD instead of saDD as the standard system activity daily data file name.

--sleep

This option tells sa1 that the sadc command should insert a comment indicating that the system is entering or leaving sleep mode (i.e. system suspend or hibernation).

## EXAMPLE
To collect data (including those from disks) every 10 minutes, place the following entry in your root crontab file:

0,10,20,30,40,50 * * * * /usr/lib64/sa/sa1 1 1 -S DISK

To rotate current system activity daily data file, ensuring it is complete, place the following entry in your root crontab file:

0 0 * * * /usr/lib64/sa/sa1 --rotate

## FILES
/var/log/sa/saDD

/var/log/sa/saYYYYMMDD

The standard system activity daily data files and their default location. YYYY stands for the current year, MM for the current month and DD for the current day.

## AUTHOR
Sebastien Godard (sysstat <at> orange.fr)

## SEE ALSO
sar(1), sadc(8), sa2(8), sadf(1), sysstat(5)

https://github.com/sysstat/sysstat


title: sa2(8)

text:
# sa2(8)

## NAME
sa2 - Create a report from the current standard system activity daily data file.

## SYNOPSIS
/usr/lib64/sa/sa2

## DESCRIPTION
The sa2 command is a shell procedure variant of the sar command which writes a daily report in the sarDD or the sarYYYYMMDD file, where YYYY stands for the current year, MM for the current month and DD for the current day. By default the report is saved in the /var/log/sa directory. The sa2 command will also remove reports more than one week old by default. You can however keep reports for a longer (or a shorter) period by setting the HISTORY environment variable. Read the sysstat(5) manual page for details.

The sa2 command accepts most of the flags and parameters of the sar command.

The sa2 command is designed to be started automatically by the cron command.

## EXAMPLES
To run the sa2 command daily, place the following entry in your root crontab file:

5 19 * * 1-5 /usr/lib64/sa/sa2 -A

This will generate by default a daily report called sarDD in the /var/log/sa directory, where the DD parameter is a number representing the day of the month.

## FILES
/var/log/sa/sarDD

/var/log/sa/sarYYYYMMDD

The standard system activity daily report files and their default location. YYYY stands for the current year, MM for the current month and DD for the current day.

## AUTHOR
Sebastien Godard (sysstat <at> orange.fr)

## SEE ALSO
sar(1), sadc(8), sa1(8), sadf(1), sysstat(5)

https://github.com/sysstat/sysstat


sadc

title: sadc(8)

summary: System activity data collector.

text:
# sadc(8)

## NAME
sadc - System activity data collector.

## SYNOPSIS
/usr/lib64/sa/sadc [ -C comment ] [ -D ] [ -F ] [ -f ] [ -L ] [ -V ] [ -S { keyword[,...] | ALL | XALL } ] [ interval [ count ] ] [ outfile ]

## DESCRIPTION
The sadc command samples system data a specified number of times (count) at a specified interval measured in seconds (interval). It writes in binary format to the specified outfile or to standard output. If outfile is set to -, then sadc uses the standard system activity daily data file (see below). In this case, if the file already exists, sadc will overwrite it if it is from a previous month. By default sadc collects most of the data available from the kernel. But there are also optional metrics, for which the relevant options must be explicitly passed to sadc to be collected (see option -S below).

The standard system activity daily data file is named saDD unless option -D is used, in which case its name is saYYYYMMDD, where YYYY stands for the current year, MM for the current month and DD for the current day. By default it is located in the /var/log/sa directory. Yet it is possible to specify an alternate location for it: If outfile is a directory (instead of a plain file) then it will be considered as the directory where the standard system activity daily data file will be saved.

When the count parameter is not specified, sadc writes its data endlessly. When both interval and count are not specified, and option -C is not used, a dummy record, which is used at system startup to mark the time when the counter restarts from 0, will be written. For example, one of the system startup script may write the restart mark to the daily data file by the command entry:

/usr/lib64/sa/sadc -

The sadc command is intended to be used as a backend to the sar command.

Note: The sadc command only reports on local activities.

## OPTIONS
-C comment

When neither the interval nor the count parameters are specified, this option tells sadc to write a dummy record containing the specified comment string. This comment can then be displayed with option -C of sar.

-D

Use saYYYYMMDD instead of saDD as the standard system activity daily data file name.

-F

The creation of outfile will be forced. If the file already exists and has a format unknown to sadc then it will be truncated. This may be useful for daily data files created by an older version of sadc and whose format is no longer compatible with current one.

-f

fdatasync() will be used to ensure data is written to disk. This differs from the normal operation in that a sudden system reset is less likely to result in the saDD datafiles being corrupted. However, this is at the expense of performance within the sadc process as forward progress will be blocked while data is written to underlying disk instead of just to cache.

-L

sadc will try to get an exclusive lock on the outfile before writing to it or truncating it. Failure to get the lock is fatal, except in the case of trying to write a normal (i.e. not a dummy and not a header) record to an existing file, in which case sadc will try again at the next interval. Usually, the only reason a lock would fail would be if another sadc process were also writing to the file. This can happen when cron is used to launch sadc. If the system is under heavy load, an old sadc might still be running when cron starts a new one. Without locking, this situation can result in a corrupted system activity file.

-S { keyword[,...] | ALL | XALL }

Possible keywords are DISK, INT, IPV6, POWER, SNMP, XDISK, ALL and XALL.

Specify which optional activities should be collected by sadc. Some activities are optional to prevent data files from growing too large. The DISK keyword indicates that sadc should collect data for block devices. The INT keyword indicates that sadc should collect data for system interrupts. The IPV6 keyword indicates that IPv6 statistics should be collected by sadc. The POWER keyword indicates that sadc should collect power management statistics. The SNMP keyword indicates that SNMP statistics should be collected by sadc. The ALL keyword is equivalent to specifying all the keywords above and therefore all previous activities are collected.

The XDISK keyword is an extension to the DISK one and indicates that partitions and filesystems statistics should be collected by sadc in addition to disk statistics. This option works only with kernels 2.6.25 and later. The XALL keyword is equivalent to specifying all the keywords above (including keyword extensions) and therefore all possible activities are collected.

Important note: The activities (including optional ones) saved in an existing data file prevail over those selected with option -S. As a consequence, appending data to an existing data file will result in option -S being ignored.

-V

Print version number then exit.

## ENVIRONMENT
The sadc command takes into account the following environment variable:

S_TIME_DEF_TIME

If this variable exists and its value is UTC then sadc will save its data in UTC time. sadc will also use UTC time instead of local time to determine the current daily data file located in the /var/log/sa directory.

## EXAMPLES
/usr/lib64/sa/sadc 1 10 /tmp/datafile

Write 10 records of one second intervals to the /tmp/datafile binary file.

/usr/lib64/sa/sadc -C "Backup Start" /tmp/datafile

Insert the comment "Backup Start" into the file /tmp/datafile.

## BUGS
The /proc filesystem must be mounted for the sadc command to work.

All the statistics are not necessarily available, depending on the kernel version used. sadc assumes that you are using at least a 2.6 kernel.

## FILES
/var/log/sa/saDD

/var/log/sa/saYYYYMMDD

The standard system activity daily data files and their default location. YYYY stands for the current year, MM for the current month and DD for the current day.

/proc and /sys contain various files with system statistics.

## AUTHOR
Sebastien Godard (sysstat <at> orange.fr)

## SEE ALSO
sar(1), sa1(8), sa2(8), sadf(1), sysstat(5)

https://github.com/sysstat/sysstat


kernel-install

package: systemd

title: kernel-install(8)

text:
# kernel-install(8)

## NAME
kernel-install - Add and remove kernel and initramfs images to and from /boot

## SYNOPSIS
kernel-install COMMAND [OPTIONS...] KERNEL-VERSION KERNEL-IMAGE [INITRD-FILE...]

## DESCRIPTION
kernel-install is used to install and remove kernel and initramfs images to and from the boot loader partition, referred to as $BOOT here. It will usually be one of /boot/, /efi/, or /boot/efi/, see below.

kernel-install will execute the files located in the directory /usr/lib/kernel/install.d/ and the local administration directory /etc/kernel/install.d/. All files are collectively sorted and executed in lexical order, regardless of the directory in which they live. However, files with identical filenames replace each other. Files in /etc/kernel/install.d/ take precedence over files with the same name in /usr/lib/kernel/install.d/. This can be used to override a system-supplied executables with a local file if needed; a symbolic link in /etc/kernel/install.d/ with the same name as an executable in /usr/lib/kernel/install.d/, pointing to /dev/null, disables the executable entirely. Executables must have the extension ".install"; other extensions are ignored.

An executable should return 0 on success. It may also return 77 to cause the whole operation to terminate (executables later in lexical order will be skipped).

## COMMANDS
The following commands are understood:

add KERNEL-VERSION KERNEL-IMAGE [INITRD-FILE ...]

This command expects a kernel version string and a path to a kernel image file as arguments. kernel-install calls the executables from /usr/lib/kernel/install.d/*.install and /etc/kernel/install.d/*.install with the following arguments:

```
add KERNEL-VERSION $BOOT/MACHINE-ID/KERNEL-VERSION/ KERNEL-IMAGE [INITRD-FILE ...]
```

Three default plugins execute the following operations in this case:

•00-entry-directory.install creates the directory $BOOT/MACHINE-ID/KERNEL-VERSION/ if $BOOT/MACHINE-ID/ already exists.

•50-depmod.install runs depmod(8) for the KERNEL-VERSION.

•90-loaderentry.install copies KERNEL-IMAGE to $BOOT/MACHINE-ID/KERNEL-VERSION/linux. If an INITRD-FILE is provided, it also copies INITRD-FILE to $BOOT/MACHINE-ID/KERNEL_VERSION/INITRD-FILE. It also creates a boot loader entry according to the Boot Loader Specification[1] in $BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION.conf. The title of the entry is the PRETTY_NAME parameter specified in /etc/os-release or /usr/lib/os-release (if the former is missing), or "Linux KERNEL-VERSION", if unset. If the entry directory $BOOT/MACHINE-ID/KERNEL-VERSION/ does not exist, this plugin does nothing.

remove KERNEL-VERSION

This command expects a kernel version string as single argument. This calls executables from /usr/lib/kernel/install.d/*.install and /etc/kernel/install.d/*.install with the following arguments:

```
remove KERNEL-VERSION $BOOT/MACHINE-ID/KERNEL-VERSION/
```

Afterwards, kernel-install removes the directory $BOOT/MACHINE-ID/KERNEL-VERSION/ and its contents.

Two default plugins execute the following operations in this case:

•50-depmod.install removes the files generated by depmod for this kernel again.

•90-loaderentry.install removes the file $BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION.conf.

## THE $BOOT PARTITION
The partition where the kernels and Boot Loader Specification[1] snippets are located is called $BOOT. kernel-install determines the location of this partition by checking /efi/, /boot/, and /boot/efi/ in turn. The first location where $BOOT/loader/entries/ or $BOOT/$MACHINE_ID/ exists is used.

## OPTIONS
The following options are understood:

-v, --verbose

Output additional information about operations being performed.

-h, --help

Print a short help text and exit.

## ENVIRONMENT VARIABLES
If --verbose is used, $KERNEL_INSTALL_VERBOSE=1 will be set for the plugins. They may output additional logs in this case.

## EXIT STATUS
If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise.

## FILES
/usr/lib/kernel/install.d/*.install /etc/kernel/install.d/*.install

Drop-in files which are executed by kernel-install.

/etc/kernel/cmdline /proc/cmdline

Read by 90-loaderentry.install. The content of the file /etc/kernel/cmdline specifies the kernel command line to use. If that file does not exist, /proc/cmdline is used.

/etc/kernel/tries

Read by 90-loaderentry.install. If this file exists a numeric value is read from it and the naming of the generated entry file is slightly altered to include it as $BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION+TRIES.conf. This is useful for boot loaders such as systemd-boot(7) which implement boot attempt counting with a counter embedded in the entry file name.

/etc/machine-id

The content of this file specifies the machine identification MACHINE-ID. If it cannot read /etc/machine-id, kernel-install will use "Linux" as the machine ID instead.

/etc/os-release /usr/lib/os-release

The content of the file specifies the operating system title PRETTY_NAME.

## SEE ALSO
machine-id(5), os-release(5), depmod(8), systemd-boot(7), Boot Loader Specification[1]

## NOTES
1.

Boot Loader Specification

https://systemd.io/BOOT_LOADER_SPECIFICATION


systemd-ask-password

title: systemd-ask-password(8)

summary: Query the user for a system password

text:
# systemd-ask-password(8)

## NAME
systemd-ask-password - Query the user for a system password

## SYNOPSIS
systemd-ask-password [OPTIONS...] [MESSAGE]

## DESCRIPTION
systemd-ask-password may be used to query a system password or passphrase from the user, using a question message specified on the command line. When run from a TTY it will query a password on the TTY and print it to standard output. When run with no TTY or with --no-tty it will use the system-wide query mechanism, which allows active users to respond via several agents, listed below.

The purpose of this tool is to query system-wide passwords — that is passwords not attached to a specific user account. Examples include: unlocking encrypted hard disks when they are plugged in or at boot, entering an SSL certificate passphrase for web and VPN servers.

Existing agents are:

•A boot-time password agent asking the user for passwords using plymouth(8),

•A boot-time password agent querying the user directly on the console — systemd-ask-password-console.service(8),

•An agent requesting password input via a wall(1) message — systemd-ask-password-wall.service(8),

•A TTY agent that is temporarily spawned during systemctl(1) invocations,

•A command line agent which can be started temporarily to process queued password requests — systemd-tty-ask-password-agent --query.

Answering system-wide password queries is a privileged operation, hence all the agents listed above (except for the last one), run as privileged system services. The last one also needs elevated privileges, so should be run through sudo(8) or similar.

Additional password agents may be implemented according to the systemd Password Agent Specification[1].

If a password is queried on a TTY, the user may press TAB to hide the asterisks normally shown for each character typed. Pressing Backspace as first key achieves the same effect.

## OPTIONS
The following options are understood:

--icon=

Specify an icon name alongside the password query, which may be used in all agents supporting graphical display. The icon name should follow the XDG Icon Naming Specification[2].

--id=

Specify an identifier for this password query. This identifier is freely choosable and allows recognition of queries by involved agents. It should include the subsystem doing the query and the specific object the query is done for. Example: "--id=cryptsetup:/dev/sda5".

--keyname=

Configure a kernel keyring key name to use as cache for the password. If set, then the tool will try to push any collected passwords into the kernel keyring of the root user, as a key of the specified name. If combined with --accept-cached, it will also try to retrieve such cached passwords from the key in the kernel keyring instead of querying the user right away. By using this option, the kernel keyring may be used as effective cache to avoid repeatedly asking users for passwords, if there are multiple objects that may be unlocked with the same password. The cached key will have a timeout of 2.5min set, after which it will be purged from the kernel keyring. Note that it is possible to cache multiple passwords under the same keyname, in which case they will be stored as NUL-separated list of passwords. Use keyctl(1) to access the cached key via the kernel keyring directly. Example: "--keyname=cryptsetup"

--credential=

Configure a credential to read the password from – if it exists. This may be used in conjunction with the LoadCredential= and SetCredential= settings in unit files. See systemd.exec(5) for details. If not specified, defaults to "password". This option has no effect if no credentials directory is passed to the program (i.e. $CREDENTIALS_DIRECTORY is not set) or if the no credential of the specified name exists.

--timeout=

Specify the query timeout in seconds. Defaults to 90s. A timeout of 0 waits indefinitely.

--echo=yes|no|masked

Controls whether to echo user input. Takes a boolean or the special string "masked", the default being the latter. If enabled the typed characters are echoed literally, which is useful for prompting for usernames and other non-protected data. If disabled the typed characters are not echoed in any form, the user will not get feedback on their input. If set to "masked", an asterisk ("*") is echoed for each character typed. In this mode, if the user hits the tabulator key ("↹"), echo is turned off. (Alternatively, if the user hits the backspace key ("⌫") while no data has been entered otherwise, echo is turned off, too).

--echo, -e

Equivalent to --echo=yes, see above.

--emoji=yes|no|auto

Controls whether or not to prefix the query with a lock and key emoji (🔐), if the TTY settings permit this. The default is "auto", which defaults to "yes", unless --echo=yes is given.

--no-tty

Never ask for password on current TTY even if one is available. Always use agent system.

--accept-cached

If passed, accept cached passwords, i.e. passwords previously entered.

--multiple

When used in conjunction with --accept-cached accept multiple passwords. This will output one password per line.

--no-output

Do not print passwords to standard output. This is useful if you want to store a password in kernel keyring with --keyname= but do not want it to show up on screen or in logs.

-n

By default, when writing the acquired password to standard output it is suffixed by a newline character. This may be turned off with the -n switch, similar to the switch of the same name of the echo(1) command.

-h, --help

Print a short help text and exit.

## EXIT STATUS
On success, 0 is returned, a non-zero failure code otherwise.

## SEE ALSO
systemd(1), systemd-ask-password-console.service(8), systemd-tty-ask-password-agent(8), keyctl(1), plymouth(8), wall(1)

## NOTES
1.

systemd Password Agent Specification

https://systemd.io/PASSWORD_AGENTS/

2.

XDG Icon Naming Specification

http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html


systemd-ask-password-console.service

title: systemd-ask-password-console.service(8)

text:
# systemd-ask-password-console.service(8)

## NAME
systemd-ask-password-console.service, systemd-ask-password-console.path, systemd-ask-password-wall.service, systemd-ask-password-wall.path - Query the user for system passwords on the console and via wall

## SYNOPSIS
systemd-ask-password-console.service

systemd-ask-password-console.path

systemd-ask-password-wall.service

systemd-ask-password-wall.path

## DESCRIPTION
systemd-ask-password-console.service is a system service that queries the user for system passwords (such as hard disk encryption keys and SSL certificate passphrases) on the console. It is intended to be used during boot to ensure proper handling of passwords necessary for boot. systemd-ask-password-wall.service is a system service that informs all logged in users for system passwords via wall(1). It is intended to be used after boot to ensure that users are properly notified.

See the developer documentation[1] for more information about the system password logic.

Note that these services invoke systemd-tty-ask-password-agent(8) with either the --watch --console or --watch --wall command line parameters.

## SEE ALSO
systemd(1), systemd-tty-ask-password-agent(8), wall(1)

## NOTES
1.

developer documentation

https://systemd.io/PASSWORD_AGENTS/


systemd-backlight@.service

title: systemd-backlight@.service(8)

text:
# systemd-backlight@.service(8)

## NAME
systemd-backlight@.service, systemd-backlight - Load and save the display backlight brightness at boot and shutdown

## SYNOPSIS
systemd-backlight@.service

/lib/systemd/systemd-backlight save [backlight|leds]:DEVICE

/lib/systemd/systemd-backlight load [backlight|leds]:DEVICE

## DESCRIPTION
systemd-backlight@.service is a service that restores the display backlight brightness at early boot and saves it at shutdown. On disk, the backlight brightness is stored in /var/lib/systemd/backlight/. During loading, if the udev property ID_BACKLIGHT_CLAMP is not set to false, the brightness is clamped to a value of at least 1 or 5% of maximum brightness, whichever is greater. This restriction will be removed when the kernel allows user space to reliably set a brightness value which does not turn off the display.

## KERNEL COMMAND LINE
systemd-backlight understands the following kernel command line parameter:

systemd.restore_state=

Takes a boolean argument. Defaults to "1". If "0", does not restore the backlight settings on boot. However, settings will still be stored on shutdown.

## SEE ALSO
systemd(1)


systemd-binfmt.service

title: systemd-binfmt.service(8)

text:
# systemd-binfmt.service(8)

## NAME
systemd-binfmt.service, systemd-binfmt - Configure additional binary formats for executables at boot

## SYNOPSIS
systemd-binfmt.service

/lib/systemd/systemd-binfmt

## DESCRIPTION
systemd-binfmt.service is an early boot service that registers additional binary formats for executables in the kernel.

See binfmt.d(5) for information about the configuration of this service.

## OPTIONS
--unregister

If passed, instead of registering configured binary formats in the kernel, the reverse operation is executed: all currently registered binary formats are unregistered from the kernel.

--cat-config

Copy the contents of config files to standard output. Before each file, the filename is printed as a comment.

--no-pager

Do not pipe output into a pager.

-h, --help

Print a short help text and exit.

--version

Print a short version string and exit.

## SEE ALSO
systemd(1), binfmt.d(5), wine(8)


systemd-cryptsetup-generator

title: systemd-cryptsetup-generator(8)

summary: Unit generator for /etc/crypttab

text:
# systemd-cryptsetup-generator(8)

## NAME
systemd-cryptsetup-generator - Unit generator for /etc/crypttab

## SYNOPSIS
/lib/systemd/system-generators/systemd-cryptsetup-generator

## DESCRIPTION
systemd-cryptsetup-generator is a generator that translates /etc/crypttab into native systemd units early at boot and when configuration of the system manager is reloaded. This will create systemd-cryptsetup@.service(8) units as necessary.

systemd-cryptsetup-generator implements systemd.generator(7).

## KERNEL COMMAND LINE
systemd-cryptsetup-generator understands the following kernel command line parameters:

luks=, rd.luks=

Takes a boolean argument. Defaults to "yes". If "no", disables the generator entirely. rd.luks= is honored only by initial RAM disk (initrd) while luks= is honored by both the main system and the initrd.

luks.crypttab=, rd.luks.crypttab=

Takes a boolean argument. Defaults to "yes". If "no", causes the generator to ignore any devices configured in /etc/crypttab (luks.uuid= will still work however). rd.luks.crypttab= is honored only by initial RAM disk (initrd) while luks.crypttab= is honored by both the main system and the initrd.

luks.uuid=, rd.luks.uuid=

Takes a LUKS superblock UUID as argument. This will activate the specified device as part of the boot process as if it was listed in /etc/crypttab. This option may be specified more than once in order to set up multiple devices. rd.luks.uuid= is honored only by initial RAM disk (initrd) while luks.uuid= is honored by both the main system and the initrd. If /etc/crypttab contains entries with the same UUID, then the name, keyfile and options specified there will be used. Otherwise, the device will have the name "luks-UUID".

If /etc/crypttab exists, only those UUIDs specified on the kernel command line will be activated in the initrd or the real root.

luks.name=, rd.luks.name=

Takes a LUKS super block UUID followed by an "=" and a name. This implies rd.luks.uuid= or luks.uuid= and will additionally make the LUKS device given by the UUID appear under the provided name. This parameter is the analogue of the first crypttab(5) field volume-name.

rd.luks.name= is honored only by initial RAM disk (initrd) while luks.name= is honored by both the main system and the initrd.

luks.data=, rd.luks.data=

Takes a LUKS super block UUID followed by a "=" and a block device specification for device hosting encrypted data. For those entries specified with rd.luks.uuid= or luks.uuid=, the data device will be set to the one specified by rd.luks.data= or luks.data= of the corresponding UUID.

LUKS data device parameter is useful for specifying encrypted data devices with detached headers specified in luks.options entry containing "header=" argument. For example, rd.luks.uuid=b40f1abf-2a53-400a-889a-2eccc27eaa40 rd.luks.options=b40f1abf-2a53-400a-889a-2eccc27eaa40=header=/path/to/luks.hdr rd.luks.data=b40f1abf-2a53-400a-889a-2eccc27eaa40=/dev/sdx. Hence, in this case, we will attempt to unlock LUKS device assembled from data device "/dev/sdx" and LUKS header (metadata) put in "/path/to/luks.hdr" file. This syntax is for now only supported on a per-device basis, i.e. you have to specify LUKS device UUID.

This parameter is the analogue of the second crypttab(5) field encrypted-device.

rd.luks.data= is honored only by initial RAM disk (initrd) while luks.data= is honored by both the main system and the initrd.

luks.key=, rd.luks.key=

Takes a password file name as argument or a LUKS super block UUID followed by a "=" and a password file name. For those entries specified with rd.luks.uuid= or luks.uuid=, the password file will be set to the one specified by rd.luks.key= or luks.key= of the corresponding UUID, or the password file that was specified without a UUID.

It is also possible to specify an external device which should be mounted before we attempt to unlock the LUKS device. systemd-cryptsetup will use password file stored on that device. Device containing password file is specified by appending colon and a device identifier to the password file path. For example, rd.luks.uuid=b40f1abf-2a53-400a-889a-2eccc27eaa40 rd.luks.key=b40f1abf-2a53-400a-889a-2eccc27eaa40=/keyfile:LABEL=keydev. Hence, in this case, we will attempt to mount file system residing on the block device with label "keydev". This syntax is for now only supported on a per-device basis, i.e. you have to specify LUKS device UUID.

This parameter is the analogue of the third crypttab(5) field key-file.

rd.luks.key= is honored only by initial RAM disk (initrd) while luks.key= is honored by both the main system and the initrd.

luks.options=, rd.luks.options=

Takes a LUKS super block UUID followed by an "=" and a string of options separated by commas as argument. This will override the options for the given UUID. If only a list of options, without an UUID, is specified, they apply to any UUIDs not specified elsewhere, and without an entry in /etc/crypttab.

This parameter is the analogue of the fourth crypttab(5) field options.

It is possible to specify an external device which should be mounted before we attempt to unlock the LUKS device. systemd-cryptsetup will assemble LUKS device by combining data device specified in luks.data with detached LUKS header found in "header=" argument. For example, rd.luks.uuid=b40f1abf-2a53-400a-889a-2eccc27eaa40 rd.luks.options=b40f1abf-2a53-400a-889a-2eccc27eaa40=header=/luks.hdr:LABEL=hdrdev rd.luks.data=b40f1abf-2a53-400a-889a-2eccc27eaa40=/dev/sdx. Hence, in this case, we will attempt to mount file system residing on the block device with label "hdrdev", and look for "luks.hdr" on that file system. Said header will be used to unlock (decrypt) encrypted data stored on /dev/sdx. This syntax is for now only supported on a per-device basis, i.e. you have to specify LUKS device UUID.

rd.luks.options= is honored only by initial RAM disk (initrd) while luks.options= is honored by both the main system and the initrd.

## SEE ALSO
systemd(1), crypttab(5), systemd-cryptsetup@.service(8), systemd-cryptenroll(1), cryptsetup(8), systemd-fstab-generator(8)


systemd-cryptsetup@.service

title: systemd-cryptsetup@.service(8)

summary: Full disk decryption logic

text:
# systemd-cryptsetup@.service(8)

## NAME
systemd-cryptsetup@.service, systemd-cryptsetup - Full disk decryption logic

## SYNOPSIS
systemd-cryptsetup@.service

system-systemd\x2dcryptsetup.slice

/lib/systemd/systemd-cryptsetup

## DESCRIPTION
systemd-cryptsetup@.service is a service responsible for setting up encrypted block devices. It is instantiated for each device that requires decryption for access.

systemd-cryptsetup@.service instances are part of the system-systemd\x2dcryptsetup.slice slice, which is destroyed only very late in the shutdown procedure. This allows the encrypted devices to remain up until filesystems have been unmounted.

systemd-cryptsetup@.service will ask for hard disk passwords via the password agent logic[1], in order to query the user for the password using the right mechanism at boot and during runtime.

At early boot and when the system manager configuration is reloaded, /etc/crypttab is translated into systemd-cryptsetup@.service units by systemd-cryptsetup-generator(8).

In order to unlock a volume a password or binary key is required. systemd-cryptsetup@.service tries to acquire a suitable password or binary key via the following mechanisms, tried in order:

1.If a key file is explicitly configured (via the third column in /etc/crypttab), a key read from it is used. If a PKCS#11 token, FIDO2 token or TPM2 device is configured (using the pkcs11-uri=, fido2-device=, tpm2-device= options) the key is decrypted before use.

2.If no key file is configured explicitly this way, a key file is automatically loaded from /etc/cryptsetup-keys.d/volume.key and /run/cryptsetup-keys.d/volume.key, if present. Here too, if a PKCS#11/FIDO2/TPM2 token/device is configured, any key found this way is decrypted before use.

3.If the try-empty-password option is specified it is then attempted to unlock the volume with an empty password.

4.The kernel keyring is then checked for a suitable cached password from previous attempts.

5.Finally, the user is queried for a password, possibly multiple times, unless the headless option is set.

If no suitable key may be acquired via any of the mechanisms describes above, volume activation fails.

## SEE ALSO
systemd(1), systemd-cryptsetup-generator(8), crypttab(5), systemd-cryptenroll(1), cryptsetup(8)

## NOTES
1.

password agent logic

https://systemd.io/PASSWORD_AGENTS/


systemd-debug-generator

title: systemd-debug-generator(8)

text:
# systemd-debug-generator(8)

## NAME
systemd-debug-generator - Generator for enabling a runtime debug shell and masking specific units at boot

## SYNOPSIS
/lib/systemd/system-generators/systemd-debug-generator

## DESCRIPTION
systemd-debug-generator is a generator that reads the kernel command line and understands three options:

If the systemd.mask= or rd.systemd.mask= option is specified and followed by a unit name, this unit is masked for the runtime, similar to the effect of systemctl(1)'s mask command. This is useful to boot with certain units removed from the initial boot transaction for debugging system startup. May be specified more than once. rd.systemd.mask= is honored only by initial RAM disk (initrd) while systemd.mask= is honored only in the main system.

If the systemd.wants= or rd.systemd.wants= option is specified and followed by a unit name, a start job for this unit is added to the initial transaction. This is useful to start one or more additional units at boot. May be specified more than once. rd.systemd.wants= is honored only by initial RAM disk (initrd) while systemd.wants= is honored only in the main system.

If the systemd.debug_shell or rd.systemd.debug_shell option is specified, the debug shell service "debug-shell.service" is pulled into the boot transaction and a debug shell will be spawned during early boot. By default, /dev/tty9 is used, but a specific tty can also be set, either with or without the /dev/ prefix. Note that the shell may also be turned on persistently by enabling it with systemctl(1)'s enable command. rd.systemd.debug_shell= is honored only by initial RAM disk (initrd) while systemd.debug_shell is honored only in the main system.

systemd-debug-generator implements systemd.generator(7).

## SEE ALSO
systemd(1), systemctl(1), kernel-command-line(7)


systemd-environment-d-generator

title: systemd-environment-d-generator(8)

text:
# systemd-environment-d-generator(8)

## NAME
systemd-environment-d-generator, 30-systemd-environment-d-generator - Load variables specified by environment.d

## SYNOPSIS
/usr/lib/systemd/user-environment-generators/30-systemd-environment-d-generator

## DESCRIPTION
systemd-environment-d-generator is a systemd.environment-generator(7) that reads environment configuration specified by environment.d(5) configuration files and passes it to the systemd(1) user manager instance.

## SEE ALSO
systemd(1), systemctl(1), systemd.environment-generator(7), systemd.generator(7)


systemd-fsck@.service

title: systemd-fsck@.service(8)

summary: File system checker logic

text:
# systemd-fsck@.service(8)

## NAME
systemd-fsck@.service, systemd-fsck-root.service, systemd-fsck - File system checker logic

## SYNOPSIS
systemd-fsck@.service

systemd-fsck-root.service

/lib/systemd/systemd-fsck

## DESCRIPTION
systemd-fsck@.service and systemd-fsck-root.service are services responsible for file system checks. They are instantiated for each device that is configured for file system checking. systemd-fsck-root.service is responsible for file system checks on the root file system, but only if the root filesystem was not checked in the initramfs. systemd-fsck@.service is used for all other file systems and for the root file system in the initramfs.

These services are started at boot if passno in /etc/fstab for the file system is set to a value greater than zero. The file system check for root is performed before the other file systems. Other file systems may be checked in parallel, except when they are on the same rotating disk.

systemd-fsck does not know any details about specific filesystems, and simply executes file system checkers specific to each filesystem type (/sbin/fsck.type). These checkers will decide if the filesystem should actually be checked based on the time since last check, number of mounts, unclean unmount, etc.

If a file system check fails for a service without nofail, emergency mode is activated, by isolating to emergency.target.

## KERNEL COMMAND LINE
systemd-fsck understands these kernel command line parameters:

fsck.mode=

One of "auto", "force", "skip". Controls the mode of operation. The default is "auto", and ensures that file system checks are done when the file system checker deems them necessary. "force" unconditionally results in full file system checks. "skip" skips any file system checks.

fsck.repair=

One of "preen", "yes", "no". Controls the mode of operation. The default is "preen", and will automatically repair problems that can be safely fixed. "yes" will answer yes to all questions by fsck and "no" will answer no to all questions.

## SEE ALSO
systemd(1), fsck(8), systemd-quotacheck.service(8), fsck.btrfs(8), fsck.cramfs(8), fsck.ext4(8), fsck.fat(8), fsck.hfsplus(8), fsck.minix(8), fsck.ntfs(8), fsck.xfs(8)


systemd-fstab-generator

title: systemd-fstab-generator(8)

summary: Unit generator for /etc/fstab

text:
# systemd-fstab-generator(8)

## NAME
systemd-fstab-generator - Unit generator for /etc/fstab

## SYNOPSIS
/lib/systemd/system-generators/systemd-fstab-generator

## DESCRIPTION
systemd-fstab-generator is a generator that translates /etc/fstab (see fstab(5) for details) into native systemd units early at boot and when configuration of the system manager is reloaded. This will instantiate mount and swap units as necessary.

The passno field is treated like a simple boolean, and the ordering information is discarded. However, if the root file system is checked, it is checked before all the other file systems.

See systemd.mount(5) and systemd.swap(5) for more information about special /etc/fstab mount options this generator understands.

One special topic is handling of symbolic links. Historical init implementations supported symlinks in /etc/fstab. Because mount units will refuse mounts where the target is a symbolic link, this generator will resolve any symlinks as far as possible when processing /etc/fstab in order to enhance backwards compatibility. If a symlink target does not exist at the time that this generator runs, it is assumed that the symlink target is the final target of the mount.

systemd-fstab-generator implements systemd.generator(7).

## KERNEL COMMAND LINE
systemd-fstab-generator understands the following kernel command line parameters:

fstab=, rd.fstab=

Takes a boolean argument. Defaults to "yes". If "no", causes the generator to ignore any mounts or swap devices configured in /etc/fstab. rd.fstab= is honored only by the initial RAM disk (initrd) while fstab= is honored by both the main system and the initrd.

root=

Configures the operating system's root filesystem to mount when running in the initrd. This accepts a device node path (usually /dev/disk/by-uuid/... or /dev/disk/by-label/... or similar), or the special values "gpt-auto" and "tmpfs". Use "gpt-auto" to explicitly request automatic root file system discovery via systemd-gpt-auto-generator(8).

Use "tmpfs" in order to mount a tmpfs(5) file system as root file system of the OS. This is useful in combination with mount.usr= (see below) in order to combine a volatile root file system with a separate, immutable /usr/ file system. Also see systemd.volatile= below.

rootfstype=

Takes the root filesystem type that will be passed to the mount command. rootfstype= is honored by the initrd.

rootflags=

Takes the root filesystem mount options to use. rootflags= is honored by the initrd. Note that unlike most kernel command line options this setting does not override settings made in configuration files (specifically: the mount option string in /etc/fstab). See systemd-remount-fs.service(8).

mount.usr=

Takes the /usr/ filesystem to be mounted by the initrd. If mount.usrfstype= or mount.usrflags= is set, then mount.usr= will default to the value set in root=. Otherwise, this parameter defaults to the /usr/ entry found in /etc/fstab on the root filesystem.

mount.usr= is honored by the initrd.

mount.usrfstype=

Takes the /usr/ filesystem type that will be passed to the mount command. If mount.usr= or mount.usrflags= is set, then mount.usrfstype= will default to the value set in rootfstype=. Otherwise, this value will be read from the /usr/ entry in /etc/fstab on the root filesystem.

mount.usrfstype= is honored by the initrd.

mount.usrflags=

Takes the /usr/ filesystem mount options to use. If mount.usr= or mount.usrfstype= is set, then mount.usrflags= will default to the value set in rootflags=. Otherwise, this value will be read from the /usr/ entry in /etc/fstab on the root filesystem.

mount.usrflags= is honored by the initrd.

systemd.volatile=

Controls whether the system shall boot up in volatile mode. Takes a boolean argument or the special value state. If false (the default), this generator makes no changes to the mount tree and the system is booted up in normal mode.

If true the generator ensures systemd-volatile-root.service(8) is run as part of the initial RAM disk ("initrd"). This service changes the mount table before transitioning to the host system, so that a volatile memory file system ("tmpfs") is used as root directory, with only /usr/ mounted into it from the configured root file system, in read-only mode. This way the system operates in fully stateless mode, with all configuration and state reset at boot and lost at shutdown, as /etc/ and /var/ will be served from the (initially unpopulated) volatile memory file system.

If set to state the generator will leave the root directory mount point unaltered, however will mount a "tmpfs" file system to /var/. In this mode the normal system configuration (i.e. the contents of "/etc/") is in effect (and may be modified during system runtime), however the system state (i.e. the contents of "/var/") is reset at boot and lost at shutdown.

If this setting is set to "overlay" the root file system is set up as "overlayfs" mount combining the read-only root directory with a writable "tmpfs", so that no modifications are made to disk, but the file system may be modified nonetheless with all changes being lost at reboot.

Note that in none of these modes the root directory, /etc/, /var/ or any other resources stored in the root file system are physically removed. It's thus safe to boot a system that is normally operated in non-volatile mode temporarily into volatile mode, without losing data.

Note that with the exception of "overlay" mode, enabling this setting will only work correctly on operating systems that can boot up with only /usr/ mounted, and are able to automatically populate /etc/, and also /var/ in case of "systemd.volatile=yes".

Also see root=tmpfs above, for a method to combine a "tmpfs" file system with a regular /usr/ file system (as configured via mount.usr=). The main distinction between systemd.volatile=yes, and root=tmpfs in combination mount.usr= is that the former operates on top of a regular root file system and temporarily obstructs the files and directories above its /usr/ subdirectory, while the latter does not hide any files, but simply mounts a unpopulated tmpfs as root file system and combines it with a user picked /usr/ file system.

systemd.swap

Takes a boolean argument or enables the option if specified without an argument. If disabled, causes the generator to ignore any swap devices configured in /etc/fstab. Defaults to enabled.

## SEE ALSO
systemd(1), fstab(5), systemd.mount(5), systemd.swap(5), systemd-cryptsetup-generator(8), systemd-gpt-auto-generator(8), kernel-command-line(7)


systemd-getty-generator

title: systemd-getty-generator(8)

text:
# systemd-getty-generator(8)

## NAME
systemd-getty-generator - Generator for enabling getty instances on the console

## SYNOPSIS
/lib/systemd/system-generators/systemd-getty-generator

## DESCRIPTION
systemd-getty-generator is a generator that automatically instantiates serial-getty@.service on the kernel console(s), if they can function as ttys and are not provided by the virtual console subsystem. It will also instantiate serial-getty@.service instances for virtualizer consoles, if execution in a virtualized environment is detected. If execution in a container environment is detected, it will instead enable console-getty.service for /dev/console, and container-getty@.service instances for additional container pseudo TTYs as requested by the container manager (see Container Interface[1]). This should ensure that the user is shown a login prompt at the right place, regardless of which environment the system is started in. For example, it is sufficient to redirect the kernel console with a kernel command line argument such as console= to get both kernel messages and a getty prompt on a serial TTY. See kernel-parameters.txt[2] for more information on the console= kernel parameter.

systemd-getty-generator implements systemd.generator(7).

Further information about configuration of gettys can be found in systemd for Administrators, Part XVI: Gettys on Serial Consoles (and Elsewhere)[3].

## SEE ALSO
systemd(1), agetty(8)

## NOTES
1.

Container

Interface

https://systemd.io/CONTAINER_INTERFACE

2.

kernel-parameters.txt

https://www.kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt

3.

systemd for Administrators, Part XVI: Gettys on Serial Consoles (and Elsewhere)

http://0pointer.de/blog/projects/serial-console.html


systemd-gpt-auto-generator

title: systemd-gpt-auto-generator(8)

text:
# systemd-gpt-auto-generator(8)

## NAME
systemd-gpt-auto-generator - Generator for automatically discovering and mounting root, /home/, /srv/, /var/ and /var/tmp/ partitions, as well as discovering and enabling swap partitions, based on GPT partition type GUIDs

## SYNOPSIS
/lib/systemd/system-generators/systemd-gpt-auto-generator

## DESCRIPTION
systemd-gpt-auto-generator is a unit generator that automatically discovers root, /home/, /srv/, /var/, /var/tmp/, the EFI System Partition, the Extended Boot Loader Partition and swap partitions and creates mount and swap units for them, based on the partition type GUIDs of GUID partition tables (GPT), see UEFI Specification[1], chapter 5. It implements the Discoverable Partitions Specification[2]. Note that this generator has no effect on non-GPT systems, and on specific mount points that are directories already containing files. Also, on systems where the units are explicitly configured (for example, listed in fstab(5)), the units this generator creates are overridden, but additional implicit dependencies might be created.

This generator will only look for the root partition on the same physical disk the EFI System Partition (ESP) is located on. Note that support from the boot loader is required: the EFI variable LoaderDevicePartUUID of the 4a67b082-0a4c-41cf-b6c7-440b29bb8c4f vendor UUID is used to determine from which partition, and hence the disk from which the system was booted. If the boot loader does not set this variable, this generator will not be able to autodetect the root partition. See the Boot Loader Interface[3] for details.

Similarly, this generator will only look for the other partitions on the same physical disk as the root partition. In this case, boot loader support is not required. These partitions will not be searched for on systems where the root file system is distributed on multiple disks, for example via btrfs RAID.

systemd-gpt-auto-generator is useful for centralizing file system configuration in the partition table and making configuration in /etc/fstab or on the kernel command line unnecessary.

This generator looks for the partitions based on their partition type GUID. The following partition type GUIDs are identified:

Table 1. Partition Type GUIDs

Partition Type GUID

Name

Mount Point

Explanation

44479540-f297-41b2-9af7-d131d5f0458a

Root Partition (x86)

/

On 32-bit x86 systems, the first x86 root partition on the disk the EFI ESP is located on is mounted to the root directory /.

4f68bce3-e8cd-4db1-96e7-fbcaf984b709

Root Partition (x86-64)

/

On 64-bit x86 systems, the first x86-64 root partition on the disk the EFI ESP is located on is mounted to the root directory /.

69dad710-2ce4-4e3c-b16c-21a1d49abed3

Root Partition (32-bit ARM)

/

On 32-bit ARM systems, the first ARM root partition on the disk the EFI ESP is located on is mounted to the root directory /.

b921b045-1df0-41c3-af44-4c6f280d3fae

Root Partition (64-bit ARM)

/

On 64-bit ARM systems, the first ARM root partition on the disk the EFI ESP is located on is mounted to the root directory /.

993d8d3d-f80e-4225-855a-9daf8ed7ea97

Root Partition (Itanium/IA-64)

/

On Itanium systems, the first Itanium root partition on the disk the EFI ESP is located on is mounted to the root directory /.

60d5a7fe-8e7d-435c-b714-3dd8162144e1

Root Partition (RISCV-V 32)

/

On RISC-V 32-bit systems, the first RISCV-V 32-bit root partition on the disk the EFI ESP is located on is mounted to the root directory /.

72ec70a6-cf74-40e6-bd49-4bda08e8f224

Root Partition (RISCV-V 64)

/

On RISC-V 64-bit systems, the first RISCV-V 64-bit root partition on the disk the EFI ESP is located on is mounted to the root directory /.

933ac7e1-2eb4-4f13-b844-0e14e2aef915

Home Partition

/home/

The first home partition on the disk the root partition is located on is mounted to /home/.

3b8f8425-20e0-4f3b-907f-1a25a76f98e8

Server Data Partition

/srv/

The first server data partition on the disk the root partition is located on is mounted to /srv/.

4d21b016-b534-45c2-a9fb-5c16e091fd2d

Variable Data Partition

/var/

The first variable data partition on the disk the root partition is located on is mounted to /var/ — under the condition its partition UUID matches the first 128 bit of the HMAC-SHA256 of the GPT type uuid of this partition keyed by the machine ID of the installation stored in machine-id(5).

7ec6f557-3bc5-4aca-b293-16ef5df639d1

Temporary Data Partition

/var/tmp/

The first temporary data partition on the disk the root partition is located on is mounted to /var/tmp/.

0657fd6d-a4ab-43c4-84e5-0933c84b4f4f

Swap

n/a

All swap partitions located on the disk the root partition is located on are enabled.

c12a7328-f81f-11d2-ba4b-00a0c93ec93b

EFI System Partition (ESP)

/efi/ or /boot/

The first ESP located on the disk the root partition is located on is mounted to /boot/ or /efi/, see below.

bc13c2ff-59e6-4262-a352-b275fd6f7172

Extended Boot Loader Partition

/boot/

The first Extended Boot Loader Partition is mounted to /boot/, see below.

This generator understands the following attribute flags for partitions:

Table 2. Partition Attributes

Name

Value

Applicable to

Explanation

GPT_FLAG_READ_ONLY

0x1000000000000000

/, /home/, /srv/, /var/, /var/tmp/, Extended Boot Loader Partition

Partition is mounted read-only

GPT_FLAG_NO_AUTO

0x8000000000000000

/, /home/, /srv/, /var/, /var/tmp/, Extended Boot Loader Partition

Partition is not mounted automatically

GPT_FLAG_NO_BLOCK_IO_PROTOCOL

0x0000000000000002

EFI System Partition (ESP)

Partition is not mounted automatically

The

/home/, /srv/, /var/ and /var/tmp/ partitions may be encrypted in LUKS format. In this case, a device mapper device is set up under the names /dev/mapper/home, /dev/mapper/srv, /dev/mapper/var and /dev/mapper/tmp. Note that this might create conflicts if the same partition is listed in /etc/crypttab with a different device mapper device name.

When systemd is running in the initrd the / partition may be encrypted in LUKS format as well. In this case, a device mapper device is set up under the name /dev/mapper/root, and a sysroot.mount is set up that mounts the device under /sysroot. For more information, see bootup(7).

Mount and automount units for the EFI System Partition (ESP) are generated on EFI systems. The ESP is mounted to /boot/ (except if an Extended Boot Loader partition exists, see below), unless a mount point directory /efi/ exists, in which case it is mounted there. Since this generator creates an automount unit, the mount will only be activated on-demand, when accessed. On systems where /boot/ (or /efi/ if it exists) is an explicitly configured mount (for example, listed in fstab(5)) or where the /boot/ (or /efi/) mount point is non-empty, no mount units are generated.

If the disk contains an Extended Boot Loader partition, as defined in the Boot Loader Specification[4], it is made available at /boot/ (by means of an automount point, similar to the ESP, see above). If both an EFI System Partition and an Extended Boot Loader partition exist the latter is preferably mounted to /boot/. Make sure to create both /efi/ and /boot/ to ensure both partitions are mounted.

When using this generator in conjunction with btrfs file systems, make sure to set the correct default subvolumes on them, using btrfs subvolume set-default.

systemd-gpt-auto-generator implements systemd.generator(7).

## KERNEL COMMAND LINE
systemd-gpt-auto-generator understands the following kernel command line parameters:

systemd.gpt_auto, rd.systemd.gpt_auto

Those options take an optional boolean argument, and default to yes. The generator is enabled by default, and a negative value may be used to disable it.

root=

When used with the special value "gpt-auto", automatic discovery of the root partition based on the GPT partition type is enabled. Any other value disables this generator.

rw, ro

Mount the root partition read-write or read-only initially. Note that unlike most kernel command line options these settings do not override configuration in the file system, and the file system may be remounted later. See systemd-remount-fs.service(8).

## SEE ALSO
systemd(1), systemd.mount(5), systemd.swap(5), systemd-fstab-generator(8), systemd-cryptsetup@.service(8), machine-id(5), cryptsetup(8), fstab(5), btrfs(8)

## NOTES
1.

UEFI Specification

https://uefi.org/specifications

2.

Discoverable Partitions Specification

https://systemd.io/DISCOVERABLE_PARTITIONS

3.

Boot Loader Interface

https://systemd.io/BOOT_LOADER_INTERFACE

4.

Boot Loader Specification

https://systemd.io/BOOT_LOADER_SPECIFICATION


systemd-halt.service

title: systemd-halt.service(8)

summary: System shutdown logic

text:
# systemd-halt.service(8)

## NAME
systemd-halt.service, systemd-poweroff.service, systemd-reboot.service, systemd-kexec.service, systemd-shutdown - System shutdown logic

## SYNOPSIS
systemd-halt.service

systemd-poweroff.service

systemd-reboot.service

systemd-kexec.service

/lib/systemd/systemd-shutdown

/lib/systemd/system-shutdown/

## DESCRIPTION
systemd-halt.service is a system service that is pulled in by halt.target and is responsible for the actual system halt. Similarly, systemd-poweroff.service is pulled in by poweroff.target, systemd-reboot.service by reboot.target and systemd-kexec.service by kexec.target to execute the respective actions.

When these services are run, they ensure that PID 1 is replaced by the /lib/systemd/systemd-shutdown tool which is then responsible for the actual shutdown. Before shutting down, this binary will try to unmount all remaining file systems, disable all remaining swap devices, detach all remaining storage devices and kill all remaining processes.

It is necessary to have this code in a separate binary because otherwise rebooting after an upgrade might be broken — the running PID 1 could still depend on libraries which are not available any more, thus keeping the file system busy, which then cannot be re-mounted read-only.

Immediately before executing the actual system halt/poweroff/reboot/kexec systemd-shutdown will run all executables in /lib/systemd/system-shutdown/ and pass one arguments to them: either "halt", "poweroff", "reboot" or "kexec", depending on the chosen action. All executables in this directory are executed in parallel, and execution of the action is not continued before all executables finished.

Note that systemd-halt.service (and the related units) should never be executed directly. Instead, trigger system shutdown with a command such as "systemctl halt" or suchlike.

## SEE ALSO
systemd(1), systemctl(1), systemd.special(7), reboot(2), systemd-suspend.service(8), bootup(7)


systemd-hibernate-resume-generator

title: systemd-hibernate-resume-generator(8)

text:
# systemd-hibernate-resume-generator(8)

## NAME
systemd-hibernate-resume-generator - Unit generator for resume= kernel parameter

## SYNOPSIS
/lib/systemd/system-generators/systemd-hibernate-resume-generator

## DESCRIPTION
systemd-hibernate-resume-generator is a generator that initiates the procedure to resume the system from hibernation. It instantiates the systemd-hibernate-resume@.service(8) unit according to the value of resume= parameter specified on the kernel command line, which will instruct the kernel to resume the system from the hibernation image on that device.

## KERNEL COMMAND LINE
systemd-hibernate-resume-generator understands the following kernel command line parameters:

resume=

Takes a path to the resume device. Both persistent block device paths like /dev/disk/by-foo/bar and fstab(5)-style specifiers like "FOO=bar" are supported.

resumeflags=

Takes the resume device mount options to use. Defaults rootflags= if not specified.

noresume

Do not try to resume from hibernation. If this parameter is present, resume= is ignored.

## SEE ALSO
systemd(1), systemd-hibernate-resume@.service(8), kernel-command-line(7)