systemd-coredump

package: systemd-coredump

title: systemd-coredump(8)

summary: Acquire, save and process core dumps

text:
# systemd-coredump(8)

## NAME
systemd-coredump, systemd-coredump.socket, systemd-coredump@.service - Acquire, save and process core dumps

## SYNOPSIS
/usr/lib/systemd/systemd-coredump

/usr/lib/systemd/systemd-coredump --backtrace

systemd-coredump@.service

systemd-coredump.socket

## DESCRIPTION
systemd-coredump@.service is a system service to process core dumps. It will log a summary of the event to systemd-journald.service(8), including information about the process identifier, owner, the signal that killed the process, and the stack trace if possible. It may also save the core dump for later processing. See the "Information about the crashed process" section below.

The behavior of a specific program upon reception of a signal is governed by a few factors which are described in detail in core(5). In particular, the core dump will only be processed when the related process resource limits (RLIMIT_CORE) are sufficient.

Core dumps can be written to the journal or saved as a file. In both cases, they can be retrieved for further processing, for example in gdb(1). See coredumpctl(1), in particular the list and debug verbs.

By default, systemd-coredump will log the core dump to the journal, including a backtrace if possible, and store the core dump (an image of the memory contents of the process) itself in an external file in /var/lib/systemd/coredump/. These core dumps are deleted after a few days by default; see /usr/lib/tmpfiles.d/systemd.conf for details. Note that the removal of core files from the file system and the purging of journal entries are independent, and the core file may be present without the journal entry, and journal entries may point to since-removed core files. Some metadata is attached to core files in the form of extended attributes, so the core files are useful for some purposes even without the full metadata available in the journal entry.

For further details see systemd Coredump Handling[1].

### Invocation of systemd-coredump
The systemd-coredump executable does the actual work. It is invoked twice: once as the handler by the kernel, and the second time in the systemd-coredump@.service to actually write the data to the journal and process and save the core file.

When the kernel invokes systemd-coredump to handle a core dump, it runs in privileged mode, and will connect to the socket created by the systemd-coredump.socket unit, which in turn will spawn an unprivileged systemd-coredump@.service instance to process the core dump. Hence systemd-coredump.socket and systemd-coredump@.service are helper units which do the actual processing of core dumps and are subject to normal service management.

It is also possible to invoke systemd-coredump with --backtrace option. In this case, systemd-coredump expects a journal entry in the journal Journal Export Format[2] on standard input. The entry should contain a MESSAGE= field and any additional metadata fields the caller deems reasonable. systemd-coredump will append additional metadata fields in the same way it does for core dumps received from the kernel. In this mode, no core dump is stored in the journal.

### Core dumps in Containers/Namespaces
The systemd-coredump@.service service will automatically attempt to extract a stacktrace from a process as it crashes. For this stacktrace symbols will be resolved based on debug information embedded in the crashing ELF image, or equivalent debug information separately available on the host OS. For processes that crash inside of local containers or other mount namespace-based sandboxes, this auxiliary debug information is typically not available on the host (simply because containers typically run different software versions than the host). systemd-coredump provides two mechanisms to address this:

1.For full-OS containers running systemd inside it is a good idea to enable CoredumpReceive= on the unit (see systemd.resource-control(5)), which ensures that coredumps of a container are attempted to be forwarded to systemd-coredump@.service running inside the container, i.e the container gets to process and store its own core dumps. Note that systemd-nspawn(8) defaults to this mode if invoked with the --boot switch. This mode of operation is generally recommended for security reasons: the security-sensitive processing of the core dump is done within the confinements of the container itself, by the container's own code, backed by the container's own storage.

2.Alternatively, for more restricted containers (that do not run a proper init system as PID 1) it is possible to enable processing of the core dump on the host, with access to the debug information data from the container itself. This mode of operation must be enabled via EnterNamespace= in coredump.conf(5), and defaults to off, for security reasons.

If both CoredumpReceive= is enabled on the unit of the container the core dump belongs to, and EnterNamespace= is enabled in the coredump.conf configuration file, the former takes precedence.

## CONFIGURATION
For programs started by systemd, process resource limits can be set by directive LimitCORE=, see systemd.exec(5).

In order to be used by the kernel to handle core dumps, systemd-coredump must be configured in sysctl(8) parameter kernel.core_pattern. The syntax of this parameter is explained in core(5). systemd installs the file /usr/lib/sysctl.d/50-coredump.conf which configures kernel.core_pattern accordingly. This file may be masked or overridden to use a different setting following normal sysctl.d(5) rules. If the sysctl configuration is modified, it must be updated in the kernel before it takes effect, see sysctl(8) and systemd-sysctl(8).

In order to be used in the --backtrace mode, an appropriate backtrace handler must be installed on the sender side. For example, in case of python(1), this means a sys.excepthook must be installed, see systemd-coredump-python[3].

The behavior of systemd-coredump itself is configured through the configuration file /etc/systemd/coredump.conf and corresponding snippets /etc/systemd/coredump.conf.d/*.conf, see coredump.conf(5). A new instance of systemd-coredump is invoked upon receiving every core dump. Therefore, changes in these files will take effect the next time a core dump is received.

Resources used by core dump files are restricted in two ways. Parameters like maximum size of acquired core dumps and files can be set in files /etc/systemd/coredump.conf and snippets mentioned above. In addition the storage time of core dump files is restricted by systemd-tmpfiles, corresponding settings are by default in /usr/lib/tmpfiles.d/systemd.conf. The default is to delete core dumps after a few days; see the above file for details.

### Disabling coredump processing
To disable potentially resource-intensive processing by systemd-coredump, set

```
Storage=none
ProcessSizeMax=0
```

in coredump.conf(5).

## INFORMATION ABOUT THE CRASHED PROCESS
coredumpctl(1) can be used to retrieve saved core dumps independently of their location, to display information, and to process them e.g. by passing to the GNU debugger (gdb).

Data stored in the journal can be also viewed with journalctl(1) as usual (or from any other process, using the sd-journal(3) API). The relevant messages have MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1:

```
$ journalctl MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1 -o verbose
...
MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1
COREDUMP_PID=552351
COREDUMP_UID=1000
COREDUMP_GID=1000
COREDUMP_SIGNAL_NAME=SIGSEGV
COREDUMP_SIGNAL=11
COREDUMP_TIMESTAMP=1614342930000000
COREDUMP_COMM=Web Content
COREDUMP_EXE=/usr/lib64/firefox/firefox
COREDUMP_USER_UNIT=app-gnome-firefox-552136.scope
COREDUMP_CMDLINE=/usr/lib64/firefox/firefox -contentproc -childID 5 -isForBrowser ...
COREDUMP_CGROUP=/user.slice/user-1000.slice/user@1000.service/app.slice/app-....scope
COREDUMP_FILENAME=/var/lib/systemd/coredump/core.Web....552351.....zst
...
```

The following fields are saved (if known) with the journal entry

COREDUMP_UID=, COREDUMP_PID=, COREDUMP_GID=

The process number (PID), owner user number (UID), and group number (GID) of the crashed process. When the crashed process was part of a container (or in a process or user namespace in general), those are the values as seen outside, in the namespace where systemd-coredump is running.

Added in version 248.

COREDUMP_BY_PIDFD=

If the crashed process was analyzed using a PIDFD provided by the kernel (requires kernel v6.16) then this field will be present and set to "1". If this field is not set, then the crashed process was analyzed via a PID, which is known to be subject to race conditions. Added in version 258.

COREDUMP_TIMESTAMP=

The time of the crash as reported by the kernel (in μs since the epoch). Added in version 248.

COREDUMP_RLIMIT=

The core file size soft resource limit, see getrlimit(2). Added in version 248.

COREDUMP_UNIT=, COREDUMP_SLICE=

The system unit and slice names. When the crashed process was in container, those are the units names outside, in the main system manager.

Added in version 248.

COREDUMP_CGROUP=

The primary cgroup of the unit of the crashed process. When the crashed process was in a container, this is the full path, as seen outside of the container.

Added in version 248.

COREDUMP_PROC_CGROUP=

Control group information in the format used in /proc/self/cgroup. On systems with the unified cgroup hierarchy, this is a single path prefixed with "0::", and multiple paths prefixed with controller numbers on legacy systems. When the crashed process was in a container, this is the full path, as seen outside of the container.

Added in version 248.

COREDUMP_OWNER_UID=, COREDUMP_USER_UNIT=, COREDUMP_SESSION=

The numerical UID of the user owning the login session or systemd user unit of the crashed process, the user manager unit, and the session identifier. All three fields are only present for user processes. When the crashed process was in container, those are the values outside, in the main system.

Added in version 248.

COREDUMP_SIGNAL_NAME=, COREDUMP_SIGNAL=

The terminating signal name (with the "SIG" prefix [4]) and numerical value. (Both are included because signal numbers vary by architecture.) Added in version 248.

COREDUMP_CWD=, COREDUMP_ROOT=

The current working directory and root directory of the crashed process. When the crashed process is in a container, those paths are relative to the root of the container's mount namespace.

Added in version 248.

COREDUMP_DUMPABLE=

The PR_GET_DUMPABLE field as reported by the kernel, see prctl(2). Added in version 258.

COREDUMP_OPEN_FDS=

Information about open file descriptors, in the following format:

```
fd:/path/to/file
pos:     ...
flags:   ...
...
fd:/path/to/file
pos:     ...
flags:   ...
...
```

The first line contains the file descriptor number fd and the path, while subsequent lines show the contents of /proc/pid/fdinfo/fd.

Added in version 248.

COREDUMP_EXE=

The destination of the /proc/pid/exe symlink. When the crashed process is in a container, that path is relative to the root of the container's mount namespace.

Added in version 248.

COREDUMP_CMDLINE=, COREDUMP_COMM=, COREDUMP_ENVIRON=, COREDUMP_PROC_AUXV=, COREDUMP_PROC_LIMITS=, COREDUMP_PROC_MAPS=, COREDUMP_PROC_MOUNTINFO=, COREDUMP_PROC_STATUS=

Fields that map the per-process entries in the /proc/ filesystem: /proc/pid/cmdline (the command line of the crashed process), /proc/pid/comm (the command name associated with the process), /proc/pid/environ (the environment block of the crashed process), /proc/pid/auxv (the auxiliary vector of the crashed process, see getauxval(3)), /proc/pid/limits (the soft and hard resource limits), /proc/pid/maps (memory regions visible to the process and their access permissions), /proc/pid/mountinfo (mount points in the process's mount namespace), /proc/pid/status (various metadata about the process). See proc(5) for more information.

Added in version 248.

COREDUMP_HOSTNAME=

The system hostname. When the crashed process was in container, this is the container hostname.

Added in version 248.

COREDUMP_CONTAINER_CMDLINE=

For processes running in a container, the command line of the process spawning the container (the first parent process with a different mount namespace). Added in version 248.

COREDUMP=

When the core is stored in the journal, the core image itself. Added in version 248.

COREDUMP_FILENAME=

When the core is stored externally, the path to the core file. Added in version 248.

COREDUMP_TRUNCATED=

Set to "1" when the saved coredump was truncated. (A partial core image may still be processed by some tools, though obviously not all information is available.) Added in version 248.

COREDUMP_PACKAGE_NAME=, COREDUMP_PACKAGE_VERSION=, COREDUMP_PACKAGE_JSON=

If the executable contained .package metadata ELF notes, they will be parsed and attached. The package and version of the 'main' ELF module (i.e., the executable) will be appended individually. The JSON-formatted content of all modules will be appended as a single JSON object, each with the module name as the key. For more information about this metadata format and content, see the Package Metadata for Executable Files[5] document. Added in version 249.

MESSAGE=

The message generated by systemd-coredump that includes the backtrace if it was successfully generated. When systemd-coredump is invoked with --backtrace, this field is provided by the caller. Added in version 248.

Various other fields exist in the journal entry, but pertain to the logging process, i.e. systemd-coredump, not the crashed process. See systemd.journal-fields(7).

The following fields are saved (if known) with the external file listed in COREDUMP_FILENAME= as extended attributes:

user.coredump.pid, user.coredump.uid, user.coredump.gid, user.coredump.signal, user.coredump.timestamp, user.coredump.rlimit, user.coredump.hostname, user.coredump.comm, user.coredump.exe

Those are the same as COREDUMP_PID=, COREDUMP_UID=, COREDUMP_GID=, COREDUMP_SIGNAL=, COREDUMP_TIMESTAMP=, COREDUMP_RLIMIT=, COREDUMP_HOSTNAME=, COREDUMP_COMM=, and COREDUMP_EXE=, described above. Added in version 248.

Those can be viewed using getfattr(1). For the core file described in the journal entry shown above:

```
$ getfattr --absolute-names -d /var/lib/systemd/coredump/core.Web....552351.....zst
# file: /var/lib/systemd/coredump/core.Web....552351.....zst
user.coredump.pid="552351"
user.coredump.uid="1000"
user.coredump.gid="1000"
user.coredump.signal="11"
user.coredump.timestamp="1614342930000000"
user.coredump.comm="Web Content"
user.coredump.exe="/usr/lib64/firefox/firefox"
...
```

## SEE ALSO
coredump.conf(5), coredumpctl(1), systemd-journald.service(8), systemd-tmpfiles(8), core(5), sysctl.d(5), systemd-sysctl.service(8), systemd Coredump Handling[1]

## NOTES
1.

systemd Coredump Handling

https://systemd.io/COREDUMP

2.

Journal Export Format

https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format

3.

systemd-coredump-python

https://github.com/systemd/systemd-coredump-python

4.

kill(1) expects signal names without the prefix; kill(2) uses the prefix; all systemd tools accept signal names both with and without the prefix.

5.

Package Metadata for Executable Files

https://systemd.io/PACKAGE_METADATA_FOR_EXECUTABLE_FILES/


systemd-homed.service

package: systemd-homed

title: systemd-homed.service(8)

summary: Home Area/User Account Manager

text:
# systemd-homed.service(8)

## NAME
systemd-homed.service, systemd-homed - Home Area/User Account Manager

## SYNOPSIS
systemd-homed.service

/usr/lib/systemd/systemd-homed

## DESCRIPTION
systemd-homed is a system service that may be used to create, remove, change or inspect home areas (directories and network mounts and real or loopback block devices with a filesystem, optionally encrypted).

Most of systemd-homed's functionality is accessible through the homectl(1) command.

See the Home Directories[1] documentation for details about the format and design of home areas managed by systemd-homed.service.

Each home directory managed by systemd-homed.service synthesizes a local user and group. These are made available to the system using the User/Group Record Lookup API via Varlink[2], and thus may be browsed with userdbctl(1).

systemd-homed.service also manages blob directories for each home directory it manages. See User Record Blob Directories[3] for more details.

## KEY MANAGEMENT
User records are cryptographically signed with a public/private key pair (the signature is part of the JSON record itself). For a user to be permitted to log in locally the public key matching the signature of their user record must be installed. For a user record to be modified locally the private key matching the signature must be installed locally, too. The keys are stored in the /var/lib/systemd/home/ directory:

/var/lib/systemd/home/local.private

The private key of the public/private key pair used for local records. Currently, only a single such key may be installed. Added in version 246.

/var/lib/systemd/home/local.public

The public key of the public/private key pair used for local records. Currently, only a single such key may be installed. Added in version 246.

/var/lib/systemd/home/*.public

Additional public keys. Any users whose user records are signed with any of these keys are permitted to log in locally. An arbitrary number of keys may be installed this way. Added in version 246.

All key files listed above are in PEM format.

In order to migrate a home directory from a host "foobar" to another host "quux" it is hence sufficient to copy /var/lib/systemd/home/local.public from the host "foobar" to "quux", maybe calling the file on the destination /var/lib/systemd/home/foobar.public, reflecting the origin of the key. If the user record should be modifiable on "quux" the pair /var/lib/systemd/home/local.public and /var/lib/systemd/home/local.private need to be copied from "foobar" to "quux", and placed under the identical paths there, as currently only a single private key is supported per host. Note of course that the latter means that user records generated/signed before the key pair is copied in, lose their validity.

## SIGNALS
SIGUSR1

Upon reception of the SIGUSR1 process signal systemd-homed will reestablish its file watches on /home/ and rescan the directory for home directories. Added in version 258.

## SEE ALSO
systemd(1), homed.conf(5), homectl(1), pam_systemd_home(8), userdbctl(1), org.freedesktop.home1(5)

## NOTES
1.

Home Directories

https://systemd.io/HOME_DIRECTORY

2.

User/Group Record Lookup API via Varlink

https://systemd.io/USER_GROUP_API

3.

User Record Blob Directories

https://systemd.io/USER_RECORD_BLOB_DIRS

branch: sisyphus


systemd-journal-gatewayd.service

package: systemd-journal-remote

title: systemd-journal-gatewayd.service(8)

summary: HTTP server for journal events

text:
# systemd-journal-gatewayd.service(8)

## NAME
systemd-journal-gatewayd.service, systemd-journal-gatewayd.socket, systemd-journal-gatewayd - HTTP server for journal events

## SYNOPSIS
systemd-journal-gatewayd.service

systemd-journal-gatewayd.socket

/usr/lib/systemd/systemd-journal-gatewayd [OPTIONS...]

## DESCRIPTION
systemd-journal-gatewayd serves journal events over the network. Clients must connect using HTTP. The server listens on port 19531 by default. If --cert= is specified, the server expects HTTPS connections.

The program is started by systemd(1) and expects to receive a single socket. Use systemctl start systemd-journal-gatewayd.socket to start the service, and systemctl enable systemd-journal-gatewayd.socket to have it started on boot.

## OPTIONS
The following options are understood:

--cert=

Specify the path to a file or AF_UNIX stream socket to read the server certificate from. The certificate must be in PEM format. This option switches systemd-journal-gatewayd into HTTPS mode and must be used together with --key=. Added in version 198.

--key=

Specify the path to a file or AF_UNIX stream socket to read the secret server key corresponding to the certificate specified with --cert= from. The key must be in PEM format. Added in version 198.

--trust=

Specify the path to a file or AF_UNIX stream socket to read a CA certificate from. The certificate must be in PEM format. Added in version 236.

--system, --user

Limit served entries to entries from system services and the kernel, or to entries from services of current user. This has the same meaning as --system and --user options for journalctl(1). If neither is specified, all accessible entries are served. Added in version 249.

-m, --merge

Serve entries interleaved from all available journals, including other machines. This has the same meaning as --merge option for journalctl(1). Added in version 249.

-D DIR, --directory=DIR

Takes a directory path as argument. If specified, systemd-journal-gatewayd will serve the specified journal directory DIR instead of the default runtime and system journal paths. Added in version 232.

--file=GLOB

Takes a file glob as an argument. Serve entries from the specified journal files matching GLOB instead of the default runtime and system journal paths. May be specified multiple times, in which case files will be suitably interleaved. This has the same meaning as --file= option for journalctl(1). Added in version 249.

-h, --help

Print a short help text and exit.

--version

Print a short version string and exit.

## SUPPORTED URLS
The following URLs are recognized:

/boots

Returns json-seq (RFC 7464) response containing JSON objects, each one containing boot number, its ID and the timestamps of the first and last message. Boots are returned starting with the latest boot first and use the same schema as journalctl --list-boots --output json. Added in version 258.

/browse

Interactive browsing. Added in version 197.

/entries[?option1&option2=value...]

Retrieval of events in various formats. The Accept: part of the HTTP header determines the format. Supported values are described below.

The Range: part of the HTTP header determines the range of events returned. Supported values are described below.

GET parameters can be used to modify what events are returned. Supported parameters are described below.

Added in version 197.

/machine

Return a JSON structure describing the machine. Example:

```
{ "machine_id" : "8cf7ed9d451ea194b77a9f118f3dc446",

  "boot_id" : "3d3c9efaf556496a9b04259ee35df7f7",

  "hostname" : "fedora",

  "os_pretty_name" : "Fedora 19 (Rawhide)",

  "virtualization" : "kvm",

  ...}
```

Added in version 197.

/fields/FIELD_NAME

Return a list of values of this field present in the logs. Added in version 197.

## ACCEPT HEADER
Accept: format

Recognized formats:

text/plain

The default. Plaintext syslog-like output, one line per journal entry (like journalctl --output short). Added in version 197.

application/json

Entries are formatted as JSON data structures, one per line (like journalctl --output json). See Journal JSON Format[1] for more information. Added in version 197.

text/event-stream

Entries are formatted as JSON data structures, wrapped in a format suitable for Server-Sent Events[2] (like journalctl --output json-sse). Added in version 229.

application/vnd.fdo.journal

Entries are serialized into a binary (but mostly text-based) stream suitable for backups and network transfer (like journalctl --output export). See Journal Export Format[3] for more information. Added in version 197.

## RANGE HEADER
Range: entries=[cursor][[:num_skip]:[num_entries]]

Range: realtime=[since]:[until][[:num_skip]:num_entries]

where cursor is a cursor string, defaults to the first entry, since and until are timestamps (seconds since 1970-01-01 00:00:00 UTC), num_skip is an integer, num_entries is an unsigned integer.

Range defaults to all available events.

If num_skip is negative and no cursor is given, the last entry will be the reference point.

## URL GET PARAMETERS
Following parameters can be used as part of the URL:

follow

wait for new events (like journalctl --follow, the number of events returned is not limited, unless num_entries is specified in the Range header). Added in version 197.

discrete

Test that the specified cursor refers to an entry in the journal. Returns just this entry. Added in version 197.

boot

Limit events to the current boot of the system (like journalctl -b). Added in version 197.

KEY=match

Match journal fields. See systemd.journal-fields(7). Added in version 197.

## EXAMPLES
Retrieve events from this boot from local journal in Journal Export Format[3]:

```
curl --silent -H'Accept: application/vnd.fdo.journal' \

       'http://localhost:19531/entries?boot'
```

Listen for core dumps:

```
curl 'http://localhost:19531/entries?follow&MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1'
```

## SEE ALSO
systemd(1), journalctl(1), systemd.journal-fields(7), systemd-journald.service(8), systemd-journal-remote.service(8), systemd-journal-upload.service(8)

## NOTES
1.

Journal JSON Format

https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-json-format

2.

Server-Sent Events

https://developer.mozilla.org/en-US/docs/Server-sent_events/Using_server-sent_events

3.

Journal Export Format

https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format


systemd-journal-remote.service

title: systemd-journal-remote.service(8)

text:
# systemd-journal-remote.service(8)

## NAME
systemd-journal-remote.service, systemd-journal-remote.socket, systemd-journal-remote - Receive journal messages over the network

## SYNOPSIS
systemd-journal-remote.service

systemd-journal-remote.socket

/usr/lib/systemd/systemd-journal-remote [OPTIONS...] [-o/--output=DIR|FILE] [SOURCES...]

## DESCRIPTION
systemd-journal-remote is a command to receive serialized journal events and store them to journal files. Input streams are in the Journal Export Format[1], i.e. like the output from journalctl --output=export. For transport over the network, this serialized stream is usually carried over an HTTPS connection.

systemd-journal-remote.service is a system service that uses systemd-journal-remote to listen for connections. systemd-journal-remote.socket configures the network address that systemd-journal-remote.service listens on. By default, this is port 19532. What connections are accepted and how the received data is stored can be configured through the journal-remote.conf(5) configuration file.

## SOURCES
Sources can be either "active" (systemd-journal-remote requests and pulls the data), or "passive" (systemd-journal-remote waits for a connection and then receives events pushed by the other side).

systemd-journal-remote can read more than one event stream at a time. They will be interleaved in the output file. In case of "active" connections, each "source" is one stream, and in case of "passive" connections, each connection can result in a separate stream. Sockets can be configured in "accept" mode (i.e. only one connection), or "listen" mode (i.e. multiple connections, each resulting in a stream).

When there are no more connections, and no more can be created (there are no listening sockets), then systemd-journal-remote will exit.

Active sources can be specified in the following ways:

[SOURCES]

When - is given as a positional argument, events will be read from standard input. Other positional arguments will be treated as filenames to open and read from. Added in version 239.

--url=ADDRESS

With the --url=ADDRESS option, events will be retrieved using HTTP from ADDRESS. This URL should refer to the root of a remote systemd-journal-gatewayd(8) instance, e.g. http://some.host:19531/ or https://some.host:19531/. Added in version 239.

--getter='PROG [OPTIONS]'

Program to invoke to retrieve data. The journal event stream must be generated on standard output. Examples:

```
--getter='curl "-HAccept: application/vnd.fdo.journal" https://some.host:19531/'
```

```
--getter='wget --header="Accept: application/vnd.fdo.journal" -O- https://some.host:19531/'
```

Added in version 239.

Passive sources can be specified in the following ways:

--listen-raw=ADDRESS

ADDRESS must be an address suitable for ListenStream= (cf. systemd.socket(5)). systemd-journal-remote will listen on this socket for connections. Each connection is expected to be a stream of journal events. Added in version 239.

--listen-http=ADDRESS, --listen-https=ADDRESS

ADDRESS must be either a negative integer, in which case it will be interpreted as the (negated) file descriptor number, or an address suitable for ListenStream= (c.f. systemd.socket(5)). In the first case, the server listens on port 19532 by default, and the matching file descriptor must be inherited through $LISTEN_FDS/$LISTEN_PID. In the second case, an HTTP or HTTPS server will be spawned on this port, respectively for --listen-http= and --listen-https=. Currently, only POST requests to /upload with "Content-Type: application/vnd.fdo.journal" are supported. Added in version 239.

$LISTEN_FDS

systemd-journal-remote supports the $LISTEN_FDS/$LISTEN_PID protocol. Open sockets inherited through socket activation behave like those opened with --listen-raw= described above, unless they are specified as an argument in --listen-http=-n or --listen-https=-n above. In the latter case, an HTTP or HTTPS server will be spawned using this descriptor and connections must be made over the HTTP protocol. Added in version 239.

--key=

Takes a path to a SSL secret key file in PEM format. Defaults to /etc/pki/tls/private/journal-remote.pem. This option can be used with --listen-https=. If the path refers to an AF_UNIX stream socket in the file system a connection is made to it and the key read from it. Added in version 239.

--cert=

Takes a path to a SSL certificate file in PEM format. Defaults to /etc/pki/tls/certs/journal-remote.pem. This option can be used with --listen-https=. If the path refers to an AF_UNIX stream socket in the file system a connection is made to it and the certificate read from it. Added in version 239.

--trust=

Takes a path to a SSL CA certificate file in PEM format, or all. If all is set, then certificate checking will be disabled. Defaults to /etc/pki/tls/ca/trusted.pem. This option can be used with --listen-https=. If the path refers to an AF_UNIX stream socket in the file system a connection is made to it and the certificate read from it. Added in version 239.

--gnutls-log=

Takes a comma separated list of gnutls logging categories. This option can be used with --listen-http= or --listen-https=. Added in version 239.

## SINKS
The location of the output journal can be specified with -o or --output=.

-o FILE, --output=FILE

Will write to this journal file. The filename must end with .journal. The file will be created if it does not exist. If necessary (journal file full, or corrupted), the file will be renamed following normal journald rules and a new journal file will be created in its stead. Added in version 239.

-o DIR, --output=DIR

Will create journal files underneath directory DIR. The directory must exist. If necessary (journal files over size, or corrupted), journal files will be rotated following normal journald rules. Names of files underneath DIR will be generated using the rules described below. Added in version 239.

If --output= is not used, the output directory /var/log/journal/remote/ will be used. In case the output file is not specified, journal files will be created underneath the selected directory. Files will be called remote-hostname.journal, where the hostname part is the escaped hostname of the source endpoint of the connection, or the numerical address if the hostname cannot be determined.

In the case that "active" sources are given by the positional arguments or --getter= option, the output file name must always be given explicitly.

## OPTIONS
The following options are understood:

--split-mode

One of none or host. For the first, only one output journal file is used. For the latter, a separate output file is used, based on the hostname of the other endpoint of a connection. In the case that "active" sources are given by the positional arguments or --getter= option, the output file name must always be given explicitly and only none is allowed.

Added in version 239.

--compress [BOOL]

If this is set to "yes" then compress the data in the journal using XZ. The default is "yes". Added in version 239.

--seal [BOOL]

If this is set to "yes" then periodically sign the data in the journal using Forward Secure Sealing. The default is "no". Added in version 239.

-h, --help

Print a short help text and exit.

--version

Print a short version string and exit.

## EXAMPLES
Copy local journal events to a different journal directory:

```
journalctl -o export | systemd-journal-remote -o /tmp/dir/foo.journal -
```

Retrieve all available events from a remote systemd-journal-gatewayd(8) instance and store them in /var/log/journal/remote/remote-some.host.journal:

```
systemd-journal-remote --url http://some.host:19531/
```

Retrieve current boot events and wait for new events from a remote systemd-journal-gatewayd(8) instance, and store them in /var/log/journal/remote/remote-some.host.journal:

```
systemd-journal-remote --url http://some.host:19531/entries?boot&follow
```

## SEE ALSO
journal-remote.conf(5), journalctl(1), systemd-journal-gatewayd.service(8), systemd-journal-upload.service(8), systemd-journald.service(8)

## NOTES
1.

Journal Export Format

https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format


systemd-journal-upload.service

title: systemd-journal-upload.service(8)

summary: Send journal messages over the network

text:
# systemd-journal-upload.service(8)

## NAME
systemd-journal-upload.service, systemd-journal-upload - Send journal messages over the network

## SYNOPSIS
systemd-journal-upload.service

/usr/lib/systemd/systemd-journal-upload [OPTIONS...] [-u/--url=URL] [SOURCES...]

## DESCRIPTION
systemd-journal-upload will upload journal entries to the URL specified with --url=. This program reads journal entries from one or more journal files, similarly to journalctl(1). Unless limited by one of the options specified below, all journal entries accessible to the user the program is running as will be uploaded, and then the program will wait and send new entries as they become available.

systemd-journal-upload transfers the raw content of journal file and uses HTTP as a transport protocol.

systemd-journal-upload.service is a system service that uses systemd-journal-upload to upload journal entries to a server. It uses the configuration in journal-upload.conf(5). At least the URL= option must be specified.

## OPTIONS
-u, --url=[https://]URL[:PORT], --url=[http://]URL[:PORT]

Upload to the specified address. URL may specify either just the hostname or both the protocol and hostname. https is the default. The port number may be specified after a colon (":"), otherwise 19532 will be used by default. Added in version 239.

--system, --user

Limit uploaded entries to entries from system services and the kernel, or to entries from services of current user. This has the same meaning as --system and --user options for journalctl(1). If neither is specified, all accessible entries are uploaded. Added in version 239.

-m, --merge

Upload entries interleaved from all available journals, including other machines. This has the same meaning as --merge option for journalctl(1). Added in version 239.

--namespace=NAMESPACE

Takes a journal namespace identifier string as argument. Upload entries from the specified journal namespace NAMESPACE instead of the default namespace. This has the same meaning as --namespace= option for journalctl(1). Added in version 254.

-D, --directory=DIR

Takes a directory path as argument. Upload entries from the specified journal directory DIR instead of the default runtime and system journal paths. This has the same meaning as --directory= option for journalctl(1). Added in version 239.

--file=GLOB

Takes a file glob as an argument. Upload entries from the specified journal files matching GLOB instead of the default runtime and system journal paths. May be specified multiple times, in which case files will be suitably interleaved. This has the same meaning as --file= option for journalctl(1). Added in version 239.

--cursor=

Upload entries from the location in the journal specified by the passed cursor. This has the same meaning as --cursor= option for journalctl(1). Added in version 239.

--after-cursor=

Upload entries from the location in the journal after the location specified by the this cursor. This has the same meaning as --after-cursor= option for journalctl(1). Added in version 239.

--save-state[=PATH]

Upload entries from the location in the journal after the location specified by the cursor saved in file at PATH (/var/lib/systemd/journal-upload/state by default). After an entry is successfully uploaded, update this file with the cursor of that entry. Added in version 239.

--follow[=BOOL]

If set to yes, then systemd-journal-upload waits for input. Added in version 239.

--key=

Takes a path to a SSL key file in PEM format, or -. If - is set, then client certificate authentication checking will be disabled. Defaults to /etc/pki/tls/private/journal-upload.pem. Added in version 239.

--cert=

Takes a path to a SSL certificate file in PEM format, or -. If - is set, then client certificate authentication checking will be disabled. Defaults to /etc/pki/tls/certs/journal-upload.pem. Added in version 239.

--trust=

Takes a path to a SSL CA certificate file in PEM format, or -/all. If -/all is set, then certificate checking will be disabled. Defaults to /etc/pki/tls/ca/trusted.pem. Added in version 239.

-h, --help

Print a short help text and exit.

--version

Print a short version string and exit.

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

## EXAMPLES
Example 1. Setting up certificates for authentication

Certificates signed by a trusted authority are used to verify that the server to which messages are uploaded is legitimate, and vice versa, that the client is trusted.

A suitable set of certificates can be generated with openssl. Note, 2048 bits of key length is minimally recommended to use for security reasons:

```
openssl req -newkey rsa:2048 -days 3650 -x509 -nodes \

      -out ca.pem -keyout ca.key -subj '/CN=Certificate authority/'
cat >ca.conf <<EOF
[ ca ]
default_ca = this
[ this ]
new_certs_dir = .
certificate = ca.pem
database = ./index
private_key = ca.key
serial = ./serial
default_days = 3650
default_md = default
policy = policy_anything
[ policy_anything ]
countryName             = optional
stateOrProvinceName     = optional
localityName            = optional
organizationName        = optional
organizationalUnitName  = optional
commonName              = supplied
emailAddress            = optional
EOF
touch index
echo 0001 >serial
SERVER=server
CLIENT=client
openssl req -newkey rsa:2048 -nodes -out $SERVER.csr -keyout $SERVER.key -subj "/CN=$SERVER/"
openssl ca -batch -config ca.conf -notext -in $SERVER.csr -out $SERVER.pem
openssl req -newkey rsa:2048 -nodes -out $CLIENT.csr -keyout $CLIENT.key -subj "/CN=$CLIENT/"
openssl ca -batch -config ca.conf -notext -in $CLIENT.csr -out $CLIENT.pem
```

Generated files ca.pem, server.pem, and server.key should be installed on server, and ca.pem, client.pem, and client.key on the client. The location of those files can be specified using TrustedCertificateFile=, ServerCertificateFile=, and ServerKeyFile= in /etc/systemd/journal-remote.conf and /etc/systemd/journal-upload.conf, respectively. The default locations can be queried by using systemd-journal-remote --help and systemd-journal-upload --help.

## SEE ALSO
journal-upload.conf(5), systemd-journal-remote.service(8), journalctl(1), systemd-journald.service(8), systemd-journal-gatewayd.service(8)


systemd-network-generator.service

package: systemd-networkd

title: systemd-network-generator.service(8)

text:
# systemd-network-generator.service(8)

## NAME
systemd-network-generator.service, systemd-network-generator - Generate network configuration from the kernel command line

## SYNOPSIS
systemd-network-generator.service

/usr/lib/systemd/systemd-network-generator

## DESCRIPTION
systemd-network-generator.service is a system service that translates ip= and related settings on the kernel command line (see below) into systemd.network(5), systemd.netdev(5), and systemd.link(5) configuration files understood by systemd-networkd.service(8) and systemd-udevd.service(8).

Files are generated in /run/systemd/network/.

Note: despite the name, this generator executes as a normal systemd service and is not an implementation of the systemd.generator(7) concept.

## KERNEL COMMAND LINE OPTIONS
This tool understands the following options:

ip=, nameserver=, rd.route=, rd.peerdns=

Translated into systemd.network(5) files. In addition to the parameters dracut.cmdline(7) defines the ip= option accepts the special value "link-local". If selected, the network interfaces will be configured for link-local addressing (IPv4LL, IPv6LL) only, DHCP or IPv6RA will not be enabled.

Added in version 245.

ifname=, net.ifname_policy=

Translated into systemd.link(5) files. Added in version 245.

vlan=, bond=, bridge=, bootdev=

Translated into systemd.netdev(5) files. Added in version 245.

See dracut.cmdline(7) and systemd-udevd.service(8) for option syntax and details.

## CREDENTIALS
systemd-network-generator supports the service credentials logic as implemented by ImportCredential=/LoadCredential=/SetCredential= (see systemd.exec(5) for details). The following credentials are used when passed in:

network.conf.*, network.link.*, network.netdev.*, network.network.*

These credentials should contain valid networkd.conf(5), systemd.link(5), systemd.netdev(5), systemd.network(5) configuration data. From each matching credential a separate file is created. Example: a passed credential network.link.50-foobar will be copied into a configuration file 50-foobar.link. Note that the resulting files are created world-readable, it is hence recommended to not include secrets in these credentials, but to supply them via separate credentials directly to systemd-networkd.service(8).

Added in version 256.

Note that by default the systemd-networkd.service(8) service is set up to inherit the these credentials from the service manager.

## SEE ALSO
systemd(1), systemd-networkd.service(8), dracut(8)


systemd-networkd-wait-online.service

title: systemd-networkd-wait-online.service(8)

summary: Wait for network to come online

text:
# systemd-networkd-wait-online.service(8)

## NAME
systemd-networkd-wait-online.service, systemd-networkd-wait-online@.service, systemd-networkd-wait-online - Wait for network to come online

## SYNOPSIS
systemd-networkd-wait-online.service

systemd-networkd-wait-online@.service

/usr/lib/systemd/systemd-networkd-wait-online

## DESCRIPTION
systemd-networkd-wait-online is a oneshot system service (see systemd.service(5)), that waits for the network to be configured. By default, it will wait for all links it is aware of and which are managed by systemd-networkd.service(8) to be fully configured or failed, and for at least one link to be online. Here, online means that the link's operational state is equal or higher than "degraded". The threshold can be configured by --operational-state= option.

The service systemd-networkd-wait-online.service invokes systemd-networkd-wait-online without any options. Thus, it waits for all managed interfaces to be configured or failed, and for at least one to be online.

The service systemd-networkd-wait-online@.service takes an interface name, and invokes systemd-networkd-wait-online with -i and the specified interface name. Thus, wait for the specified interface to be configured and online. For example, systemd-networkd-wait-online@eth0.service waits for eth0 to be configured by systemd-networkd and online.

## OPTIONS
The following options are understood:

-i INTERFACE[:MIN_OPERSTATE[:MAX_OPERSTATE]], --interface=INTERFACE[:MIN_OPERSTATE[:MAX_OPERSTATE]]

Network interface to wait for before deciding if the system is online. This is useful when a system has several interfaces which will be configured, but a particular one is necessary to access some network resources. When used, all other interfaces are ignored. This option may be used more than once to wait for multiple network interfaces. When this option is specified multiple times, then systemd-networkd-wait-online waits for all specified interfaces to be online. Optionally, required minimum and maximum operational states can be specified after a colon ":". Please see networkctl(1) for possible operational states. If the operational state is not specified here, then the value from RequiredForOnline= in the corresponding .network file is used if present, and "degraded" otherwise. Added in version 213.

--ignore=INTERFACE

Network interfaces to be ignored when deciding if the system is online. By default, only the loopback interface is ignored. This option may be used more than once to ignore multiple network interfaces. Added in version 219.

-o MIN_OPERSTATE[:MAX_OPERSTATE], --operational-state=MIN_OPERSTATE[:MAX_OPERSTATE]

Takes a minimum operational state and an optional maximum operational state. Please see networkctl(1) for possible operational states. If set, the specified value overrides RequiredForOnline= settings in .network files. But this does not override operational states specified in --interface= option. Added in version 242.

-4, --ipv4

Waiting for an IPv4 address of each network interface to be configured. If this option is specified with --any, then systemd-networkd-wait-online exits with success when at least one interface becomes online and has an IPv4 address. If the required minimum operational state is below "routable", then each link (or at least one link with --any) must have an IPv4 link-local or routable address. If the required minimum operational state is "routable", then each link must have an IPv4 routable address. If neither --ipv4 nor --ipv6 is specified, then the value from RequiredFamilyForOnline= in the corresponding .network file is used if present.

Added in version 249.

-6, --ipv6

Waiting for an IPv6 address of each network interface to be configured. If this option is specified with --any, then systemd-networkd-wait-online exits with success when at least one interface becomes online and has an IPv6 address. If the required minimum operational state is below "routable", then each link (or at least one link with --any) must have an IPv6 link-local or routable address. If the required minimum operational state is "routable", then each link must have an IPv6 routable address. If neither --ipv4 nor --ipv6 is specified, then the value from RequiredFamilyForOnline= in the corresponding .network file is used if present.

Added in version 249.

--dns

Waiting for DNS servers to be accessible on each interface. If this option is specified with --any, then systemd-networkd-wait-online exits with success when at least one interface becomes online and has an accessible DNS server. If a link has the property DefaultRoute=yes (either because the DNSDefaultRoute= network property is explicitly configured, or because the link does not have any "routing-only" domains), or if the search domain "." is configured, then wait for link-specific DNS servers to be accessible. Otherwise, allow global DNS servers to satisfy the condition.

Added in version 258.

--any

Even if several interfaces are in configuring state, systemd-networkd-wait-online exits with success when at least one interface becomes online. When this option is specified with --interface=, then systemd-networkd-wait-online waits for one of the specified interfaces to be online. This option is useful when some interfaces may not have carrier on boot. Added in version 242.

--timeout=SECS

Fail the service if the network is not online by the time the timeout elapses. A timeout of 0 disables the timeout. Defaults to 120 seconds. Added in version 219.

-q, --quiet

Suppress log messages. Added in version 242.

-h, --help

Print a short help text and exit.

--version

Print a short version string and exit.

## SEE ALSO
systemd(1), systemd.service(5), systemd-networkd.service(8), networkctl(1)


systemd-networkd.service

title: systemd-networkd.service(8)

summary: Network manager

text:
# systemd-networkd.service(8)

## NAME
systemd-networkd.service, systemd-networkd - Network manager

## SYNOPSIS
systemd-networkd.service

/usr/lib/systemd/systemd-networkd

## DESCRIPTION
systemd-networkd is a system service that manages networks. It detects and configures network devices as they appear, as well as creating virtual network devices.

Certain low-level settings of physical network devices (e.g. device names and altnames) as well as the creation of SR-IOV virtual functions on physical network interfaces may be managed by systemd-udevd(8) according to the contents of systemd.link(5) files.

systemd-networkd will create "virtual" network devices (e.g. bridges and tunnels) based on the configuration in systemd.netdev(5) files, respecting the [Match] sections in those files.

systemd-networkd will manage network addresses and routes for any link for which it finds a .network file with an appropriate [Match] section, see systemd.network(5). For those links, it will flush existing network addresses and routes when bringing up the device (except when directed not to). Any links not matched by one of the .network files will be ignored. It is also possible to explicitly tell systemd-networkd to ignore a link by using the Unmanaged=yes option, see systemd.network(5).

When systemd-networkd exits, it generally leaves existing network devices and configuration intact. This makes it possible to transition from the initrd and to restart the service without breaking connectivity. This also means that when configuration is updated and systemd-networkd is restarted, netdev interfaces for which configuration was removed will not be dropped, and may need to be cleaned up manually.

systemd-networkd may be introspected and controlled at runtime using networkctl(1).

See org.freedesktop.network1(5) and org.freedesktop.LogControl1(5) for a description of the D-Bus API.

## CONFIGURATION FILES
The configuration files are read from the files located in the system network directory /usr/lib/systemd/network, the volatile runtime network directory /run/systemd/network and the local administration network directory /etc/systemd/network.

Networks are configured in .network files, see systemd.network(5), and virtual network devices are configured in .netdev files, see systemd.netdev(5).

## SEE ALSO
networkctl(1), systemd(1), systemd.link(5), systemd.network(5), systemd.netdev(5), systemd-networkd-wait-online.service(8), systemd-network-generator.service(8), org.freedesktop.network1(5)


systemd-resolved.service

title: systemd-resolved.service(8)

summary: Network Name Resolution manager

text:
# systemd-resolved.service(8)

## NAME
systemd-resolved.service, systemd-resolved - Network Name Resolution manager

## SYNOPSIS
systemd-resolved.service

/usr/lib/systemd/systemd-resolved

## DESCRIPTION
systemd-resolved is a system service that provides network name resolution to local applications. It implements a caching and validating DNS/DNSSEC stub resolver, as well as an LLMNR and MulticastDNS resolver and responder. Local applications may submit network name resolution requests via three interfaces:

•The native, fully-featured API systemd-resolved exposes via D-Bus, see org.freedesktop.resolve1(5) and org.freedesktop.LogControl1(5) for details. Usage of this API is generally recommended to clients as it is asynchronous and fully featured (for example, properly returns DNSSEC validation status and interface scope for addresses as necessary for supporting link-local networking).

•The native API systemd-resolved exposes via Varlink on the /run/systemd/resolve/io.systemd.Resolve AF_UNIX socket. This provides similar functionality as the D-Bus interface, but is available during the entire runtime, without requiring a running D-Bus system bus broker service.

•The glibc getaddrinfo(3) API as defined by RFC3493[1] and its related resolver functions, including gethostbyname(3). This API is widely supported, including beyond the Linux platform. In its current form it does not expose DNSSEC validation status information however, and is synchronous only. This API is backed by the glibc Name Service Switch (nss(5)). Usage of the glibc NSS module nss-resolve(8) is required in order to allow glibc's NSS resolver functions to resolve hostnames via systemd-resolved.

•Additionally, systemd-resolved provides a local DNS stub listener on the IP addresses 127.0.0.53 and 127.0.0.54 on the local loopback interface. Programs issuing DNS requests directly, bypassing any local API may be directed to this stub, in order to connect them to systemd-resolved. Note however that it is strongly recommended that local programs use the glibc NSS or bus APIs instead (as described above), as various network resolution concepts (such as link-local addressing, or LLMNR Unicode domains) cannot be mapped to the unicast DNS protocol. The DNS stub resolver on 127.0.0.53 provides the full feature set of the local resolver, which includes offering LLMNR/MulticastDNS resolution. The DNS stub resolver on 127.0.0.54 provides a more limited resolver, that operates in "proxy" mode only, i.e. it will pass most DNS messages relatively unmodified to the current upstream DNS servers and back, but not try to process the messages locally, and hence does not validate DNSSEC, or offer up LLMNR/MulticastDNS. (It will translate to DNS-over-TLS communication if needed however.)

The DNS servers contacted are determined from the global settings in /etc/systemd/resolved.conf, the per-link static settings in /etc/systemd/network/*.network files (in case systemd-networkd.service(8) is used), the per-link dynamic settings received over DHCP, information provided via resolvectl(1), and any DNS server information made available by other system services. See resolved.conf(5) and systemd.network(5) for details about systemd's own configuration files for DNS servers. To improve compatibility, /etc/resolv.conf is read in order to discover configured system DNS servers, but only if it is not a symlink to /run/systemd/resolve/stub-resolv.conf, /usr/lib/systemd/resolv.conf or /run/systemd/resolve/resolv.conf (see below).

## SYNTHETIC RECORDS
systemd-resolved synthesizes DNS resource records (RRs) for the following cases:

•The local, configured hostname is resolved to all locally configured IP addresses ordered by their scope, or — if none are configured — the IPv4 address 127.0.0.2 (which is on the local loopback interface) and the IPv6 address ::1 (which is the local host).

•The hostnames "localhost" and "localhost.localdomain" as well as any hostname ending in ".localhost" or ".localhost.localdomain" are resolved to the IP addresses 127.0.0.1 and ::1.

•The hostname "_gateway" is resolved to all current default routing gateway addresses, ordered by their metric. This assigns a stable hostname to the current gateway, useful for referencing it independently of the current network configuration state.

•The hostname "_outbound" is resolved to the local IPv4 and IPv6 addresses that are most likely used for communication with other hosts. This is the preferred source addresses of default gateways if specified, or determined by requesting a routing decision to the configured default gateways from the kernel and then using the local IP addresses selected by this decision. This hostname is only available if there is at least one local default gateway configured. This assigns a stable hostname to the local outbound IP addresses, useful for referencing them independently of the current network configuration state.

•The hostname "_localdnsstub" is resolved to the IP address 127.0.0.53, i.e. the address the local DNS stub (see above) is listening on.

•The hostname "_localdnsproxy" is resolved to the IP address 127.0.0.54, i.e. the address the local DNS proxy (see above) is listening on.

•The mappings defined in /etc/hosts are resolved to their configured addresses and back, but they will not affect lookups for non-address types (like MX). Support for /etc/hosts may be disabled with ReadEtcHosts=no, see resolved.conf(5).

## PROTOCOLS AND ROUTING
The lookup requests that systemd-resolved.service receives are routed to the available DNS servers, LLMNR, and MulticastDNS interfaces according to the following rules:

•Names for which synthetic records are generated (the local hostname, "localhost" and "localdomain", local gateway, as listed in the previous section) and addresses configured in /etc/hosts are never routed to the network and a reply is sent immediately.

•Single-label names are resolved using LLMNR on all local interfaces where LLMNR is enabled. Lookups for IPv4 addresses are only sent via LLMNR on IPv4, and lookups for IPv6 addresses are only sent via LLMNR on IPv6. Note that lookups for single-label synthesized names are not routed to LLMNR, MulticastDNS or unicast DNS.

•Queries for the address records (A and AAAA) of single-label non-synthesized names are resolved via unicast DNS using search domains. For any interface which defines search domains, such look-ups are routed to the servers defined for that interface, suffixed with each of those search domains. When global search domains are defined, such look-ups are routed to the global servers. For each search domain, queries are performed by suffixing the name with each of the search domains in turn. Additionally, lookup of single-label names via unicast DNS may be enabled with the ResolveUnicastSingleLabel=yes setting. The details of which servers are queried and how the final reply is chosen are described below. Note that this means that address queries for single-label names are never sent out to remote DNS servers by default, and resolution is only possible if search domains are defined.

•Multi-label names with the domain suffix ".local" are resolved using MulticastDNS on all local interfaces where MulticastDNS is enabled. As with LLMNR, IPv4 address lookups are sent via IPv4 and IPv6 address lookups are sent via IPv6.

•Queries for multi-label names are routed via unicast DNS on local interfaces that have a DNS server configured, plus the globally configured DNS servers if there are any. Which interfaces are used is determined by the routing logic based on search and route-only domains, described below. Note that by default, lookups for domains with the ".local" suffix are not routed to DNS servers, unless the domain is specified explicitly as routing or search domain for the DNS server and interface. This means that on networks where the ".local" domain is defined in a site-specific DNS server, explicit search or routing domains need to be configured to make lookups work within this DNS domain. Note that these days, it is generally recommended to avoid defining ".local" in a DNS server, as RFC6762[2] reserves this domain for exclusive MulticastDNS use.

•Address lookups (reverse lookups) are routed similarly to multi-label names, with the exception that addresses from the link-local address range are never routed to unicast DNS and are only resolved using LLMNR and MulticastDNS (when enabled).

If lookups are routed to multiple interfaces, the first successful response is returned (thus effectively merging the lookup zones on all matching interfaces). If the lookup failed on all interfaces, the last failing response is returned.

Routing of lookups is determined by the per-interface routing domains (search and route-only) and global search domains. See systemd.network(5) and resolvectl(1) for a description how those settings are set dynamically and the discussion of Domains= in resolved.conf(5) for a description of globally configured DNS settings.

The following query routing logic applies for unicast DNS lookups initiated by systemd-resolved.service:

•If a name to look up matches (that is: is equal to or has as suffix) any of the configured routing domains (search or route-only) of any link, or the globally configured DNS settings, "best matching" routing domain is determined: the matching one with the most labels. The query is then sent to all DNS servers of any links or the globally configured DNS servers associated with this "best matching" routing domain. (Note that more than one link might have this same "best matching" routing domain configured, in which case the query is sent to all of them in parallel). In case of single-label names, when search domains are defined, the same logic applies, except that the name is first suffixed by each of the search domains in turn. Note that this search logic does not apply to any names with at least one dot. Also see the discussion about compatibility with the traditional glibc resolver below.

•If a query does not match any configured routing domain (either per-link or global), it is sent to all DNS servers that are configured on links configured as the default route, as well as the globally configured DNS server.

•If there are no DNS servers configured on any link also configured as the default route and no global DNS server configured, one of the compiled-in fallback DNS servers is used.

•Otherwise, the unicast DNS query fails, as no suitable DNS servers can be determined.

Whether a link is the default route or not can be configured with resolvectl default-route command or DNSDefaultRoute= setting in .network files. If not configured explicitly, it is implicitly determined based on the configured DNS domains for a link: if there's a route-only domain other than "~.", it defaults to false, otherwise to true.

Effectively this means: in order to support single-label non-synthesized names, define appropriate search domains. In order to preferably route all DNS queries not explicitly matched by routing domain configuration to a specific link, configure a "~." route-only domain on it. This will ensure that other links will not be considered for these queries (unless they too carry such a routing domain). In order to route all such DNS queries to a specific link only if no other link is preferred, configure the link as the default route and do not configure a "~." route-only domain on it. Finally, in order to avoid a specific link receiving any DNS traffic not matching any of its configured routing domains, do not make it a default route.

See org.freedesktop.resolve1(5) for information about the D-Bus APIs systemd-resolved provides.

## COMPATIBILITY WITH THE TRADITIONAL GLIBC STUB RESOLVER
This section provides a short summary of differences in the resolver implemented by nss-resolve(8) together with systemd-resolved and the traditional stub resolver implemented in nss-dns.

•Some names are always resolved internally (see Synthetic Records above). Traditionally they would be resolved by nss-files if provided in /etc/hosts. But note that the details of how a query is constructed are under the control of the client library. nss-dns will first try to resolve names using search domains and even if those queries are routed to systemd-resolved, it will send them out over the network using the usual rules for multi-label name routing [3].

•Single-label names are not resolved for A and AAAA records using unicast DNS (unless overridden with ResolveUnicastSingleLabel=, see resolved.conf(5)). This is similar to the no-tld-query option being set in resolv.conf(5).

•Search domains are not used for suffixing of multi-label names. (Search domains are nevertheless used for lookup routing, for names that were originally specified as single-label or multi-label.) Any name with at least one dot is always interpreted as a FQDN. nss-dns would resolve names both as relative (using search domains) and absolute FQDN names. Some names would be resolved as relative first, and after that query has failed, as absolute, while other names would be resolved in opposite order. The ndots option in /etc/resolv.conf was used to control how many dots the name needs to have to be resolved as relative first. This stub resolver does not implement this at all: multi-label names are only resolved as FQDNs.[4]

•This resolver has a notion of the special ".local" domain used for MulticastDNS, and will not route queries with that suffix to unicast DNS servers unless explicitly configured, see above. Also, reverse lookups for link-local addresses are not sent to unicast DNS servers.

•This resolver reads and caches /etc/hosts internally. (In other words, nss-resolve replaces nss-files in addition to nss-dns). Entries in /etc/hosts have highest priority.

•This resolver also implements LLMNR and MulticastDNS in addition to the classic unicast DNS protocol, and will resolve single-label names using LLMNR (when enabled) and names ending in ".local" using MulticastDNS (when enabled).

•Environment variables $LOCALDOMAIN and $RES_OPTIONS described in resolv.conf(5) are not supported currently.

•The nss-dns resolver maintains little state between subsequent DNS queries, and for each query always talks to the first listed DNS server from /etc/resolv.conf first, and on failure continues with the next until reaching the end of the list which is when the query fails. The resolver in systemd-resolved however maintains state, and will continuously talk to the same server for all queries in a particular lookup scope until some form of error is seen at which point it will switch to the next server, and then stay with it for all queries on the scope until the next failure, and so on, eventually returning to the first configured server. This is done to optimize lookup times, in particular given that the resolver typically must first probe server feature sets when talking to a server, which takes time. This different behaviour implies that listed DNS servers per lookup scope must be equivalent in the zones they serve, so that sending a query to one of them will yield the same results as sending it to another configured DNS server.

## /ETC/RESOLV.CONF
Four modes of handling /etc/resolv.conf (see resolv.conf(5)) are supported:

•systemd-resolved maintains the /run/systemd/resolve/stub-resolv.conf file for compatibility with traditional Linux programs. This file lists the 127.0.0.53 DNS stub (see above) as the only DNS server. It also contains a list of search domains that are in use by systemd-resolved. The list of search domains is always kept up-to-date. Note that /run/systemd/resolve/stub-resolv.conf should not be used directly by applications, but only through a symlink from /etc/resolv.conf. This file may be symlinked from /etc/resolv.conf in order to connect all local clients that bypass local DNS APIs to systemd-resolved with correct search domains settings. This mode of operation is recommended.

•A static file /usr/lib/systemd/resolv.conf is provided that lists the 127.0.0.53 DNS stub (see above) as only DNS server. This file may be symlinked from /etc/resolv.conf in order to connect all local clients that bypass local DNS APIs to systemd-resolved. This file does not contain any search domains.

•systemd-resolved maintains the /run/systemd/resolve/resolv.conf file for compatibility with traditional Linux programs. This file may be symlinked from /etc/resolv.conf and is always kept up-to-date, containing information about all known DNS servers. Note the file format's limitations: it does not know a concept of per-interface DNS servers and hence only contains system-wide DNS server definitions. Note that /run/systemd/resolve/resolv.conf should not be used directly by applications, but only through a symlink from /etc/resolv.conf. If this mode of operation is used local clients that bypass any local DNS API will also bypass systemd-resolved and will talk directly to the known DNS servers.

•Alternatively, /etc/resolv.conf may be managed by other packages, in which case systemd-resolved will read it for DNS configuration data. In this mode of operation systemd-resolved is consumer rather than provider of this configuration file.

Note that the selected mode of operation for this file is detected fully automatically, depending on whether /etc/resolv.conf is a symlink to /run/systemd/resolve/resolv.conf or lists 127.0.0.53 as DNS server.

## SIGNALS
SIGUSR1

Upon reception of the SIGUSR1 process signal systemd-resolved will dump the contents of all DNS resource record caches it maintains, as well as all feature level information it learnt about configured DNS servers into the system logs. Added in version 231.

SIGUSR2

Upon reception of the SIGUSR2 process signal systemd-resolved will flush all caches it maintains. Note that it should normally not be necessary to request this explicitly – except for debugging purposes – as systemd-resolved flushes the caches automatically anyway any time the host's network configuration changes. Sending this signal to systemd-resolved is equivalent to the resolvectl flush-caches command, however the latter is recommended since it operates in a synchronous way. Added in version 231.

SIGRTMIN+1

Upon reception of the SIGRTMIN+1 process signal systemd-resolved will forget everything it learnt about the configured DNS servers. Specifically any information about server feature support is flushed out, and the server feature probing logic is restarted on the next request, starting with the most fully featured level. Note that it should normally not be necessary to request this explicitly – except for debugging purposes – as systemd-resolved automatically forgets learnt information any time the DNS server configuration changes. Sending this signal to systemd-resolved is equivalent to the resolvectl reset-server-features command, however the latter is recommended since it operates in a synchronous way. Added in version 235.

SIGHUP

Upon reception of the SIGHUP process signal systemd-resolved will flush all caches it maintains, drop all open TCP connections (if any), and reload its configuration files. Added in version 256.

## CREDENTIALS
systemd-resolved supports the service credentials logic as implemented by ImportCredential=/LoadCredential=/SetCredential= (see systemd.exec(5) for details). The following credentials are used when passed in:

network.dns, network.search_domains

May contain a space separated list of DNS server IP addresses and DNS search domains. This information is only used when no explicit configuration via /etc/systemd/resolved.conf, /etc/resolv.conf or the kernel command line has been provided. Added in version 253.

## KERNEL COMMAND LINE
systemd-resolved also honours two kernel command line options:

nameserver=, domain=

Takes the IP address of a DNS server (in case of nameserver=), and a DNS search domain (in case of domain=). May be used multiple times, to define multiple DNS servers/search domains. If either of these options are specified /etc/resolv.conf will not be read and the DNS= and Domains= settings of resolved.conf(5) will be ignored. These two kernel command line options hence override system configuration. Added in version 253.

## IP PORTS
The systemd-resolved service listens on the following IP ports:

•Port 53 on IPv4 addresses 127.0.0.53 and 127.0.0.54 (both are on the local loopback interface "lo"). This is the local DNS stub, as discussed above. Both UDP and TCP are covered.

•Port 5353 on all local addresses, both IPv4 and IPv6 (0.0.0.0 and ::0), for MulticastDNS on UDP. Note that even though the socket is bound to all local interfaces via the selected "wildcard" IP addresses, the incoming datagrams are filtered by the network interface they are coming in on, and separate MulticastDNS link-local scopes are maintained for each, taking into consideration whether MulticastDNS is enabled for the interface or not.

•Port 5355 on all local addresses, both IPv4 and IP6 (0.0.0.0 and ::0), for LLMNR, on both TCP and UDP. As with MulticastDNS filtering by incoming network interface is applied.

## SEE ALSO
systemd(1), resolved.conf(5), systemd.dns-delegate(5), systemd.dnssd(5), dnssec-trust-anchors.d(5), nss-resolve(8), resolvectl(1), resolv.conf(5), hosts(5), systemd.network(5), systemd-networkd.service(8), org.freedesktop.resolve1(5)

## NOTES
1.

RFC3493

https://tools.ietf.org/html/rfc3493

2.

RFC6762

https://tools.ietf.org/html/rfc6762

3.

For example, if /etc/resolv.conf has

```
nameserver 127.0.0.53
search foobar.com barbar.com
```

and we look up "localhost", nss-dns will send the following queries to systemd-resolved listening on 127.0.0.53:53: first "localhost.foobar.com", then "localhost.barbar.com", and finally "localhost". If (hopefully) the first two queries fail, systemd-resolved will synthesize an answer for the third query.

When using nss-dns with any search domains, it is thus crucial to always configure nss-files with higher priority and provide mappings for names that should not be resolved using search domains.

4.

There are currently more than 1500 top-level domain names defined, and new ones are added regularly, often using "attractive" names that are also likely to be used locally. Not looking up multi-label names in this fashion avoids fragility in both directions: a valid global name could be obscured by a local name, and resolution of a relative local name could suddenly break when a new top-level domain is created, or when a new subdomain of a top-level domain in registered. Resolving any given name as either relative or absolute avoids this ambiguity.


systemd-portabled.service

package: systemd-portable

title: systemd-portabled.service(8)

summary: Portable service manager

text:
# systemd-portabled.service(8)

## NAME
systemd-portabled.service, systemd-portabled - Portable service manager

## SYNOPSIS
systemd-portabled.service

/usr/lib/systemd/systemd-portabled

## DESCRIPTION
systemd-portabled is a system service that may be used to attach, detach and inspect portable service images.

Most of systemd-portabled's functionality is accessible through the portablectl(1) command.

See the Portable Services[1] page for details about the concepts this service implements.

See org.freedesktop.portable1(5) and org.freedesktop.LogControl1(5) for a description of the D-Bus API.

## SEE ALSO
systemd(1), portablectl(1), org.freedesktop.portable1(5)

## NOTES
1.

Portable Services

https://systemd.io/PORTABLE_SERVICES


systemd-time-wait-sync.service

package: systemd-timesyncd

title: systemd-time-wait-sync.service(8)

summary: Wait until kernel time is synchronized

text:
# systemd-time-wait-sync.service(8)

## NAME
systemd-time-wait-sync.service, systemd-time-wait-sync - Wait until kernel time is synchronized

## SYNOPSIS
systemd-time-wait-sync.service

/usr/lib/systemd/systemd-time-wait-sync

## DESCRIPTION
systemd-time-wait-sync is a system service that delays the start of units that are ordered after time-sync.target (see systemd.special(7) for details) until the system time has been synchronized with an accurate remote reference time source by systemd-timesyncd.service.

systemd-timesyncd.service notifies systemd-time-wait-sync about successful synchronization. systemd-time-wait-sync also tries to detect when the kernel marks the system clock as synchronized, but this detection is not reliable and is intended only as a fallback for compatibility with alternative NTP services that can be used to synchronize time (e.g., ntpd, chronyd).

## FILES
/run/systemd/timesync/synchronized

The presence of this file indicates to this service that the system clock has been synchronized. Added in version 239.

## SEE ALSO
systemd(1), systemd.special(7), systemd-timesyncd.service(8)


systemd-timesyncd.service

title: systemd-timesyncd.service(8)

summary: Network Time Synchronization

text:
# systemd-timesyncd.service(8)

## NAME
systemd-timesyncd.service, systemd-timesyncd - Network Time Synchronization

## SYNOPSIS
systemd-timesyncd.service

/usr/lib/systemd/systemd-timesyncd

## DESCRIPTION
systemd-timesyncd.service is a system service that may be used to synchronize the local system clock with a remote Network Time Protocol (NTP) server. It also saves the local time to disk every time the clock has been synchronized and uses this to possibly advance the system realtime clock on subsequent reboots to ensure it (roughly) monotonically advances even if the system lacks a battery-buffered RTC chip.

The systemd-timesyncd.service service implements SNTP only. This minimalistic service will step the system clock for large offsets or slowly adjust it for smaller deltas. Complex use cases that require full NTP support (and where SNTP is not sufficient) are not covered by systemd-timesyncd.service.

The NTP servers contacted are determined from the global settings in timesyncd.conf(5), the per-link static settings in .network files, and the per-link dynamic settings received over DHCP. See systemd.network(5) for further details.

timedatectl(1)'s set-ntp command may be used to enable and start, or disable and stop this service.

timedatectl(1)'s timesync-status or show-timesync command can be used to show the current status of this service.

Initialization of systemd-timesyncd.service delays the start of units that are ordered after time-set.target (see systemd.special(7) for details) until the local time has been updated from /var/lib/systemd/timesync/clock (see below) in order to make it roughly monotonic. It does not delay other units until synchronization with an accurate reference time sources has been reached. Use systemd-time-wait-sync.service(8) to achieve that, which will delay start of units that are ordered after time-sync.target until synchronization to an accurate reference clock is reached.

systemd and systemd-timesyncd advance the system clock to the "epoch" (the lowest date above which the system clock time is assumed to be set correctly). See "System clock epoch" section in systemd(1) for details. systemd will set the clock when initializing, but /var/lib/systemd/timesync/clock might not yet be available at that point. systemd-timesyncd will advance the clock when it is started and notices that the system clock is before the modification time of /var/lib/systemd/timesync/clock.

## FILES
/var/lib/systemd/timesync/clock

The modification time ("mtime") of this file is updated on each successful NTP synchronization or after each SaveIntervalSec= time interval, as specified in timesyncd.conf(5). If present, the modification time of this file is used for the epoch by systemd(1) and systemd-timesyncd.service.

Added in version 219.

/run/systemd/timesync/synchronized

A file that is touched on each successful synchronization to assist systemd-time-wait-sync.service(8) service and other applications in detecting synchronization to an accurate reference clock. Added in version 239.

## SEE ALSO
systemd(1), timesyncd.conf(5), systemd.network(5), systemd-networkd.service(8), systemd-time-wait-sync.service(8), systemd.special(7), timedatectl(1), localtime(5), hwclock(8)


fstab-decode

package: sysvinit

title: fstab-decode(8)

text:
# fstab-decode(8)

## NAME
fstab-decode - run a command with fstab-encoded arguments

## SYNOPSIS
fstab-decode COMMAND [ARGUMENT]...

## DESCRIPTION
fstab-decode decodes escapes (such as newline characters and other whitespace) in the specified ARGUMENTs and uses them to run COMMAND. The argument escaping uses the same rules as path escaping in /etc/fstab, /etc/mtab and /proc/mtab.

In essence fstab-decode can be used anytime we want to pass multiple parameters to a command as a list of command line arguments. It turns output like this:

```
/root
/mnt/remote-disk
/home
Into one long list of parameters, "/root /mnt/remote-disk /home". This
can be useful when trying to work with multiple filesystems at once. For
instance, we can use it to unmount multiple NFS shares. This program also
removes whitespace and other characters which might cause programs such
as mount or umount to fail.
```

## EXIT STATUS
fstab-decode exits with status 127 if COMMAND can't be run. Otherwise it exits with the status returned by COMMAND.

## EXAMPLES

```
The following example reads fstab, finds all instances of VFAT filesystems and
prints their mount points (argument 2 in the fstab file). fstab-decode then runs
the specified program, umount, and passes it the list of VFAT mountpoints.
This unmounts all VFAT partitions.
fstab-decode umount $(awk '$3 == "vfat" { print $2 }' /etc/fstab)
```

## SEE ALSO
fstab(5)


halt

title: halt(8)

summary: stop the system.

text:
# halt(8)

## NAME
halt, reboot, poweroff - stop the system.

## SYNOPSIS
/sbin/halt [-n] [-w] [-d] [-f] [-i] [-p] [-h]

/sbin/reboot [-n] [-w] [-d] [-f] [-i] [-k]

/sbin/poweroff [-n] [-w] [-d] [-f] [-i] [-h]

## DESCRIPTION
halt notes that the system is being brought down in the file /var/log/wtmp, and then either tells the kernel to halt, reboot or power-off the system.

If halt or reboot is called when the system is not in runlevel 0 or 6, in other words when it's running normally, shutdown will be invoked instead (with the -h or -r flag). For more info see the shutdown(8) manpage.

The rest of this manpage describes the behaviour in runlevels 0 and 6, that is when the systems shutdown scripts are being run.

## OPTIONS
-n

Don't sync before reboot or halt. Note that the kernel and storage drivers may still sync. This implies -d.

-w

Don't actually reboot or halt but only write the wtmp record (in the /var/log/wtmp file).

-d

Don't write the wtmp record.

-f

Force halt or reboot, don't call shutdown(8).

-i

Shut down all network interfaces just before halt or reboot. Warning: This may not work on interfaces which do not have an IP address and should ideally be handled by a network manager service.

-h

Put all hard drives on the system in stand-by mode just before halt or power-off.

-p

When halting the system, switch off the power. This is the default when halt is called as poweroff.

-k

Try to reboot using kexec, if kernel supports it.

## DIAGNOSTICS
If you're not the superuser, you will get the message `operation not permitted'.

## NOTES
Under older sysvinit releases , reboot and halt should never be called directly. From release 2.74 on halt and reboot invoke shutdown(8) if the system is not in runlevel 0 or 6. This means that if halt or reboot cannot find out the current runlevel (for example, when /var/run/utmp hasn't been initialized correctly and /var/run/runlevel does not exist) shutdown will be called, which might not be what you want. Use the -f flag if you want to do a hard halt or reboot.

The -h flag puts all hard disks in standby mode just before halt or power-off. Right now this is only implemented for IDE drives. A side effect of putting the drive in stand-by mode is that the write cache on the disk is flushed. This is important for IDE drives, since the kernel doesn't flush the write cache itself before power-off.

The halt program uses /proc/ide/hd* to find all IDE disk devices, which means that /proc needs to be mounted when halt or poweroff is called or the -h switch will do nothing.

## AUTHOR
Miquel van Smoorenburg, miquels@cistron.nl

## SEE ALSO
shutdown(8), init(8)


init

title: init(8)

summary: process control initialization

text:
# init(8)

## NAME
init, telinit - process control initialization

## SYNOPSIS
/sbin/init [ -a ] [ -s ] [ -b ] [ -z xxx ] [ 0123456Ss ]

/sbin/init [ --version ]

/sbin/telinit [ -t SECONDS ] [ 0123456sSQqabcUu ]

/sbin/telinit [ -e VAR[=VAL] ]

## DESCRIPTION

### Init
Init is the parent of all processes. Its primary role is to create processes from a script stored in the file /etc/inittab (see inittab(5)). This file usually has entries which cause init to spawn gettys on each line that users can log in. It also controls autonomous processes required by any particular system.

## RUNLEVELS
A runlevel is a software configuration of the system which allows only a selected group of processes to exist. The processes spawned by init for each of these runlevels are defined in the /etc/inittab file. Init can be in one of eight runlevels: 0–6 and S (a.k.a. s). The runlevel is changed by having a privileged user run telinit, which sends appropriate signals to init, telling it which runlevel to change to.

Runlevels S, 0, 1, and 6 are reserved. Runlevel S is used to initialize the system on boot. When starting runlevel S (on boot) or runlevel 1 (switching from a multi-user runlevel) the system is entering ``single-user mode'', after which the current runlevel is S. Runlevel 0 is used to halt the system; runlevel 6 is used to reboot the system.

After booting through S the system automatically enters one of the multi-user runlevels 2 through 5, unless there was some problem that needs to be fixed by the administrator in single-user mode. Normally after entering single-user mode the administrator performs maintenance and then reboots the system.

For more information, see the manpages for shutdown(8) and inittab(5).

Runlevels 7-9 are also valid, though not really documented. This is because "traditional" Unix variants don't use them.

Runlevels S and s are the same. Internally they are aliases for the same runlevel.

## BOOTING
After init is invoked as the last step of the kernel boot sequence, it looks for the file /etc/inittab to see if there is an entry of the type initdefault (see inittab(5)). The initdefault entry determines the initial runlevel of the system. If there is no such entry (or no /etc/inittab at all), a runlevel must be entered at the system console.

Runlevel S or s initialize the system and do not require an /etc/inittab file.

In single user mode, /sbin/sulogin is invoked on /dev/console.

When entering single user mode, init initializes the consoles stty settings to sane values. Clocal mode is set. Hardware speed and handshaking are not changed.

When entering a multi-user mode for the first time, init performs the boot and bootwait entries to allow file systems to be mounted before users can log in. Then all entries matching the runlevel are processed.

When starting a new process, init first checks whether the file /etc/initscript exists. If it does, it uses this script to start the process.

Each time a child terminates, init records the fact and the reason it died in /var/run/utmp and /var/log/wtmp, provided that these files exist.

## CHANGING RUNLEVELS
After it has spawned all of the processes specified, init waits for one of its descendant processes to die, a powerfail signal, or until it is signaled by telinit to change the system's runlevel. When one of the above three conditions occurs, it re-examines the /etc/inittab file. New entries can be added to this file at any time. However, init still waits for one of the above three conditions to occur. To provide for an instantaneous response, the telinit Q or q command can wake up init to re-examine (reload) the /etc/inittab file.

If init is not in single user mode and receives a powerfail signal (SIGPWR), it reads the file /etc/powerstatus. It then starts a command based on the contents of this file:

F(AIL)

Power is failing, UPS is providing the power. Execute the powerwait and powerfail entries.

O(K)

The power has been restored, execute the powerokwait entries.

L(OW)

The power is failing and the UPS has a low battery. Execute the powerfailnow entries.

If /etc/powerstatus doesn't exist or contains anything else then the letters F, O or L, init will behave as if it has read the letter F.

Usage of SIGPWR and /etc/powerstatus is discouraged. Someone wanting to interact with init should use the /run/initctl control channel - see the initctl manual page for more documentation about this.

When init is requested to change the runlevel, it sends the warning signal SIGTERM to all processes that are undefined in the new runlevel. It then waits 3 seconds before forcibly terminating these processes via the SIGKILL signal. Note that init assumes that all these processes (and their descendants) remain in the same process group which init originally created for them. If any process changes its process group affiliation it will not receive these signals. Such processes need to be terminated separately.

## TELINIT
/sbin/telinit is linked to /sbin/init. It takes a one-character argument and signals init to perform the appropriate action. The following arguments serve as directives to telinit:

0,1,2,3,4,5 or 6

tell init to switch to the specified run level.

a,b,c

tell init to process only those /etc/inittab file entries having runlevel a,b or c.

Q or q

tell init to re-examine the /etc/inittab file.

S or s

tell init to switch to single user mode.

U or u

tell init to re-execute itself (preserving the state). No re-examining of /etc/inittab file happens. Runlevel should be one of Ss0123456 otherwise request would be silently ignored.

telinit can tell init how long it should wait between sending processes the SIGTERM and SIGKILL signals. The default is 3 seconds, but this can be changed with the -t option.

telinit -e tells init to change the environment for processes it spawns. The argument of -e is either of the form VAR=VAL which sets variable VAR to value VAL, or of the form VAR (without an equality sign) which unsets variable VAR.

telinit can be invoked only by users with appropriate privileges.

The init binary checks if it is init or telinit by looking at its process id; the real init's process id is always 1. From this it follows that instead of calling telinit one can also just use init instead as a shortcut.

## ENVIRONMENT
Init sets the following environment variables for all its children:

PATH

/bin:/usr/bin:/sbin:/usr/sbin

INIT_VERSION

As the name says. Useful to determine if a script runs directly from init.

RUNLEVEL

The current system runlevel.

PREVLEVEL

The previous runlevel (useful after a runlevel switch).

CONSOLE

The system console. This is really inherited from the kernel; however if it is not set init will set it to /dev/console by default.

## BOOTFLAGS
It is possible to pass a number of flags to init from the boot monitor (eg. LILO or GRUB). Init accepts the following flags:

-s, S, single

Single user mode boot. In this mode /etc/inittab is examined and the bootup rc scripts are usually run before the single user mode shell is started.

1-5

Runlevel to boot into.

-b, emergency

Boot directly into a single user shell without running any other startup scripts.

-a, auto

The LILO boot loader adds the word "auto" to the command line if it booted the kernel with the default command line (without user intervention). If this is found init sets the "AUTOBOOT" environment variable to "yes". Note that you cannot use this for any security measures - of course the user could specify "auto" or -a on the command line manually.

-z xxx

The argument to -z is ignored. You can use this to expand the command line a bit, so that it takes some more space on the stack. Init can then manipulate the command line so that ps(1) shows the current runlevel.

--version

This argument, when used on its own, displays the current version of init to the console/stdout. It is a quick way to determine which init software and version is being used. After the version information is displayed, init immediately exits with a return code of zero.

## INTERFACE
Init listens on a fifo in /dev, /run/initctl, for messages. Telinit uses this to communicate with init. The interface is not very well documented or finished. Those interested should study the initreq.h file in the src/ subdirectory of the init source code tar archive.

## SIGNALS
Init reacts to several signals:

SIGHUP

Has the same effect as telinit q.

SIGUSR1

On receipt of this signals, init closes and re-opens its control fifo, /run/initctl. Useful for bootscripts when /dev is remounted.

SIGUSR2

When init receives SIGUSR2, init closes and leaves the control fifo, /run/initctl, closed. This may be used to make sure init is not holding open any files. However, it also prevents init from switching runlevels. Which means commands like shutdown no longer work. The fifo can be re-opened by sending init the SIGUSR1 signal.

SIGINT

Normally the kernel sends this signal to init when CTRL-ALT-DEL is pressed. It activates the ctrlaltdel action.

SIGWINCH

The kernel sends this signal when the KeyboardSignal key is hit. It activates the kbrequest action.

## CONFORMING TO
Init is compatible with the System V init. It works closely together with the scripts in the directories /etc/init.d and /etc/rc{runlevel}.d. If your system uses this convention, there should be a README file in the directory /etc/init.d explaining how these scripts work.

## FILES

```
/etc/inittab
/etc/initscript
/dev/console
/var/run/utmp
/var/log/wtmp
/run/initctl
```

## WARNINGS
Init assumes that processes and descendants of processes remain in the same process group which was originally created for them. If the processes change their group, init can't kill them and you may end up with two processes reading from one terminal line.

On a Debian system, entering runlevel 1 causes all processes to be killed except for kernel threads and the script that does the killing and other processes in its session. As a consequence of this, it isn't safe to return from runlevel 1 to a multi-user runlevel: daemons that were started in runlevel S and are needed for normal operation are no longer running. The system should be rebooted.

## DIAGNOSTICS
If init finds that it is continuously respawning an entry more than 10 times in 2 minutes, it will assume that there is an error in the command string, generate an error message on the system console, and refuse to respawn this entry until either 5 minutes has elapsed or it receives a signal. This prevents it from eating up system resources when someone makes a typographical error in the /etc/inittab file or the program for the entry is removed.

## AUTHOR
Miquel van Smoorenburg (miquels@cistron.nl), initial manual page by Michael Haardt (u31b3hs@pool.informatik.rwth-aachen.de).

## SEE ALSO
getty(1), login(1), sh(1), runlevel(8), shutdown(8), kill(1), initctl(5), inittab(5), initscript(5), utmp(5)


runlevel

title: runlevel(8)

text:
# runlevel(8)

## NAME
runlevel -- find the previous and current system runlevel.

## SYNOPSIS
runlevel [utmp]

## DESCRIPTION
Runlevel reads the system utmp file (typically /var/run/utmp) to locate the runlevel record, and then prints the previous and current system runlevel on its standard output, separated by a single space. If there is no previous system runlevel, the letter N will be printed instead.

If no utmp file exists, and if no runlevel record can be found in the /var/run/runlevel file, runlevel prints the word unknown and exits with an error.

Runlevel can be used in rc scripts as a substitute for the System-V who -r command. However, in newer versions of init(8) this information is also available in the environment variables RUNLEVEL and PREVLEVEL.

## OPTIONS
utmp

The name of the utmp file to read.

## SEE ALSO
init(8), utmp(5)

## AUTHOR
Miquel van Smoorenburg, miquels@cistron.nl