diff options
Diffstat (limited to 'src/grp-system/systemd')
40 files changed, 18932 insertions, 0 deletions
diff --git a/src/grp-system/systemd/50-systemd-user.xorg b/src/grp-system/systemd/50-systemd-user.xorg new file mode 100755 index 0000000000..4d49767228 --- /dev/null +++ b/src/grp-system/systemd/50-systemd-user.xorg @@ -0,0 +1,7 @@ +#!/bin/sh + +systemctl --user import-environment DISPLAY XAUTHORITY + +if which dbus-update-activation-environment >/dev/null 2>&1; then + dbus-update-activation-environment DISPLAY XAUTHORITY +fi diff --git a/src/grp-system/systemd/GNUmakefile b/src/grp-system/systemd/GNUmakefile new file mode 120000 index 0000000000..0f24a727ed --- /dev/null +++ b/src/grp-system/systemd/GNUmakefile @@ -0,0 +1 @@ +GNUmakefile
\ No newline at end of file diff --git a/src/grp-system/systemd/Makefile b/src/grp-system/systemd/Makefile new file mode 100644 index 0000000000..7f7fbb963e --- /dev/null +++ b/src/grp-system/systemd/Makefile @@ -0,0 +1,73 @@ +# -*- Mode: makefile; indent-tabs-mode: t -*- +# +# This file is part of systemd. +# +# Copyright 2010-2012 Lennart Poettering +# Copyright 2010-2012 Kay Sievers +# Copyright 2013 Zbigniew Jędrzejewski-Szmek +# Copyright 2013 David Strauss +# Copyright 2016 Luke Shumaker +# +# systemd is free software; you can redistribute it and/or modify it +# under the terms of the GNU Lesser General Public License as published by +# the Free Software Foundation; either version 2.1 of the License, or +# (at your option) any later version. +# +# systemd is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public License +# along with systemd; If not, see <http://www.gnu.org/licenses/>. +include $(dir $(lastword $(MAKEFILE_LIST)))/../../../config.mk +include $(topsrcdir)/build-aux/Makefile.head.mk + +rootlibexec_PROGRAMS += systemd +systemd_SOURCES = \ + src/core/main.c + +systemd_CFLAGS = \ + $(SECCOMP_CFLAGS) \ + $(MOUNT_CFLAGS) + +systemd_LDADD = \ + libcore.la + +dist_pkgsysconf_DATA += \ + src/core/system.conf \ + src/core/user.conf + +dist_dbuspolicy_DATA += \ + src/core/org.freedesktop.systemd1.conf + +dist_dbussystemservice_DATA += \ + src/core/org.freedesktop.systemd1.service + +polkitpolicy_in_in_files += \ + src/core/org.freedesktop.systemd1.policy.in.in + +pkgconfigdata_DATA += \ + src/core/systemd.pc + +nodist_rpmmacros_DATA = \ + src/core/macros.systemd + +BUILT_SOURCES += \ + src/core/triggers.systemd + +EXTRA_DIST += \ + src/core/systemd.pc.in \ + src/core/macros.systemd.in \ + src/core/triggers.systemd.in + +dist_xinitrc_SCRIPTS = \ + xorg/50-systemd-user.sh + +dist_systemunit_DATA_busnames += \ + units/org.freedesktop.systemd1.busname + +BUSNAMES_TARGET_WANTS += \ + org.freedesktop.systemd1.busname + +include $(topsrcdir)/build-aux/Makefile.tail.mk diff --git a/src/grp-system/systemd/macros.systemd.in b/src/grp-system/systemd/macros.systemd.in new file mode 100644 index 0000000000..6e8a3b3e3d --- /dev/null +++ b/src/grp-system/systemd/macros.systemd.in @@ -0,0 +1,113 @@ +# -*- Mode: rpm-spec; indent-tabs-mode: nil -*- */ +# +# This file is part of systemd. +# +# Copyright 2012 Lennart Poettering +# +# systemd is free software; you can redistribute it and/or modify it +# under the terms of the GNU Lesser General Public License as published by +# the Free Software Foundation; either version 2.1 of the License, or +# (at your option) any later version. +# +# systemd is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public License +# along with systemd; If not, see <http://www.gnu.org/licenses/>. + +# RPM macros for packages installing systemd unit files + +%_unitdir @systemunitdir@ +%_userunitdir @userunitdir@ +%_presetdir @systempresetdir@ +%_udevhwdbdir @udevhwdbdir@ +%_udevrulesdir @udevrulesdir@ +%_journalcatalogdir @catalogdir@ +%_tmpfilesdir @tmpfilesdir@ +%_sysusersdir @sysusersdir@ +%_sysctldir @sysctldir@ +%_binfmtdir @binfmtdir@ +%_systemdgeneratordir @systemgeneratordir@ +%_systemdusergeneratordir @usergeneratordir@ + +%systemd_requires \ +Requires(post): systemd \ +Requires(preun): systemd \ +Requires(postun): systemd \ +%{nil} + +%systemd_ordering \ +OrderWithRequires(post): systemd \ +OrderWithRequires(preun): systemd \ +OrderWithRequires(postun): systemd \ +%{nil} + +%systemd_post() \ +if [ $1 -eq 1 ] ; then \ + # Initial installation \ + systemctl --no-reload preset %{?*} >/dev/null 2>&1 || : \ +fi \ +%{nil} + +%systemd_user_post() %{expand:%systemd_post \\--user \\--global %%{?*}} + +%systemd_preun() \ +if [ $1 -eq 0 ] ; then \ + # Package removal, not upgrade \ + systemctl --no-reload disable --now %{?*} > /dev/null 2>&1 || : \ +fi \ +%{nil} + +%systemd_user_preun() \ +if [ $1 -eq 0 ] ; then \ + # Package removal, not upgrade \ + systemctl --no-reload --user --global disable %{?*} > /dev/null 2>&1 || : \ +fi \ +%{nil} + +%systemd_postun() %{nil} + +%systemd_user_postun() %{nil} + +%systemd_postun_with_restart() \ +if [ $1 -ge 1 ] ; then \ + # Package upgrade, not uninstall \ + systemctl try-restart %{?*} >/dev/null 2>&1 || : \ +fi \ +%{nil} + +%systemd_user_postun_with_restart() %{nil} + +%udev_hwdb_update() \ +udevadm hwdb --update >/dev/null 2>&1 || : \ +%{nil} + +%udev_rules_update() \ +udevadm control --reload >/dev/null 2>&1 || : \ +%{nil} + +%journal_catalog_update() \ +journalctl --update-catalog >/dev/null 2>&1 || : \ +%{nil} + +%tmpfiles_create() \ +systemd-tmpfiles --create %{?*} >/dev/null 2>&1 || : \ +%{nil} + +%sysusers_create() \ +systemd-sysusers %{?*} >/dev/null 2>&1 || : \ +%{nil} + +%sysusers_create_inline() \ +echo %{?*} | systemd-sysusers - >/dev/null 2>&1 || : \ +%{nil} + +%sysctl_apply() \ +@rootlibexecdir@/systemd-sysctl %{?*} >/dev/null 2>&1 || : \ +%{nil} + +%binfmt_apply() \ +@rootlibexecdir@/systemd-binfmt %{?*} >/dev/null 2>&1 || : \ +%{nil} diff --git a/src/grp-system/systemd/main.c b/src/grp-system/systemd/main.c new file mode 100644 index 0000000000..be97cef6a1 --- /dev/null +++ b/src/grp-system/systemd/main.c @@ -0,0 +1,2204 @@ +/*** + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +***/ + +#include <errno.h> +#include <fcntl.h> +#include <getopt.h> +#include <signal.h> +#include <stdio.h> +#include <string.h> +#include <sys/mount.h> +#include <sys/prctl.h> +#include <sys/reboot.h> +#include <sys/stat.h> +#include <unistd.h> +#ifdef HAVE_SECCOMP +#include <seccomp.h> +#endif +#ifdef HAVE_VALGRIND_VALGRIND_H +#include <valgrind/valgrind.h> +#endif + +#include <systemd/sd-bus.h> +#include <systemd/sd-daemon.h> + +#include "core/dbus-manager.h" +#include "core/hostname-setup.h" +#include "core/ima-setup.h" +#include "core/killall.h" +#include "core/kmod-setup.h" +#include "core/load-fragment.h" +#include "core/loopback-setup.h" +#include "core/machine-id-setup.h" +#include "core/manager.h" +#include "core/mount-setup.h" +#include "sd-bus/bus-error.h" +#include "sd-bus/bus-util.h" +#include "systemd-basic/alloc-util.h" +#include "systemd-basic/architecture.h" +#include "systemd-basic/build.h" +#include "systemd-basic/capability-util.h" +#include "systemd-basic/clock-util.h" +#include "systemd-basic/cpu-set-util.h" +#include "systemd-basic/def.h" +#include "systemd-basic/env-util.h" +#include "systemd-basic/fd-util.h" +#include "systemd-basic/fileio.h" +#include "systemd-basic/formats-util.h" +#include "systemd-basic/fs-util.h" +#include "systemd-basic/log.h" +#include "systemd-basic/missing.h" +#include "systemd-basic/parse-util.h" +#include "systemd-basic/proc-cmdline.h" +#include "systemd-basic/process-util.h" +#include "systemd-basic/raw-clone.h" +#include "systemd-basic/rlimit-util.h" +#include "systemd-shared/conf-parser.h" +#include "systemd-shared/fdset.h" +#include "systemd-shared/pager.h" +#ifdef HAVE_SECCOMP +#include "systemd-shared/seccomp-util.h" +#endif +#include "core/emergency-action.h" +#include "core/selinux-setup.h" +#include "core/smack-setup.h" +#include "systemd-basic/selinux-util.h" +#include "systemd-basic/signal-util.h" +#include "systemd-basic/special.h" +#include "systemd-basic/stat-util.h" +#include "systemd-basic/stdio-util.h" +#include "systemd-basic/strv.h" +#include "systemd-basic/terminal-util.h" +#include "systemd-basic/umask-util.h" +#include "systemd-basic/user-util.h" +#include "systemd-basic/virt.h" +#include "systemd-shared/switch-root.h" +#include "systemd-shared/watchdog.h" + +static enum { + ACTION_RUN, + ACTION_HELP, + ACTION_VERSION, + ACTION_TEST, + ACTION_DUMP_CONFIGURATION_ITEMS +} arg_action = ACTION_RUN; +static char *arg_default_unit = NULL; +static bool arg_system = false; +static bool arg_dump_core = true; +static int arg_crash_chvt = -1; +static bool arg_crash_shell = false; +static bool arg_crash_reboot = false; +static bool arg_confirm_spawn = false; +static ShowStatus arg_show_status = _SHOW_STATUS_UNSET; +static bool arg_switched_root = false; +static bool arg_no_pager = false; +static char ***arg_join_controllers = NULL; +static ExecOutput arg_default_std_output = EXEC_OUTPUT_JOURNAL; +static ExecOutput arg_default_std_error = EXEC_OUTPUT_INHERIT; +static usec_t arg_default_restart_usec = DEFAULT_RESTART_USEC; +static usec_t arg_default_timeout_start_usec = DEFAULT_TIMEOUT_USEC; +static usec_t arg_default_timeout_stop_usec = DEFAULT_TIMEOUT_USEC; +static usec_t arg_default_start_limit_interval = DEFAULT_START_LIMIT_INTERVAL; +static unsigned arg_default_start_limit_burst = DEFAULT_START_LIMIT_BURST; +static usec_t arg_runtime_watchdog = 0; +static usec_t arg_shutdown_watchdog = 10 * USEC_PER_MINUTE; +static char **arg_default_environment = NULL; +static struct rlimit *arg_default_rlimit[_RLIMIT_MAX] = {}; +static uint64_t arg_capability_bounding_set = CAP_ALL; +static nsec_t arg_timer_slack_nsec = NSEC_INFINITY; +static usec_t arg_default_timer_accuracy_usec = 1 * USEC_PER_MINUTE; +static Set* arg_syscall_archs = NULL; +static FILE* arg_serialization = NULL; +static bool arg_default_cpu_accounting = false; +static bool arg_default_io_accounting = false; +static bool arg_default_blockio_accounting = false; +static bool arg_default_memory_accounting = false; +static bool arg_default_tasks_accounting = true; +static uint64_t arg_default_tasks_max = UINT64_MAX; +static sd_id128_t arg_machine_id = {}; +static EmergencyAction arg_cad_burst_action = EMERGENCY_ACTION_REBOOT_FORCE; + +noreturn static void freeze_or_reboot(void) { + + if (arg_crash_reboot) { + log_notice("Rebooting in 10s..."); + (void) sleep(10); + + log_notice("Rebooting now..."); + (void) reboot(RB_AUTOBOOT); + log_emergency_errno(errno, "Failed to reboot: %m"); + } + + log_emergency("Freezing execution."); + freeze(); +} + +noreturn static void crash(int sig) { + struct sigaction sa; + pid_t pid; + + if (getpid() != 1) + /* Pass this on immediately, if this is not PID 1 */ + (void) raise(sig); + else if (!arg_dump_core) + log_emergency("Caught <%s>, not dumping core.", signal_to_string(sig)); + else { + sa = (struct sigaction) { + .sa_handler = nop_signal_handler, + .sa_flags = SA_NOCLDSTOP|SA_RESTART, + }; + + /* We want to wait for the core process, hence let's enable SIGCHLD */ + (void) sigaction(SIGCHLD, &sa, NULL); + + pid = raw_clone(SIGCHLD); + if (pid < 0) + log_emergency_errno(errno, "Caught <%s>, cannot fork for core dump: %m", signal_to_string(sig)); + else if (pid == 0) { + /* Enable default signal handler for core dump */ + + sa = (struct sigaction) { + .sa_handler = SIG_DFL, + }; + (void) sigaction(sig, &sa, NULL); + + /* Don't limit the coredump size */ + (void) setrlimit(RLIMIT_CORE, &RLIMIT_MAKE_CONST(RLIM_INFINITY)); + + /* Just to be sure... */ + (void) chdir("/"); + + /* Raise the signal again */ + pid = raw_getpid(); + (void) kill(pid, sig); /* raise() would kill the parent */ + + assert_not_reached("We shouldn't be here..."); + _exit(EXIT_FAILURE); + } else { + siginfo_t status; + int r; + + /* Order things nicely. */ + r = wait_for_terminate(pid, &status); + if (r < 0) + log_emergency_errno(r, "Caught <%s>, waitpid() failed: %m", signal_to_string(sig)); + else if (status.si_code != CLD_DUMPED) + log_emergency("Caught <%s>, core dump failed (child "PID_FMT", code=%s, status=%i/%s).", + signal_to_string(sig), + pid, sigchld_code_to_string(status.si_code), + status.si_status, + strna(status.si_code == CLD_EXITED + ? exit_status_to_string(status.si_status, EXIT_STATUS_MINIMAL) + : signal_to_string(status.si_status))); + else + log_emergency("Caught <%s>, dumped core as pid "PID_FMT".", signal_to_string(sig), pid); + } + } + + if (arg_crash_chvt >= 0) + (void) chvt(arg_crash_chvt); + + sa = (struct sigaction) { + .sa_handler = SIG_IGN, + .sa_flags = SA_NOCLDSTOP|SA_NOCLDWAIT|SA_RESTART, + }; + + /* Let the kernel reap children for us */ + (void) sigaction(SIGCHLD, &sa, NULL); + + if (arg_crash_shell) { + log_notice("Executing crash shell in 10s..."); + (void) sleep(10); + + pid = raw_clone(SIGCHLD); + if (pid < 0) + log_emergency_errno(errno, "Failed to fork off crash shell: %m"); + else if (pid == 0) { + (void) setsid(); + (void) make_console_stdio(); + (void) execle("/bin/sh", "/bin/sh", NULL, environ); + + log_emergency_errno(errno, "execle() failed: %m"); + _exit(EXIT_FAILURE); + } else { + log_info("Spawned crash shell as PID "PID_FMT".", pid); + (void) wait_for_terminate(pid, NULL); + } + } + + freeze_or_reboot(); +} + +static void install_crash_handler(void) { + static const struct sigaction sa = { + .sa_handler = crash, + .sa_flags = SA_NODEFER, /* So that we can raise the signal again from the signal handler */ + }; + int r; + + /* We ignore the return value here, since, we don't mind if we + * cannot set up a crash handler */ + r = sigaction_many(&sa, SIGNALS_CRASH_HANDLER, -1); + if (r < 0) + log_debug_errno(r, "I had trouble setting up the crash handler, ignoring: %m"); +} + +static int console_setup(void) { + _cleanup_close_ int tty_fd = -1; + int r; + + tty_fd = open_terminal("/dev/console", O_WRONLY|O_NOCTTY|O_CLOEXEC); + if (tty_fd < 0) + return log_error_errno(tty_fd, "Failed to open /dev/console: %m"); + + /* We don't want to force text mode. plymouth may be showing + * pictures already from initrd. */ + r = reset_terminal_fd(tty_fd, false); + if (r < 0) + return log_error_errno(r, "Failed to reset /dev/console: %m"); + + return 0; +} + +static int parse_crash_chvt(const char *value) { + int b; + + if (safe_atoi(value, &arg_crash_chvt) >= 0) + return 0; + + b = parse_boolean(value); + if (b < 0) + return b; + + if (b > 0) + arg_crash_chvt = 0; /* switch to where kmsg goes */ + else + arg_crash_chvt = -1; /* turn off switching */ + + return 0; +} + +static int set_machine_id(const char *m) { + sd_id128_t t; + assert(m); + + if (sd_id128_from_string(m, &t) < 0) + return -EINVAL; + + if (sd_id128_is_null(t)) + return -EINVAL; + + arg_machine_id = t; + return 0; +} + +static int parse_proc_cmdline_item(const char *key, const char *value, void *data) { + + int r; + + assert(key); + + if (streq(key, "systemd.unit") && value) { + + if (!in_initrd()) + return free_and_strdup(&arg_default_unit, value); + + } else if (streq(key, "rd.systemd.unit") && value) { + + if (in_initrd()) + return free_and_strdup(&arg_default_unit, value); + + } else if (streq(key, "systemd.dump_core") && value) { + + r = parse_boolean(value); + if (r < 0) + log_warning("Failed to parse dump core switch %s. Ignoring.", value); + else + arg_dump_core = r; + + } else if (streq(key, "systemd.crash_chvt") && value) { + + if (parse_crash_chvt(value) < 0) + log_warning("Failed to parse crash chvt switch %s. Ignoring.", value); + + } else if (streq(key, "systemd.crash_shell") && value) { + + r = parse_boolean(value); + if (r < 0) + log_warning("Failed to parse crash shell switch %s. Ignoring.", value); + else + arg_crash_shell = r; + + } else if (streq(key, "systemd.crash_reboot") && value) { + + r = parse_boolean(value); + if (r < 0) + log_warning("Failed to parse crash reboot switch %s. Ignoring.", value); + else + arg_crash_reboot = r; + + } else if (streq(key, "systemd.confirm_spawn") && value) { + + r = parse_boolean(value); + if (r < 0) + log_warning("Failed to parse confirm spawn switch %s. Ignoring.", value); + else + arg_confirm_spawn = r; + + } else if (streq(key, "systemd.show_status") && value) { + + r = parse_show_status(value, &arg_show_status); + if (r < 0) + log_warning("Failed to parse show status switch %s. Ignoring.", value); + + } else if (streq(key, "systemd.default_standard_output") && value) { + + r = exec_output_from_string(value); + if (r < 0) + log_warning("Failed to parse default standard output switch %s. Ignoring.", value); + else + arg_default_std_output = r; + + } else if (streq(key, "systemd.default_standard_error") && value) { + + r = exec_output_from_string(value); + if (r < 0) + log_warning("Failed to parse default standard error switch %s. Ignoring.", value); + else + arg_default_std_error = r; + + } else if (streq(key, "systemd.setenv") && value) { + + if (env_assignment_is_valid(value)) { + char **env; + + env = strv_env_set(arg_default_environment, value); + if (env) + arg_default_environment = env; + else + log_warning_errno(ENOMEM, "Setting environment variable '%s' failed, ignoring: %m", value); + } else + log_warning("Environment variable name '%s' is not valid. Ignoring.", value); + + } else if (streq(key, "systemd.machine_id") && value) { + + r = set_machine_id(value); + if (r < 0) + log_warning("MachineID '%s' is not valid. Ignoring.", value); + + } else if (streq(key, "quiet") && !value) { + + if (arg_show_status == _SHOW_STATUS_UNSET) + arg_show_status = SHOW_STATUS_AUTO; + + } else if (streq(key, "debug") && !value) { + + /* Note that log_parse_environment() handles 'debug' + * too, and sets the log level to LOG_DEBUG. */ + + if (detect_container() > 0) + log_set_target(LOG_TARGET_CONSOLE); + + } else if (!value) { + const char *target; + + /* SysV compatibility */ + target = runlevel_to_target(key); + if (target) + return free_and_strdup(&arg_default_unit, target); + + } else if (streq(key, "systemd.default_timeout_start_sec") && value) { + + r = parse_sec(value, &arg_default_timeout_start_usec); + if (r < 0) + log_warning_errno(r, "Failed to parse default start timeout: %s, ignoring.", value); + + if (arg_default_timeout_start_usec <= 0) + arg_default_timeout_start_usec = USEC_INFINITY; + } + + return 0; +} + +#define DEFINE_SETTER(name, func, descr) \ + static int name(const char *unit, \ + const char *filename, \ + unsigned line, \ + const char *section, \ + unsigned section_line, \ + const char *lvalue, \ + int ltype, \ + const char *rvalue, \ + void *data, \ + void *userdata) { \ + \ + int r; \ + \ + assert(filename); \ + assert(lvalue); \ + assert(rvalue); \ + \ + r = func(rvalue); \ + if (r < 0) \ + log_syntax(unit, LOG_ERR, filename, line, r, \ + "Invalid " descr "'%s': %m", \ + rvalue); \ + \ + return 0; \ + } + +DEFINE_SETTER(config_parse_level2, log_set_max_level_from_string, "log level") +DEFINE_SETTER(config_parse_target, log_set_target_from_string, "target") +DEFINE_SETTER(config_parse_color, log_show_color_from_string, "color" ) +DEFINE_SETTER(config_parse_location, log_show_location_from_string, "location") + +static int config_parse_cpu_affinity2( + const char *unit, + const char *filename, + unsigned line, + const char *section, + unsigned section_line, + const char *lvalue, + int ltype, + const char *rvalue, + void *data, + void *userdata) { + + _cleanup_cpu_free_ cpu_set_t *c = NULL; + int ncpus; + + ncpus = parse_cpu_set_and_warn(rvalue, &c, unit, filename, line, lvalue); + if (ncpus < 0) + return ncpus; + + if (sched_setaffinity(0, CPU_ALLOC_SIZE(ncpus), c) < 0) + log_warning("Failed to set CPU affinity: %m"); + + return 0; +} + +static int config_parse_show_status( + const char* unit, + const char *filename, + unsigned line, + const char *section, + unsigned section_line, + const char *lvalue, + int ltype, + const char *rvalue, + void *data, + void *userdata) { + + int k; + ShowStatus *b = data; + + assert(filename); + assert(lvalue); + assert(rvalue); + assert(data); + + k = parse_show_status(rvalue, b); + if (k < 0) { + log_syntax(unit, LOG_ERR, filename, line, k, "Failed to parse show status setting, ignoring: %s", rvalue); + return 0; + } + + return 0; +} + +static int config_parse_crash_chvt( + const char* unit, + const char *filename, + unsigned line, + const char *section, + unsigned section_line, + const char *lvalue, + int ltype, + const char *rvalue, + void *data, + void *userdata) { + + int r; + + assert(filename); + assert(lvalue); + assert(rvalue); + + r = parse_crash_chvt(rvalue); + if (r < 0) { + log_syntax(unit, LOG_ERR, filename, line, r, "Failed to parse CrashChangeVT= setting, ignoring: %s", rvalue); + return 0; + } + + return 0; +} + +static int config_parse_join_controllers(const char *unit, + const char *filename, + unsigned line, + const char *section, + unsigned section_line, + const char *lvalue, + int ltype, + const char *rvalue, + void *data, + void *userdata) { + + const char *whole_rvalue = rvalue; + unsigned n = 0; + + assert(filename); + assert(lvalue); + assert(rvalue); + + arg_join_controllers = strv_free_free(arg_join_controllers); + + for (;;) { + _cleanup_free_ char *word = NULL; + char **l; + int r; + + r = extract_first_word(&rvalue, &word, WHITESPACE, EXTRACT_QUOTES); + if (r < 0) { + log_syntax(unit, LOG_ERR, filename, line, r, "Invalid value for %s: %s", lvalue, whole_rvalue); + return r; + } + if (r == 0) + break; + + l = strv_split(word, ","); + if (!l) + return log_oom(); + strv_uniq(l); + + if (strv_length(l) <= 1) { + strv_free(l); + continue; + } + + if (!arg_join_controllers) { + arg_join_controllers = new(char**, 2); + if (!arg_join_controllers) { + strv_free(l); + return log_oom(); + } + + arg_join_controllers[0] = l; + arg_join_controllers[1] = NULL; + + n = 1; + } else { + char ***a; + char ***t; + + t = new0(char**, n+2); + if (!t) { + strv_free(l); + return log_oom(); + } + + n = 0; + + for (a = arg_join_controllers; *a; a++) { + + if (strv_overlap(*a, l)) { + if (strv_extend_strv(&l, *a, false) < 0) { + strv_free(l); + strv_free_free(t); + return log_oom(); + } + + } else { + char **c; + + c = strv_copy(*a); + if (!c) { + strv_free(l); + strv_free_free(t); + return log_oom(); + } + + t[n++] = c; + } + } + + t[n++] = strv_uniq(l); + + strv_free_free(arg_join_controllers); + arg_join_controllers = t; + } + } + if (!isempty(rvalue)) + log_syntax(unit, LOG_ERR, filename, line, 0, "Trailing garbage, ignoring."); + + return 0; +} + +static int parse_config_file(void) { + + const ConfigTableItem items[] = { + { "Manager", "LogLevel", config_parse_level2, 0, NULL }, + { "Manager", "LogTarget", config_parse_target, 0, NULL }, + { "Manager", "LogColor", config_parse_color, 0, NULL }, + { "Manager", "LogLocation", config_parse_location, 0, NULL }, + { "Manager", "DumpCore", config_parse_bool, 0, &arg_dump_core }, + { "Manager", "CrashChVT", /* legacy */ config_parse_crash_chvt, 0, NULL }, + { "Manager", "CrashChangeVT", config_parse_crash_chvt, 0, NULL }, + { "Manager", "CrashShell", config_parse_bool, 0, &arg_crash_shell }, + { "Manager", "CrashReboot", config_parse_bool, 0, &arg_crash_reboot }, + { "Manager", "ShowStatus", config_parse_show_status, 0, &arg_show_status }, + { "Manager", "CPUAffinity", config_parse_cpu_affinity2, 0, NULL }, + { "Manager", "JoinControllers", config_parse_join_controllers, 0, &arg_join_controllers }, + { "Manager", "RuntimeWatchdogSec", config_parse_sec, 0, &arg_runtime_watchdog }, + { "Manager", "ShutdownWatchdogSec", config_parse_sec, 0, &arg_shutdown_watchdog }, + { "Manager", "CapabilityBoundingSet", config_parse_capability_set, 0, &arg_capability_bounding_set }, +#ifdef HAVE_SECCOMP + { "Manager", "SystemCallArchitectures", config_parse_syscall_archs, 0, &arg_syscall_archs }, +#endif + { "Manager", "TimerSlackNSec", config_parse_nsec, 0, &arg_timer_slack_nsec }, + { "Manager", "DefaultTimerAccuracySec", config_parse_sec, 0, &arg_default_timer_accuracy_usec }, + { "Manager", "DefaultStandardOutput", config_parse_output, 0, &arg_default_std_output }, + { "Manager", "DefaultStandardError", config_parse_output, 0, &arg_default_std_error }, + { "Manager", "DefaultTimeoutStartSec", config_parse_sec, 0, &arg_default_timeout_start_usec }, + { "Manager", "DefaultTimeoutStopSec", config_parse_sec, 0, &arg_default_timeout_stop_usec }, + { "Manager", "DefaultRestartSec", config_parse_sec, 0, &arg_default_restart_usec }, + { "Manager", "DefaultStartLimitInterval", config_parse_sec, 0, &arg_default_start_limit_interval }, /* obsolete alias */ + { "Manager", "DefaultStartLimitIntervalSec",config_parse_sec, 0, &arg_default_start_limit_interval }, + { "Manager", "DefaultStartLimitBurst", config_parse_unsigned, 0, &arg_default_start_limit_burst }, + { "Manager", "DefaultEnvironment", config_parse_environ, 0, &arg_default_environment }, + { "Manager", "DefaultLimitCPU", config_parse_limit, RLIMIT_CPU, arg_default_rlimit }, + { "Manager", "DefaultLimitFSIZE", config_parse_limit, RLIMIT_FSIZE, arg_default_rlimit }, + { "Manager", "DefaultLimitDATA", config_parse_limit, RLIMIT_DATA, arg_default_rlimit }, + { "Manager", "DefaultLimitSTACK", config_parse_limit, RLIMIT_STACK, arg_default_rlimit }, + { "Manager", "DefaultLimitCORE", config_parse_limit, RLIMIT_CORE, arg_default_rlimit }, + { "Manager", "DefaultLimitRSS", config_parse_limit, RLIMIT_RSS, arg_default_rlimit }, + { "Manager", "DefaultLimitNOFILE", config_parse_limit, RLIMIT_NOFILE, arg_default_rlimit }, + { "Manager", "DefaultLimitAS", config_parse_limit, RLIMIT_AS, arg_default_rlimit }, + { "Manager", "DefaultLimitNPROC", config_parse_limit, RLIMIT_NPROC, arg_default_rlimit }, + { "Manager", "DefaultLimitMEMLOCK", config_parse_limit, RLIMIT_MEMLOCK, arg_default_rlimit }, + { "Manager", "DefaultLimitLOCKS", config_parse_limit, RLIMIT_LOCKS, arg_default_rlimit }, + { "Manager", "DefaultLimitSIGPENDING", config_parse_limit, RLIMIT_SIGPENDING, arg_default_rlimit }, + { "Manager", "DefaultLimitMSGQUEUE", config_parse_limit, RLIMIT_MSGQUEUE, arg_default_rlimit }, + { "Manager", "DefaultLimitNICE", config_parse_limit, RLIMIT_NICE, arg_default_rlimit }, + { "Manager", "DefaultLimitRTPRIO", config_parse_limit, RLIMIT_RTPRIO, arg_default_rlimit }, + { "Manager", "DefaultLimitRTTIME", config_parse_limit, RLIMIT_RTTIME, arg_default_rlimit }, + { "Manager", "DefaultCPUAccounting", config_parse_bool, 0, &arg_default_cpu_accounting }, + { "Manager", "DefaultIOAccounting", config_parse_bool, 0, &arg_default_io_accounting }, + { "Manager", "DefaultBlockIOAccounting", config_parse_bool, 0, &arg_default_blockio_accounting }, + { "Manager", "DefaultMemoryAccounting", config_parse_bool, 0, &arg_default_memory_accounting }, + { "Manager", "DefaultTasksAccounting", config_parse_bool, 0, &arg_default_tasks_accounting }, + { "Manager", "DefaultTasksMax", config_parse_tasks_max, 0, &arg_default_tasks_max }, + { "Manager", "CtrlAltDelBurstAction", config_parse_emergency_action, 0, &arg_cad_burst_action }, + {} + }; + + const char *fn, *conf_dirs_nulstr; + + fn = arg_system ? + PKGSYSCONFDIR "/system.conf" : + PKGSYSCONFDIR "/user.conf"; + + conf_dirs_nulstr = arg_system ? + CONF_PATHS_NULSTR("systemd/system.conf.d") : + CONF_PATHS_NULSTR("systemd/user.conf.d"); + + config_parse_many_nulstr(fn, conf_dirs_nulstr, "Manager\0", config_item_table_lookup, items, false, NULL); + + /* Traditionally "0" was used to turn off the default unit timeouts. Fix this up so that we used USEC_INFINITY + * like everywhere else. */ + if (arg_default_timeout_start_usec <= 0) + arg_default_timeout_start_usec = USEC_INFINITY; + if (arg_default_timeout_stop_usec <= 0) + arg_default_timeout_stop_usec = USEC_INFINITY; + + return 0; +} + +static void manager_set_defaults(Manager *m) { + + assert(m); + + m->default_timer_accuracy_usec = arg_default_timer_accuracy_usec; + m->default_std_output = arg_default_std_output; + m->default_std_error = arg_default_std_error; + m->default_timeout_start_usec = arg_default_timeout_start_usec; + m->default_timeout_stop_usec = arg_default_timeout_stop_usec; + m->default_restart_usec = arg_default_restart_usec; + m->default_start_limit_interval = arg_default_start_limit_interval; + m->default_start_limit_burst = arg_default_start_limit_burst; + m->default_cpu_accounting = arg_default_cpu_accounting; + m->default_io_accounting = arg_default_io_accounting; + m->default_blockio_accounting = arg_default_blockio_accounting; + m->default_memory_accounting = arg_default_memory_accounting; + m->default_tasks_accounting = arg_default_tasks_accounting; + m->default_tasks_max = arg_default_tasks_max; + + manager_set_default_rlimits(m, arg_default_rlimit); + manager_environment_add(m, NULL, arg_default_environment); +} + +static int parse_argv(int argc, char *argv[]) { + + enum { + ARG_LOG_LEVEL = 0x100, + ARG_LOG_TARGET, + ARG_LOG_COLOR, + ARG_LOG_LOCATION, + ARG_UNIT, + ARG_SYSTEM, + ARG_USER, + ARG_TEST, + ARG_NO_PAGER, + ARG_VERSION, + ARG_DUMP_CONFIGURATION_ITEMS, + ARG_DUMP_CORE, + ARG_CRASH_CHVT, + ARG_CRASH_SHELL, + ARG_CRASH_REBOOT, + ARG_CONFIRM_SPAWN, + ARG_SHOW_STATUS, + ARG_DESERIALIZE, + ARG_SWITCHED_ROOT, + ARG_DEFAULT_STD_OUTPUT, + ARG_DEFAULT_STD_ERROR, + ARG_MACHINE_ID + }; + + static const struct option options[] = { + { "log-level", required_argument, NULL, ARG_LOG_LEVEL }, + { "log-target", required_argument, NULL, ARG_LOG_TARGET }, + { "log-color", optional_argument, NULL, ARG_LOG_COLOR }, + { "log-location", optional_argument, NULL, ARG_LOG_LOCATION }, + { "unit", required_argument, NULL, ARG_UNIT }, + { "system", no_argument, NULL, ARG_SYSTEM }, + { "user", no_argument, NULL, ARG_USER }, + { "test", no_argument, NULL, ARG_TEST }, + { "no-pager", no_argument, NULL, ARG_NO_PAGER }, + { "help", no_argument, NULL, 'h' }, + { "version", no_argument, NULL, ARG_VERSION }, + { "dump-configuration-items", no_argument, NULL, ARG_DUMP_CONFIGURATION_ITEMS }, + { "dump-core", optional_argument, NULL, ARG_DUMP_CORE }, + { "crash-chvt", required_argument, NULL, ARG_CRASH_CHVT }, + { "crash-shell", optional_argument, NULL, ARG_CRASH_SHELL }, + { "crash-reboot", optional_argument, NULL, ARG_CRASH_REBOOT }, + { "confirm-spawn", optional_argument, NULL, ARG_CONFIRM_SPAWN }, + { "show-status", optional_argument, NULL, ARG_SHOW_STATUS }, + { "deserialize", required_argument, NULL, ARG_DESERIALIZE }, + { "switched-root", no_argument, NULL, ARG_SWITCHED_ROOT }, + { "default-standard-output", required_argument, NULL, ARG_DEFAULT_STD_OUTPUT, }, + { "default-standard-error", required_argument, NULL, ARG_DEFAULT_STD_ERROR, }, + { "machine-id", required_argument, NULL, ARG_MACHINE_ID }, + {} + }; + + int c, r; + + assert(argc >= 1); + assert(argv); + + if (getpid() == 1) + opterr = 0; + + while ((c = getopt_long(argc, argv, "hDbsz:", options, NULL)) >= 0) + + switch (c) { + + case ARG_LOG_LEVEL: + r = log_set_max_level_from_string(optarg); + if (r < 0) { + log_error("Failed to parse log level %s.", optarg); + return r; + } + + break; + + case ARG_LOG_TARGET: + r = log_set_target_from_string(optarg); + if (r < 0) { + log_error("Failed to parse log target %s.", optarg); + return r; + } + + break; + + case ARG_LOG_COLOR: + + if (optarg) { + r = log_show_color_from_string(optarg); + if (r < 0) { + log_error("Failed to parse log color setting %s.", optarg); + return r; + } + } else + log_show_color(true); + + break; + + case ARG_LOG_LOCATION: + if (optarg) { + r = log_show_location_from_string(optarg); + if (r < 0) { + log_error("Failed to parse log location setting %s.", optarg); + return r; + } + } else + log_show_location(true); + + break; + + case ARG_DEFAULT_STD_OUTPUT: + r = exec_output_from_string(optarg); + if (r < 0) { + log_error("Failed to parse default standard output setting %s.", optarg); + return r; + } else + arg_default_std_output = r; + break; + + case ARG_DEFAULT_STD_ERROR: + r = exec_output_from_string(optarg); + if (r < 0) { + log_error("Failed to parse default standard error output setting %s.", optarg); + return r; + } else + arg_default_std_error = r; + break; + + case ARG_UNIT: + + r = free_and_strdup(&arg_default_unit, optarg); + if (r < 0) + return log_error_errno(r, "Failed to set default unit %s: %m", optarg); + + break; + + case ARG_SYSTEM: + arg_system = true; + break; + + case ARG_USER: + arg_system = false; + break; + + case ARG_TEST: + arg_action = ACTION_TEST; + break; + + case ARG_NO_PAGER: + arg_no_pager = true; + break; + + case ARG_VERSION: + arg_action = ACTION_VERSION; + break; + + case ARG_DUMP_CONFIGURATION_ITEMS: + arg_action = ACTION_DUMP_CONFIGURATION_ITEMS; + break; + + case ARG_DUMP_CORE: + if (!optarg) + arg_dump_core = true; + else { + r = parse_boolean(optarg); + if (r < 0) + return log_error_errno(r, "Failed to parse dump core boolean: %s", optarg); + arg_dump_core = r; + } + break; + + case ARG_CRASH_CHVT: + r = parse_crash_chvt(optarg); + if (r < 0) + return log_error_errno(r, "Failed to parse crash virtual terminal index: %s", optarg); + break; + + case ARG_CRASH_SHELL: + if (!optarg) + arg_crash_shell = true; + else { + r = parse_boolean(optarg); + if (r < 0) + return log_error_errno(r, "Failed to parse crash shell boolean: %s", optarg); + arg_crash_shell = r; + } + break; + + case ARG_CRASH_REBOOT: + if (!optarg) + arg_crash_reboot = true; + else { + r = parse_boolean(optarg); + if (r < 0) + return log_error_errno(r, "Failed to parse crash shell boolean: %s", optarg); + arg_crash_reboot = r; + } + break; + + case ARG_CONFIRM_SPAWN: + r = optarg ? parse_boolean(optarg) : 1; + if (r < 0) { + log_error("Failed to parse confirm spawn boolean %s.", optarg); + return r; + } + arg_confirm_spawn = r; + break; + + case ARG_SHOW_STATUS: + if (optarg) { + r = parse_show_status(optarg, &arg_show_status); + if (r < 0) { + log_error("Failed to parse show status boolean %s.", optarg); + return r; + } + } else + arg_show_status = SHOW_STATUS_YES; + break; + + case ARG_DESERIALIZE: { + int fd; + FILE *f; + + r = safe_atoi(optarg, &fd); + if (r < 0 || fd < 0) { + log_error("Failed to parse deserialize option %s.", optarg); + return -EINVAL; + } + + (void) fd_cloexec(fd, true); + + f = fdopen(fd, "r"); + if (!f) + return log_error_errno(errno, "Failed to open serialization fd: %m"); + + safe_fclose(arg_serialization); + arg_serialization = f; + + break; + } + + case ARG_SWITCHED_ROOT: + arg_switched_root = true; + break; + + case ARG_MACHINE_ID: + r = set_machine_id(optarg); + if (r < 0) + return log_error_errno(r, "MachineID '%s' is not valid.", optarg); + break; + + case 'h': + arg_action = ACTION_HELP; + break; + + case 'D': + log_set_max_level(LOG_DEBUG); + break; + + case 'b': + case 's': + case 'z': + /* Just to eat away the sysvinit kernel + * cmdline args without getopt() error + * messages that we'll parse in + * parse_proc_cmdline_word() or ignore. */ + + case '?': + if (getpid() != 1) + return -EINVAL; + else + return 0; + + default: + assert_not_reached("Unhandled option code."); + } + + if (optind < argc && getpid() != 1) { + /* Hmm, when we aren't run as init system + * let's complain about excess arguments */ + + log_error("Excess arguments."); + return -EINVAL; + } + + return 0; +} + +static int help(void) { + + printf("%s [OPTIONS...]\n\n" + "Starts up and maintains the system or user services.\n\n" + " -h --help Show this help\n" + " --test Determine startup sequence, dump it and exit\n" + " --no-pager Do not pipe output into a pager\n" + " --dump-configuration-items Dump understood unit configuration items\n" + " --unit=UNIT Set default unit\n" + " --system Run a system instance, even if PID != 1\n" + " --user Run a user instance\n" + " --dump-core[=BOOL] Dump core on crash\n" + " --crash-vt=NR Change to specified VT on crash\n" + " --crash-reboot[=BOOL] Reboot on crash\n" + " --crash-shell[=BOOL] Run shell on crash\n" + " --confirm-spawn[=BOOL] Ask for confirmation when spawning processes\n" + " --show-status[=BOOL] Show status updates on the console during bootup\n" + " --log-target=TARGET Set log target (console, journal, kmsg, journal-or-kmsg, null)\n" + " --log-level=LEVEL Set log level (debug, info, notice, warning, err, crit, alert, emerg)\n" + " --log-color[=BOOL] Highlight important log messages\n" + " --log-location[=BOOL] Include code location in log messages\n" + " --default-standard-output= Set default standard output for services\n" + " --default-standard-error= Set default standard error output for services\n", + program_invocation_short_name); + + return 0; +} + +static int prepare_reexecute(Manager *m, FILE **_f, FDSet **_fds, bool switching_root) { + _cleanup_fdset_free_ FDSet *fds = NULL; + _cleanup_fclose_ FILE *f = NULL; + int r; + + assert(m); + assert(_f); + assert(_fds); + + r = manager_open_serialization(m, &f); + if (r < 0) + return log_error_errno(r, "Failed to create serialization file: %m"); + + /* Make sure nothing is really destructed when we shut down */ + m->n_reloading++; + bus_manager_send_reloading(m, true); + + fds = fdset_new(); + if (!fds) + return log_oom(); + + r = manager_serialize(m, f, fds, switching_root); + if (r < 0) + return log_error_errno(r, "Failed to serialize state: %m"); + + if (fseeko(f, 0, SEEK_SET) == (off_t) -1) + return log_error_errno(errno, "Failed to rewind serialization fd: %m"); + + r = fd_cloexec(fileno(f), false); + if (r < 0) + return log_error_errno(r, "Failed to disable O_CLOEXEC for serialization: %m"); + + r = fdset_cloexec(fds, false); + if (r < 0) + return log_error_errno(r, "Failed to disable O_CLOEXEC for serialization fds: %m"); + + *_f = f; + *_fds = fds; + + f = NULL; + fds = NULL; + + return 0; +} + +static int bump_rlimit_nofile(struct rlimit *saved_rlimit) { + struct rlimit nl; + int r; + + assert(saved_rlimit); + + /* Save the original RLIMIT_NOFILE so that we can reset it + * later when transitioning from the initrd to the main + * systemd or suchlike. */ + if (getrlimit(RLIMIT_NOFILE, saved_rlimit) < 0) + return log_warning_errno(errno, "Reading RLIMIT_NOFILE failed, ignoring: %m"); + + /* Make sure forked processes get the default kernel setting */ + if (!arg_default_rlimit[RLIMIT_NOFILE]) { + struct rlimit *rl; + + rl = newdup(struct rlimit, saved_rlimit, 1); + if (!rl) + return log_oom(); + + arg_default_rlimit[RLIMIT_NOFILE] = rl; + } + + /* Bump up the resource limit for ourselves substantially */ + nl.rlim_cur = nl.rlim_max = 64*1024; + r = setrlimit_closest(RLIMIT_NOFILE, &nl); + if (r < 0) + return log_warning_errno(r, "Setting RLIMIT_NOFILE failed, ignoring: %m"); + + return 0; +} + +static void test_usr(void) { + + /* Check that /usr is not a separate fs */ + + if (dir_is_empty("/usr") <= 0) + return; + + log_warning("/usr appears to be on its own filesystem and is not already mounted. This is not a supported setup. " + "Some things will probably break (sometimes even silently) in mysterious ways. " + "Consult http://freedesktop.org/wiki/Software/systemd/separate-usr-is-broken for more information."); +} + +static int initialize_join_controllers(void) { + /* By default, mount "cpu" + "cpuacct" together, and "net_cls" + * + "net_prio". We'd like to add "cpuset" to the mix, but + * "cpuset" doesn't really work for groups with no initialized + * attributes. */ + + arg_join_controllers = new(char**, 3); + if (!arg_join_controllers) + return -ENOMEM; + + arg_join_controllers[0] = strv_new("cpu", "cpuacct", NULL); + if (!arg_join_controllers[0]) + goto oom; + + arg_join_controllers[1] = strv_new("net_cls", "net_prio", NULL); + if (!arg_join_controllers[1]) + goto oom; + + arg_join_controllers[2] = NULL; + return 0; + +oom: + arg_join_controllers = strv_free_free(arg_join_controllers); + return -ENOMEM; +} + +static int enforce_syscall_archs(Set *archs) { +#ifdef HAVE_SECCOMP + scmp_filter_ctx *seccomp; + Iterator i; + void *id; + int r; + + if (!is_seccomp_available()) + return 0; + + seccomp = seccomp_init(SCMP_ACT_ALLOW); + if (!seccomp) + return log_oom(); + + SET_FOREACH(id, arg_syscall_archs, i) { + r = seccomp_arch_add(seccomp, PTR_TO_UINT32(id) - 1); + if (r == -EEXIST) + continue; + if (r < 0) { + log_error_errno(r, "Failed to add architecture to seccomp: %m"); + goto finish; + } + } + + r = seccomp_attr_set(seccomp, SCMP_FLTATR_CTL_NNP, 0); + if (r < 0) { + log_error_errno(r, "Failed to unset NO_NEW_PRIVS: %m"); + goto finish; + } + + r = seccomp_load(seccomp); + if (r < 0) + log_error_errno(r, "Failed to add install architecture seccomp: %m"); + +finish: + seccomp_release(seccomp); + return r; +#else + return 0; +#endif +} + +static int status_welcome(void) { + _cleanup_free_ char *pretty_name = NULL, *ansi_color = NULL; + int r; + + r = parse_env_file("/etc/os-release", NEWLINE, + "PRETTY_NAME", &pretty_name, + "ANSI_COLOR", &ansi_color, + NULL); + if (r == -ENOENT) + r = parse_env_file("/usr/lib/os-release", NEWLINE, + "PRETTY_NAME", &pretty_name, + "ANSI_COLOR", &ansi_color, + NULL); + + if (r < 0 && r != -ENOENT) + log_warning_errno(r, "Failed to read os-release file: %m"); + + if (log_get_show_color()) + return status_printf(NULL, false, false, + "\nWelcome to \x1B[%sm%s\x1B[0m!\n", + isempty(ansi_color) ? "1" : ansi_color, + isempty(pretty_name) ? "GNU/Linux" : pretty_name); + else + return status_printf(NULL, false, false, + "\nWelcome to %s!\n", + isempty(pretty_name) ? "GNU/Linux" : pretty_name); +} + +static int write_container_id(void) { + const char *c; + int r; + + c = getenv("container"); + if (isempty(c)) + return 0; + + RUN_WITH_UMASK(0022) + r = write_string_file("/run/systemd/container", c, WRITE_STRING_FILE_CREATE); + if (r < 0) + return log_warning_errno(r, "Failed to write /run/systemd/container, ignoring: %m"); + + return 1; +} + +static int bump_unix_max_dgram_qlen(void) { + _cleanup_free_ char *qlen = NULL; + unsigned long v; + int r; + + /* Let's bump the net.unix.max_dgram_qlen sysctl. The kernel + * default of 16 is simply too low. We set the value really + * really early during boot, so that it is actually applied to + * all our sockets, including the $NOTIFY_SOCKET one. */ + + r = read_one_line_file("/proc/sys/net/unix/max_dgram_qlen", &qlen); + if (r < 0) + return log_warning_errno(r, "Failed to read AF_UNIX datagram queue length, ignoring: %m"); + + r = safe_atolu(qlen, &v); + if (r < 0) + return log_warning_errno(r, "Failed to parse AF_UNIX datagram queue length, ignoring: %m"); + + if (v >= DEFAULT_UNIX_MAX_DGRAM_QLEN) + return 0; + + qlen = mfree(qlen); + if (asprintf(&qlen, "%lu\n", DEFAULT_UNIX_MAX_DGRAM_QLEN) < 0) + return log_oom(); + + r = write_string_file("/proc/sys/net/unix/max_dgram_qlen", qlen, 0); + if (r < 0) + return log_full_errno(IN_SET(r, -EROFS, -EPERM, -EACCES) ? LOG_DEBUG : LOG_WARNING, r, + "Failed to bump AF_UNIX datagram queue length, ignoring: %m"); + + return 1; +} + +static int fixup_environment(void) { + _cleanup_free_ char *term = NULL; + int r; + + /* We expect the environment to be set correctly + * if run inside a container. */ + if (detect_container() > 0) + return 0; + + /* When started as PID1, the kernel uses /dev/console + * for our stdios and uses TERM=linux whatever the + * backend device used by the console. We try to make + * a better guess here since some consoles might not + * have support for color mode for example. + * + * However if TERM was configured through the kernel + * command line then leave it alone. */ + + r = get_proc_cmdline_key("TERM=", &term); + if (r < 0) + return r; + + if (r == 0) { + term = strdup(default_term_for_tty("/dev/console")); + if (!term) + return -ENOMEM; + } + + if (setenv("TERM", term, 1) < 0) + return -errno; + + return 0; +} + +int main(int argc, char *argv[]) { + Manager *m = NULL; + int r, retval = EXIT_FAILURE; + usec_t before_startup, after_startup; + char timespan[FORMAT_TIMESPAN_MAX]; + FDSet *fds = NULL; + bool reexecute = false; + const char *shutdown_verb = NULL; + dual_timestamp initrd_timestamp = DUAL_TIMESTAMP_NULL; + dual_timestamp userspace_timestamp = DUAL_TIMESTAMP_NULL; + dual_timestamp kernel_timestamp = DUAL_TIMESTAMP_NULL; + dual_timestamp security_start_timestamp = DUAL_TIMESTAMP_NULL; + dual_timestamp security_finish_timestamp = DUAL_TIMESTAMP_NULL; + static char systemd[] = "systemd"; + bool skip_setup = false; + unsigned j; + bool loaded_policy = false; + bool arm_reboot_watchdog = false; + bool queue_default_job = false; + bool empty_etc = false; + char *switch_root_dir = NULL, *switch_root_init = NULL; + struct rlimit saved_rlimit_nofile = RLIMIT_MAKE_CONST(0); + const char *error_message = NULL; + +#ifdef HAVE_SYSV_COMPAT + if (getpid() != 1 && strstr(program_invocation_short_name, "init")) { + /* This is compatibility support for SysV, where + * calling init as a user is identical to telinit. */ + + execv(SYSTEMCTL_BINARY_PATH, argv); + log_error_errno(errno, "Failed to exec " SYSTEMCTL_BINARY_PATH ": %m"); + return 1; + } +#endif + + dual_timestamp_from_monotonic(&kernel_timestamp, 0); + dual_timestamp_get(&userspace_timestamp); + + /* Determine if this is a reexecution or normal bootup. We do + * the full command line parsing much later, so let's just + * have a quick peek here. */ + if (strv_find(argv+1, "--deserialize")) + skip_setup = true; + + /* If we have switched root, do all the special setup + * things */ + if (strv_find(argv+1, "--switched-root")) + skip_setup = false; + + /* If we get started via the /sbin/init symlink then we are + called 'init'. After a subsequent reexecution we are then + called 'systemd'. That is confusing, hence let's call us + systemd right-away. */ + program_invocation_short_name = systemd; + prctl(PR_SET_NAME, systemd); + + saved_argv = argv; + saved_argc = argc; + + log_set_upgrade_syslog_to_journal(true); + + /* Disable the umask logic */ + if (getpid() == 1) + umask(0); + + if (getpid() == 1 && detect_container() <= 0) { + + /* Running outside of a container as PID 1 */ + arg_system = true; + log_set_target(LOG_TARGET_KMSG); + log_open(); + + if (in_initrd()) + initrd_timestamp = userspace_timestamp; + + if (!skip_setup) { + r = mount_setup_early(); + if (r < 0) { + error_message = "Failed to early mount API filesystems"; + goto finish; + } + dual_timestamp_get(&security_start_timestamp); + if (mac_selinux_setup(&loaded_policy) < 0) { + error_message = "Failed to load SELinux policy"; + goto finish; + } else if (mac_smack_setup(&loaded_policy) < 0) { + error_message = "Failed to load SMACK policy"; + goto finish; + } else if (ima_setup() < 0) { + error_message = "Failed to load IMA policy"; + goto finish; + } + dual_timestamp_get(&security_finish_timestamp); + } + + if (mac_selinux_init() < 0) { + error_message = "Failed to initialize SELinux policy"; + goto finish; + } + + if (!skip_setup) { + if (clock_is_localtime(NULL) > 0) { + int min; + + /* + * The very first call of settimeofday() also does a time warp in the kernel. + * + * In the rtc-in-local time mode, we set the kernel's timezone, and rely on + * external tools to take care of maintaining the RTC and do all adjustments. + * This matches the behavior of Windows, which leaves the RTC alone if the + * registry tells that the RTC runs in UTC. + */ + r = clock_set_timezone(&min); + if (r < 0) + log_error_errno(r, "Failed to apply local time delta, ignoring: %m"); + else + log_info("RTC configured in localtime, applying delta of %i minutes to system time.", min); + } else if (!in_initrd()) { + /* + * Do a dummy very first call to seal the kernel's time warp magic. + * + * Do not call this from inside the initrd. The initrd might not + * carry /etc/adjtime with LOCAL, but the real system could be set up + * that way. In such case, we need to delay the time-warp or the sealing + * until we reach the real system. + * + * Do no set the kernel's timezone. The concept of local time cannot + * be supported reliably, the time will jump or be incorrect at every daylight + * saving time change. All kernel local time concepts will be treated + * as UTC that way. + */ + (void) clock_reset_timewarp(); + } + + r = clock_apply_epoch(); + if (r < 0) + log_error_errno(r, "Current system time is before build time, but cannot correct: %m"); + else if (r > 0) + log_info("System time before build time, advancing clock."); + } + + /* Set the default for later on, but don't actually + * open the logs like this for now. Note that if we + * are transitioning from the initrd there might still + * be journal fd open, and we shouldn't attempt + * opening that before we parsed /proc/cmdline which + * might redirect output elsewhere. */ + log_set_target(LOG_TARGET_JOURNAL_OR_KMSG); + + } else if (getpid() == 1) { + /* Running inside a container, as PID 1 */ + arg_system = true; + log_set_target(LOG_TARGET_CONSOLE); + log_close_console(); /* force reopen of /dev/console */ + log_open(); + + /* For the later on, see above... */ + log_set_target(LOG_TARGET_JOURNAL); + + /* clear the kernel timestamp, + * because we are in a container */ + kernel_timestamp = DUAL_TIMESTAMP_NULL; + } else { + /* Running as user instance */ + arg_system = false; + log_set_target(LOG_TARGET_AUTO); + log_open(); + + /* clear the kernel timestamp, + * because we are not PID 1 */ + kernel_timestamp = DUAL_TIMESTAMP_NULL; + } + + if (getpid() == 1) { + /* Don't limit the core dump size, so that coredump handlers such as systemd-coredump (which honour the limit) + * will process core dumps for system services by default. */ + if (setrlimit(RLIMIT_CORE, &RLIMIT_MAKE_CONST(RLIM_INFINITY)) < 0) + log_warning_errno(errno, "Failed to set RLIMIT_CORE: %m"); + + /* But at the same time, turn off the core_pattern logic by default, so that no coredumps are stored + * until the systemd-coredump tool is enabled via sysctl. */ + if (!skip_setup) + (void) write_string_file("/proc/sys/kernel/core_pattern", "|/bin/false", 0); + } + + if (arg_system) { + if (fixup_environment() < 0) { + error_message = "Failed to fix up PID1 environment"; + goto finish; + } + + /* Try to figure out if we can use colors with the console. No + * need to do that for user instances since they never log + * into the console. */ + log_show_color(colors_enabled()); + r = make_null_stdio(); + if (r < 0) + log_warning_errno(r, "Failed to redirect standard streams to /dev/null: %m"); + } + + r = initialize_join_controllers(); + if (r < 0) { + error_message = "Failed to initialize cgroup controllers"; + goto finish; + } + + /* Mount /proc, /sys and friends, so that /proc/cmdline and + * /proc/$PID/fd is available. */ + if (getpid() == 1) { + + /* Load the kernel modules early, so that we kdbus.ko is loaded before kdbusfs shall be mounted */ + if (!skip_setup) + kmod_setup(); + + r = mount_setup(loaded_policy); + if (r < 0) { + error_message = "Failed to mount API filesystems"; + goto finish; + } + } + + /* Reset all signal handlers. */ + (void) reset_all_signal_handlers(); + (void) ignore_signals(SIGNALS_IGNORE, -1); + + arg_default_tasks_max = system_tasks_max_scale(DEFAULT_TASKS_MAX_PERCENTAGE, 100U); + + if (parse_config_file() < 0) { + error_message = "Failed to parse config file"; + goto finish; + } + + if (arg_system) { + r = parse_proc_cmdline(parse_proc_cmdline_item, NULL, false); + if (r < 0) + log_warning_errno(r, "Failed to parse kernel command line, ignoring: %m"); + } + + /* Note that this also parses bits from the kernel command + * line, including "debug". */ + log_parse_environment(); + + if (parse_argv(argc, argv) < 0) { + error_message = "Failed to parse commandline arguments"; + goto finish; + } + + /* Initialize default unit */ + if (!arg_default_unit) { + arg_default_unit = strdup(SPECIAL_DEFAULT_TARGET); + if (!arg_default_unit) { + r = log_oom(); + error_message = "Failed to set default unit"; + goto finish; + } + } + + if (arg_action == ACTION_TEST && + geteuid() == 0) { + log_error("Don't run test mode as root."); + goto finish; + } + + if (!arg_system && + arg_action == ACTION_RUN && + sd_booted() <= 0) { + log_error("Trying to run as user instance, but the system has not been booted with systemd."); + goto finish; + } + + if (arg_system && + arg_action == ACTION_RUN && + running_in_chroot() > 0) { + log_error("Cannot be run in a chroot() environment."); + goto finish; + } + + if (arg_action == ACTION_TEST || arg_action == ACTION_HELP) { + pager_open(arg_no_pager, false); + skip_setup = true; + } + + if (arg_action == ACTION_HELP) { + retval = help(); + goto finish; + } else if (arg_action == ACTION_VERSION) { + retval = version(); + goto finish; + } else if (arg_action == ACTION_DUMP_CONFIGURATION_ITEMS) { + pager_open(arg_no_pager, false); + unit_dump_config_items(stdout); + retval = EXIT_SUCCESS; + goto finish; + } + + if (!arg_system && + !getenv("XDG_RUNTIME_DIR")) { + log_error("Trying to run as user instance, but $XDG_RUNTIME_DIR is not set."); + goto finish; + } + + assert_se(arg_action == ACTION_RUN || arg_action == ACTION_TEST); + + /* Close logging fds, in order not to confuse fdset below */ + log_close(); + + /* Remember open file descriptors for later deserialization */ + r = fdset_new_fill(&fds); + if (r < 0) { + log_emergency_errno(r, "Failed to allocate fd set: %m"); + error_message = "Failed to allocate fd set"; + goto finish; + } else + fdset_cloexec(fds, true); + + if (arg_serialization) + assert_se(fdset_remove(fds, fileno(arg_serialization)) >= 0); + + if (arg_system) + /* Become a session leader if we aren't one yet. */ + setsid(); + + /* Move out of the way, so that we won't block unmounts */ + assert_se(chdir("/") == 0); + + /* Reset the console, but only if this is really init and we + * are freshly booted */ + if (arg_system && arg_action == ACTION_RUN) { + + /* If we are init, we connect stdin/stdout/stderr to + * /dev/null and make sure we don't have a controlling + * tty. */ + release_terminal(); + + if (getpid() == 1 && !skip_setup) + console_setup(); + } + + /* Open the logging devices, if possible and necessary */ + log_open(); + + if (arg_show_status == _SHOW_STATUS_UNSET) + arg_show_status = SHOW_STATUS_YES; + + /* Make sure we leave a core dump without panicing the + * kernel. */ + if (getpid() == 1) { + install_crash_handler(); + + r = mount_cgroup_controllers(arg_join_controllers); + if (r < 0) + goto finish; + } + + if (arg_system) { + int v; + + log_info(PACKAGE_STRING " running in %ssystem mode. (" SYSTEMD_FEATURES ")", + arg_action == ACTION_TEST ? "test " : "" ); + + v = detect_virtualization(); + if (v > 0) + log_info("Detected virtualization %s.", virtualization_to_string(v)); + + write_container_id(); + + log_info("Detected architecture %s.", architecture_to_string(uname_architecture())); + + if (in_initrd()) + log_info("Running in initial RAM disk."); + + /* Let's check whether /etc is already populated. We + * don't actually really check for that, but use + * /etc/machine-id as flag file. This allows container + * managers and installers to provision a couple of + * files already. If the container manager wants to + * provision the machine ID itself it should pass + * $container_uuid to PID 1. */ + + empty_etc = access("/etc/machine-id", F_OK) < 0; + if (empty_etc) + log_info("Running with unpopulated /etc."); + } else { + _cleanup_free_ char *t; + + t = uid_to_name(getuid()); + log_debug(PACKAGE_STRING " running in %suser mode for user "UID_FMT"/%s. (" SYSTEMD_FEATURES ")", + arg_action == ACTION_TEST ? " test" : "", getuid(), t); + } + + if (arg_system && !skip_setup) { + if (arg_show_status > 0) + status_welcome(); + + hostname_setup(); + machine_id_setup(NULL, arg_machine_id, NULL); + loopback_setup(); + bump_unix_max_dgram_qlen(); + + test_usr(); + } + + if (arg_system && arg_runtime_watchdog > 0 && arg_runtime_watchdog != USEC_INFINITY) + watchdog_set_timeout(&arg_runtime_watchdog); + + if (arg_timer_slack_nsec != NSEC_INFINITY) + if (prctl(PR_SET_TIMERSLACK, arg_timer_slack_nsec) < 0) + log_error_errno(errno, "Failed to adjust timer slack: %m"); + + if (!cap_test_all(arg_capability_bounding_set)) { + r = capability_bounding_set_drop_usermode(arg_capability_bounding_set); + if (r < 0) { + log_emergency_errno(r, "Failed to drop capability bounding set of usermode helpers: %m"); + error_message = "Failed to drop capability bounding set of usermode helpers"; + goto finish; + } + r = capability_bounding_set_drop(arg_capability_bounding_set, true); + if (r < 0) { + log_emergency_errno(r, "Failed to drop capability bounding set: %m"); + error_message = "Failed to drop capability bounding set"; + goto finish; + } + } + + if (arg_syscall_archs) { + r = enforce_syscall_archs(arg_syscall_archs); + if (r < 0) { + error_message = "Failed to set syscall architectures"; + goto finish; + } + } + + if (!arg_system) + /* Become reaper of our children */ + if (prctl(PR_SET_CHILD_SUBREAPER, 1) < 0) + log_warning_errno(errno, "Failed to make us a subreaper: %m"); + + if (arg_system) { + (void) bump_rlimit_nofile(&saved_rlimit_nofile); + + if (empty_etc) { + r = unit_file_preset_all(UNIT_FILE_SYSTEM, 0, NULL, UNIT_FILE_PRESET_ENABLE_ONLY, NULL, 0); + if (r < 0) + log_full_errno(r == -EEXIST ? LOG_NOTICE : LOG_WARNING, r, "Failed to populate /etc with preset unit settings, ignoring: %m"); + else + log_info("Populated /etc with preset unit settings."); + } + } + + r = manager_new(arg_system ? UNIT_FILE_SYSTEM : UNIT_FILE_USER, arg_action == ACTION_TEST, &m); + if (r < 0) { + log_emergency_errno(r, "Failed to allocate manager object: %m"); + error_message = "Failed to allocate manager object"; + goto finish; + } + + m->confirm_spawn = arg_confirm_spawn; + m->runtime_watchdog = arg_runtime_watchdog; + m->shutdown_watchdog = arg_shutdown_watchdog; + m->userspace_timestamp = userspace_timestamp; + m->kernel_timestamp = kernel_timestamp; + m->initrd_timestamp = initrd_timestamp; + m->security_start_timestamp = security_start_timestamp; + m->security_finish_timestamp = security_finish_timestamp; + m->cad_burst_action = arg_cad_burst_action; + + manager_set_defaults(m); + manager_set_show_status(m, arg_show_status); + manager_set_first_boot(m, empty_etc); + + /* Remember whether we should queue the default job */ + queue_default_job = !arg_serialization || arg_switched_root; + + before_startup = now(CLOCK_MONOTONIC); + + r = manager_startup(m, arg_serialization, fds); + if (r < 0) + log_error_errno(r, "Failed to fully start up daemon: %m"); + + /* This will close all file descriptors that were opened, but + * not claimed by any unit. */ + fds = fdset_free(fds); + + arg_serialization = safe_fclose(arg_serialization); + + if (queue_default_job) { + _cleanup_(sd_bus_error_free) sd_bus_error error = SD_BUS_ERROR_NULL; + Unit *target = NULL; + Job *default_unit_job; + + log_debug("Activating default unit: %s", arg_default_unit); + + r = manager_load_unit(m, arg_default_unit, NULL, &error, &target); + if (r < 0) + log_error("Failed to load default target: %s", bus_error_message(&error, r)); + else if (target->load_state == UNIT_ERROR || target->load_state == UNIT_NOT_FOUND) + log_error_errno(target->load_error, "Failed to load default target: %m"); + else if (target->load_state == UNIT_MASKED) + log_error("Default target masked."); + + if (!target || target->load_state != UNIT_LOADED) { + log_info("Trying to load rescue target..."); + + r = manager_load_unit(m, SPECIAL_RESCUE_TARGET, NULL, &error, &target); + if (r < 0) { + log_emergency("Failed to load rescue target: %s", bus_error_message(&error, r)); + error_message = "Failed to load rescue target"; + goto finish; + } else if (target->load_state == UNIT_ERROR || target->load_state == UNIT_NOT_FOUND) { + log_emergency_errno(target->load_error, "Failed to load rescue target: %m"); + error_message = "Failed to load rescue target"; + goto finish; + } else if (target->load_state == UNIT_MASKED) { + log_emergency("Rescue target masked."); + error_message = "Rescue target masked"; + goto finish; + } + } + + assert(target->load_state == UNIT_LOADED); + + if (arg_action == ACTION_TEST) { + printf("-> By units:\n"); + manager_dump_units(m, stdout, "\t"); + } + + r = manager_add_job(m, JOB_START, target, JOB_ISOLATE, &error, &default_unit_job); + if (r == -EPERM) { + log_debug("Default target could not be isolated, starting instead: %s", bus_error_message(&error, r)); + + sd_bus_error_free(&error); + + r = manager_add_job(m, JOB_START, target, JOB_REPLACE, &error, &default_unit_job); + if (r < 0) { + log_emergency("Failed to start default target: %s", bus_error_message(&error, r)); + error_message = "Failed to start default target"; + goto finish; + } + } else if (r < 0) { + log_emergency("Failed to isolate default target: %s", bus_error_message(&error, r)); + error_message = "Failed to isolate default target"; + goto finish; + } + + m->default_unit_job_id = default_unit_job->id; + + after_startup = now(CLOCK_MONOTONIC); + log_full(arg_action == ACTION_TEST ? LOG_INFO : LOG_DEBUG, + "Loaded units and determined initial transaction in %s.", + format_timespan(timespan, sizeof(timespan), after_startup - before_startup, 100 * USEC_PER_MSEC)); + + if (arg_action == ACTION_TEST) { + printf("-> By jobs:\n"); + manager_dump_jobs(m, stdout, "\t"); + retval = EXIT_SUCCESS; + goto finish; + } + } + + for (;;) { + r = manager_loop(m); + if (r < 0) { + log_emergency_errno(r, "Failed to run main loop: %m"); + error_message = "Failed to run main loop"; + goto finish; + } + + switch (m->exit_code) { + + case MANAGER_RELOAD: + log_info("Reloading."); + + r = parse_config_file(); + if (r < 0) + log_error("Failed to parse config file."); + + manager_set_defaults(m); + + r = manager_reload(m); + if (r < 0) + log_error_errno(r, "Failed to reload: %m"); + break; + + case MANAGER_REEXECUTE: + + if (prepare_reexecute(m, &arg_serialization, &fds, false) < 0) { + error_message = "Failed to prepare for reexecution"; + goto finish; + } + + reexecute = true; + log_notice("Reexecuting."); + goto finish; + + case MANAGER_SWITCH_ROOT: + /* Steal the switch root parameters */ + switch_root_dir = m->switch_root; + switch_root_init = m->switch_root_init; + m->switch_root = m->switch_root_init = NULL; + + if (!switch_root_init) + if (prepare_reexecute(m, &arg_serialization, &fds, true) < 0) { + error_message = "Failed to prepare for reexecution"; + goto finish; + } + + reexecute = true; + log_notice("Switching root."); + goto finish; + + case MANAGER_EXIT: + retval = m->return_value; + + if (MANAGER_IS_USER(m)) { + log_debug("Exit."); + goto finish; + } + + /* fallthrough */ + case MANAGER_REBOOT: + case MANAGER_POWEROFF: + case MANAGER_HALT: + case MANAGER_KEXEC: { + static const char * const table[_MANAGER_EXIT_CODE_MAX] = { + [MANAGER_EXIT] = "exit", + [MANAGER_REBOOT] = "reboot", + [MANAGER_POWEROFF] = "poweroff", + [MANAGER_HALT] = "halt", + [MANAGER_KEXEC] = "kexec" + }; + + assert_se(shutdown_verb = table[m->exit_code]); + arm_reboot_watchdog = m->exit_code == MANAGER_REBOOT; + + log_notice("Shutting down."); + goto finish; + } + + default: + assert_not_reached("Unknown exit code."); + } + } + +finish: + pager_close(); + + if (m) + arg_shutdown_watchdog = m->shutdown_watchdog; + + m = manager_free(m); + + for (j = 0; j < ELEMENTSOF(arg_default_rlimit); j++) + arg_default_rlimit[j] = mfree(arg_default_rlimit[j]); + + arg_default_unit = mfree(arg_default_unit); + arg_join_controllers = strv_free_free(arg_join_controllers); + arg_default_environment = strv_free(arg_default_environment); + arg_syscall_archs = set_free(arg_syscall_archs); + + mac_selinux_finish(); + + if (reexecute) { + const char **args; + unsigned i, args_size; + + /* Close and disarm the watchdog, so that the new + * instance can reinitialize it, but doesn't get + * rebooted while we do that */ + watchdog_close(true); + + /* Reset the RLIMIT_NOFILE to the kernel default, so + * that the new systemd can pass the kernel default to + * its child processes */ + if (saved_rlimit_nofile.rlim_cur > 0) + (void) setrlimit(RLIMIT_NOFILE, &saved_rlimit_nofile); + + if (switch_root_dir) { + /* Kill all remaining processes from the + * initrd, but don't wait for them, so that we + * can handle the SIGCHLD for them after + * deserializing. */ + broadcast_signal(SIGTERM, false, true); + + /* And switch root with MS_MOVE, because we remove the old directory afterwards and detach it. */ + r = switch_root(switch_root_dir, "/mnt", true, MS_MOVE); + if (r < 0) + log_error_errno(r, "Failed to switch root, trying to continue: %m"); + } + + args_size = MAX(6, argc+1); + args = newa(const char*, args_size); + + if (!switch_root_init) { + char sfd[DECIMAL_STR_MAX(int) + 1]; + + /* First try to spawn ourselves with the right + * path, and with full serialization. We do + * this only if the user didn't specify an + * explicit init to spawn. */ + + assert(arg_serialization); + assert(fds); + + xsprintf(sfd, "%i", fileno(arg_serialization)); + + i = 0; + args[i++] = SYSTEMD_BINARY_PATH; + if (switch_root_dir) + args[i++] = "--switched-root"; + args[i++] = arg_system ? "--system" : "--user"; + args[i++] = "--deserialize"; + args[i++] = sfd; + args[i++] = NULL; + + assert(i <= args_size); + + /* + * We want valgrind to print its memory usage summary before reexecution. + * Valgrind won't do this is on its own on exec(), but it will do it on exit(). + * Hence, to ensure we get a summary here, fork() off a child, let it exit() cleanly, + * so that it prints the summary, and wait() for it in the parent, before proceeding into the exec(). + */ + valgrind_summary_hack(); + + (void) execv(args[0], (char* const*) args); + } + + /* Try the fallback, if there is any, without any + * serialization. We pass the original argv[] and + * envp[]. (Well, modulo the ordering changes due to + * getopt() in argv[], and some cleanups in envp[], + * but let's hope that doesn't matter.) */ + + arg_serialization = safe_fclose(arg_serialization); + fds = fdset_free(fds); + + /* Reopen the console */ + (void) make_console_stdio(); + + for (j = 1, i = 1; j < (unsigned) argc; j++) + args[i++] = argv[j]; + args[i++] = NULL; + assert(i <= args_size); + + /* Reenable any blocked signals, especially important + * if we switch from initial ramdisk to init=... */ + (void) reset_all_signal_handlers(); + (void) reset_signal_mask(); + + if (switch_root_init) { + args[0] = switch_root_init; + (void) execv(args[0], (char* const*) args); + log_warning_errno(errno, "Failed to execute configured init, trying fallback: %m"); + } + + args[0] = "/sbin/init"; + (void) execv(args[0], (char* const*) args); + + if (errno == ENOENT) { + log_warning("No /sbin/init, trying fallback"); + + args[0] = "/bin/sh"; + args[1] = NULL; + (void) execv(args[0], (char* const*) args); + log_error_errno(errno, "Failed to execute /bin/sh, giving up: %m"); + } else + log_warning_errno(errno, "Failed to execute /sbin/init, giving up: %m"); + } + + arg_serialization = safe_fclose(arg_serialization); + fds = fdset_free(fds); + +#ifdef HAVE_VALGRIND_VALGRIND_H + /* If we are PID 1 and running under valgrind, then let's exit + * here explicitly. valgrind will only generate nice output on + * exit(), not on exec(), hence let's do the former not the + * latter here. */ + if (getpid() == 1 && RUNNING_ON_VALGRIND) + return 0; +#endif + + if (shutdown_verb) { + char log_level[DECIMAL_STR_MAX(int) + 1]; + char exit_code[DECIMAL_STR_MAX(uint8_t) + 1]; + const char* command_line[11] = { + SYSTEMD_SHUTDOWN_BINARY_PATH, + shutdown_verb, + "--log-level", log_level, + "--log-target", + }; + unsigned pos = 5; + _cleanup_strv_free_ char **env_block = NULL; + + assert(command_line[pos] == NULL); + env_block = strv_copy(environ); + + xsprintf(log_level, "%d", log_get_max_level()); + + switch (log_get_target()) { + + case LOG_TARGET_KMSG: + case LOG_TARGET_JOURNAL_OR_KMSG: + case LOG_TARGET_SYSLOG_OR_KMSG: + command_line[pos++] = "kmsg"; + break; + + case LOG_TARGET_NULL: + command_line[pos++] = "null"; + break; + + case LOG_TARGET_CONSOLE: + default: + command_line[pos++] = "console"; + break; + }; + + if (log_get_show_color()) + command_line[pos++] = "--log-color"; + + if (log_get_show_location()) + command_line[pos++] = "--log-location"; + + if (streq(shutdown_verb, "exit")) { + command_line[pos++] = "--exit-code"; + command_line[pos++] = exit_code; + xsprintf(exit_code, "%d", retval); + } + + assert(pos < ELEMENTSOF(command_line)); + + if (arm_reboot_watchdog && arg_shutdown_watchdog > 0 && arg_shutdown_watchdog != USEC_INFINITY) { + char *e; + + /* If we reboot let's set the shutdown + * watchdog and tell the shutdown binary to + * repeatedly ping it */ + r = watchdog_set_timeout(&arg_shutdown_watchdog); + watchdog_close(r < 0); + + /* Tell the binary how often to ping, ignore failure */ + if (asprintf(&e, "WATCHDOG_USEC="USEC_FMT, arg_shutdown_watchdog) > 0) + (void) strv_push(&env_block, e); + } else + watchdog_close(true); + + /* Avoid the creation of new processes forked by the + * kernel; at this point, we will not listen to the + * signals anyway */ + if (detect_container() <= 0) + (void) cg_uninstall_release_agent(SYSTEMD_CGROUP_CONTROLLER); + + execve(SYSTEMD_SHUTDOWN_BINARY_PATH, (char **) command_line, env_block); + log_error_errno(errno, "Failed to execute shutdown binary, %s: %m", + getpid() == 1 ? "freezing" : "quitting"); + } + + if (getpid() == 1) { + if (error_message) + manager_status_printf(NULL, STATUS_TYPE_EMERGENCY, + ANSI_HIGHLIGHT_RED "!!!!!!" ANSI_NORMAL, + "%s, freezing.", error_message); + freeze_or_reboot(); + } + + return retval; +} diff --git a/src/grp-system/systemd/org.freedesktop.systemd1.conf b/src/grp-system/systemd/org.freedesktop.systemd1.conf new file mode 100644 index 0000000000..a61677e645 --- /dev/null +++ b/src/grp-system/systemd/org.freedesktop.systemd1.conf @@ -0,0 +1,256 @@ +<?xml version="1.0"?> <!--*-nxml-*--> +<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN" + "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"> + +<!-- + This file is part of systemd. + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. +--> + +<busconfig> + + <policy user="root"> + <allow own="org.freedesktop.systemd1"/> + + <!-- Root clients can do everything --> + <allow send_destination="org.freedesktop.systemd1"/> + <allow receive_sender="org.freedesktop.systemd1"/> + + <!-- systemd may receive activator requests --> + <allow receive_interface="org.freedesktop.systemd1.Activator" + receive_member="ActivationRequest"/> + </policy> + + <policy context="default"> + <deny send_destination="org.freedesktop.systemd1"/> + + <!-- Completely open to anyone --> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.DBus.Introspectable"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.DBus.Peer"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.DBus.Properties" + send_member="Get"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.DBus.Properties" + send_member="GetAll"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="GetUnit"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="GetUnitByPID"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="GetUnitByInvocationID"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="LoadUnit"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="GetJob"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="ListUnits"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="ListUnitsFiltered"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="ListUnitsByPatterns"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="ListUnitFiles"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="ListUnitFilesByPatterns"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="GetUnitFileState"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="GetUnitProcesses"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="GetUnitFileLinks"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="ListJobs"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="Subscribe"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="Unsubscribe"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="Dump"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="GetDefaultTarget"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="LookupDynamicUserByName"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="LookupDynamicUserByUID"/> + + <!-- Managed via polkit or other criteria --> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="StartUnit"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="StartUnitReplace"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="StopUnit"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="ReloadUnit"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="RestartUnit"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="TryRestartUnit"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="ReloadOrRestartUnit"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="ReloadOrTryRestartUnit"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="KillUnit"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="ResetFailedUnit"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="SetUnitProperties"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="ListUnitsByNames"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="StartTransientUnit"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="CancelJob"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="Reload"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="Reexecute"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="RefUnit"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="UnrefUnit"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="EnableUnitFiles"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="DisableUnitFiles"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="ReenableUnitFiles"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="LinkUnitFiles"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="RevertUnitFiles"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="PresetUnitFiles"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="PresetUnitFilesWithMode"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="MaskUnitFiles"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="UnmaskUnitFiles"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="SetDefaultTarget"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="PresetAllUnitFiles"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Manager" + send_member="AddDependencyUnitFiles"/> + + <allow send_destination="org.freedesktop.systemd1" + send_interface="org.freedesktop.systemd1.Job" + send_member="Cancel"/> + + <allow receive_sender="org.freedesktop.systemd1"/> + </policy> + +</busconfig> diff --git a/src/grp-system/systemd/org.freedesktop.systemd1.policy.in.in b/src/grp-system/systemd/org.freedesktop.systemd1.policy.in.in new file mode 100644 index 0000000000..cc39a9e1c3 --- /dev/null +++ b/src/grp-system/systemd/org.freedesktop.systemd1.policy.in.in @@ -0,0 +1,70 @@ +<?xml version="1.0" encoding="UTF-8"?> <!--*-nxml-*--> +<!DOCTYPE policyconfig PUBLIC "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN" + "http://www.freedesktop.org/standards/PolicyKit/1/policyconfig.dtd"> + +<!-- + This file is part of systemd. + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. +--> + +<policyconfig> + + <vendor>The systemd Project</vendor> + <vendor_url>http://www.freedesktop.org/wiki/Software/systemd</vendor_url> + + <action id="org.freedesktop.systemd1.reply-password"> + <_description>Send passphrase back to system</_description> + <_message>Authentication is required to send the entered passphrase back to the system.</_message> + <defaults> + <allow_any>no</allow_any> + <allow_inactive>no</allow_inactive> + <allow_active>auth_admin_keep</allow_active> + </defaults> + <annotate key="org.freedesktop.policykit.exec.path">@rootlibexecdir@/systemd-reply-password</annotate> + </action> + + <action id="org.freedesktop.systemd1.manage-units"> + <_description>Manage system services or other units</_description> + <_message>Authentication is required to manage system services or other units.</_message> + <defaults> + <allow_any>auth_admin</allow_any> + <allow_inactive>auth_admin</allow_inactive> + <allow_active>auth_admin_keep</allow_active> + </defaults> + </action> + + <action id="org.freedesktop.systemd1.manage-unit-files"> + <_description>Manage system service or unit files</_description> + <_message>Authentication is required to manage system service or unit files.</_message> + <defaults> + <allow_any>auth_admin</allow_any> + <allow_inactive>auth_admin</allow_inactive> + <allow_active>auth_admin_keep</allow_active> + </defaults> + </action> + + <action id="org.freedesktop.systemd1.set-environment"> + <_description>Set or unset system and service manager environment variables</_description> + <_message>Authentication is required to set or unset system and service manager environment variables.</_message> + <defaults> + <allow_any>auth_admin</allow_any> + <allow_inactive>auth_admin</allow_inactive> + <allow_active>auth_admin_keep</allow_active> + </defaults> + </action> + + <action id="org.freedesktop.systemd1.reload-daemon"> + <_description>Reload the systemd state</_description> + <_message>Authentication is required to reload the systemd state.</_message> + <defaults> + <allow_any>auth_admin</allow_any> + <allow_inactive>auth_admin</allow_inactive> + <allow_active>auth_admin_keep</allow_active> + </defaults> + </action> + +</policyconfig> diff --git a/src/grp-system/systemd/org.freedesktop.systemd1.service b/src/grp-system/systemd/org.freedesktop.systemd1.service new file mode 100644 index 0000000000..d4df3e93a2 --- /dev/null +++ b/src/grp-system/systemd/org.freedesktop.systemd1.service @@ -0,0 +1,11 @@ +# This file is part of systemd. +# +# systemd is free software; you can redistribute it and/or modify it +# under the terms of the GNU Lesser General Public License as published by +# the Free Software Foundation; either version 2.1 of the License, or +# (at your option) any later version. + +[D-BUS Service] +Name=org.freedesktop.systemd1 +Exec=/bin/false +User=root diff --git a/src/grp-system/systemd/system.conf b/src/grp-system/systemd/system.conf new file mode 100644 index 0000000000..746572b7ff --- /dev/null +++ b/src/grp-system/systemd/system.conf @@ -0,0 +1,62 @@ +# This file is part of systemd. +# +# systemd is free software; you can redistribute it and/or modify it +# under the terms of the GNU Lesser General Public License as published by +# the Free Software Foundation; either version 2.1 of the License, or +# (at your option) any later version. +# +# Entries in this file show the compile time defaults. +# You can change settings by editing this file. +# Defaults can be restored by simply deleting this file. +# +# See systemd-system.conf(5) for details. + +[Manager] +#LogLevel=info +#LogTarget=journal-or-kmsg +#LogColor=yes +#LogLocation=no +#DumpCore=yes +#ShowStatus=yes +#CrashChangeVT=no +#CrashShell=no +#CrashReboot=no +#CtrlAltDelBurstAction=reboot-force +#CPUAffinity=1 2 +#JoinControllers=cpu,cpuacct net_cls,net_prio +#RuntimeWatchdogSec=0 +#ShutdownWatchdogSec=10min +#CapabilityBoundingSet= +#SystemCallArchitectures= +#TimerSlackNSec= +#DefaultTimerAccuracySec=1min +#DefaultStandardOutput=journal +#DefaultStandardError=inherit +#DefaultTimeoutStartSec=90s +#DefaultTimeoutStopSec=90s +#DefaultRestartSec=100ms +#DefaultStartLimitIntervalSec=10s +#DefaultStartLimitBurst=5 +#DefaultEnvironment= +#DefaultCPUAccounting=no +#DefaultIOAccounting=no +#DefaultBlockIOAccounting=no +#DefaultMemoryAccounting=no +#DefaultTasksAccounting=yes +#DefaultTasksMax=15% +#DefaultLimitCPU= +#DefaultLimitFSIZE= +#DefaultLimitDATA= +#DefaultLimitSTACK= +#DefaultLimitCORE= +#DefaultLimitRSS= +#DefaultLimitNOFILE= +#DefaultLimitAS= +#DefaultLimitNPROC= +#DefaultLimitMEMLOCK= +#DefaultLimitLOCKS= +#DefaultLimitSIGPENDING= +#DefaultLimitMSGQUEUE= +#DefaultLimitNICE= +#DefaultLimitRTPRIO= +#DefaultLimitRTTIME= diff --git a/src/grp-system/systemd/systemd-system.conf.xml b/src/grp-system/systemd/systemd-system.conf.xml new file mode 100644 index 0000000000..e4e81f7f2e --- /dev/null +++ b/src/grp-system/systemd/systemd-system.conf.xml @@ -0,0 +1,405 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-system.conf" + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>systemd-system.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-system.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-system.conf</refname> + <refname>system.conf.d</refname> + <refname>systemd-user.conf</refname> + <refname>user.conf.d</refname> + <refpurpose>System and session service manager configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/system.conf</filename>, + <filename>/etc/systemd/system.conf.d/*.conf</filename>, + <filename>/run/systemd/system.conf.d/*.conf</filename>, + <filename>/usr/lib/systemd/system.conf.d/*.conf</filename></para> + <para><filename>/etc/systemd/user.conf</filename>, + <filename>/etc/systemd/user.conf.d/*.conf</filename>, + <filename>/run/systemd/user.conf.d/*.conf</filename>, + <filename>/usr/lib/systemd/user.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>When run as a system instance, systemd interprets the + configuration file <filename>system.conf</filename> and the files + in <filename>system.conf.d</filename> directories; when run as a + user instance, systemd interprets the configuration file + <filename>user.conf</filename> and the files in + <filename>user.conf.d</filename> directories. These configuration + files contain a few settings controlling basic manager + operations.</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="main-conf" /> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the + <literal>[Manager]</literal> section:</para> + + <variablelist class='systemd-directives'> + + <varlistentry> + <term><varname>LogLevel=</varname></term> + <term><varname>LogTarget=</varname></term> + <term><varname>LogColor=</varname></term> + <term><varname>LogLocation=</varname></term> + <term><varname>DumpCore=yes</varname></term> + <term><varname>CrashChangeVT=no</varname></term> + <term><varname>CrashShell=no</varname></term> + <term><varname>CrashReboot=no</varname></term> + <term><varname>ShowStatus=yes</varname></term> + <term><varname>DefaultStandardOutput=journal</varname></term> + <term><varname>DefaultStandardError=inherit</varname></term> + + <listitem><para>Configures various parameters of basic manager + operation. These options may be overridden by the respective + command line arguments. See + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details about these command line + arguments.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CtrlAltDelBurstAction=</varname></term> + + <listitem><para>Defines what action will be performed + if user presses Ctrl-Alt-Delete more than 7 times in 2s. + Can be set to <literal>reboot-force</literal>, <literal>poweroff-force</literal>, + <literal>reboot-immediate</literal>, <literal>poweroff-immediate</literal> + or disabled with <literal>none</literal>. Defaults to + <literal>reboot-force</literal>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUAffinity=</varname></term> + + <listitem><para>Configures the initial CPU affinity for the + init process. Takes a list of CPU indices or ranges separated + by either whitespace or commas. CPU ranges are specified by + the lower and upper CPU indices separated by a + dash.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>JoinControllers=cpu,cpuacct net_cls,netprio</varname></term> + + <listitem><para>Configures controllers that shall be mounted + in a single hierarchy. By default, systemd will mount all + controllers which are enabled in the kernel in individual + hierarchies, with the exception of those listed in this + setting. Takes a space-separated list of comma-separated + controller names, in order to allow multiple joined + hierarchies. Defaults to 'cpu,cpuacct'. Pass an empty string + to ensure that systemd mounts all controllers in separate + hierarchies.</para> + + <para>Note that this option is only applied once, at very + early boot. If you use an initial RAM disk (initrd) that uses + systemd, it might hence be necessary to rebuild the initrd if + this option is changed, and make sure the new configuration + file is included in it. Otherwise, the initrd might mount the + controller hierarchies in a different configuration than + intended, and the main system cannot remount them + anymore.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RuntimeWatchdogSec=</varname></term> + <term><varname>ShutdownWatchdogSec=</varname></term> + + <listitem><para>Configure the hardware watchdog at runtime and + at reboot. Takes a timeout value in seconds (or in other time + units if suffixed with <literal>ms</literal>, + <literal>min</literal>, <literal>h</literal>, + <literal>d</literal>, <literal>w</literal>). If + <varname>RuntimeWatchdogSec=</varname> is set to a non-zero + value, the watchdog hardware + (<filename>/dev/watchdog</filename>) will be programmed to + automatically reboot the system if it is not contacted within + the specified timeout interval. The system manager will ensure + to contact it at least once in half the specified timeout + interval. This feature requires a hardware watchdog device to + be present, as it is commonly the case in embedded and server + systems. Not all hardware watchdogs allow configuration of the + reboot timeout, in which case the closest available timeout is + picked. <varname>ShutdownWatchdogSec=</varname> may be used to + configure the hardware watchdog when the system is asked to + reboot. It works as a safety net to ensure that the reboot + takes place even if a clean reboot attempt times out. By + default <varname>RuntimeWatchdogSec=</varname> defaults to 0 + (off), and <varname>ShutdownWatchdogSec=</varname> to 10min. + These settings have no effect if a hardware watchdog is not + available.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CapabilityBoundingSet=</varname></term> + + <listitem><para>Controls which capabilities to include in the + capability bounding set for PID 1 and its children. See + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details. Takes a whitespace-separated list of capability + names as read by + <citerefentry project='mankier'><refentrytitle>cap_from_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Capabilities listed will be included in the bounding set, all + others are removed. If the list of capabilities is prefixed + with ~, all but the listed capabilities will be included, the + effect of the assignment inverted. Note that this option also + affects the respective capabilities in the effective, + permitted and inheritable capability sets. The capability + bounding set may also be individually configured for units + using the <varname>CapabilityBoundingSet=</varname> directive + for units, but note that capabilities dropped for PID 1 cannot + be regained in individual units, they are lost for + good.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SystemCallArchitectures=</varname></term> + + <listitem><para>Takes a space-separated list of architecture + identifiers. Selects from which architectures system calls may + be invoked on this system. This may be used as an effective + way to disable invocation of non-native binaries system-wide, + for example to prohibit execution of 32-bit x86 binaries on + 64-bit x86-64 systems. This option operates system-wide, and + acts similar to the + <varname>SystemCallArchitectures=</varname> setting of unit + files, see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. This setting defaults to the empty list, in which + case no filtering of system calls based on architecture is + applied. Known architecture identifiers are + <literal>x86</literal>, <literal>x86-64</literal>, + <literal>x32</literal>, <literal>arm</literal> and the special + identifier <literal>native</literal>. The latter implicitly + maps to the native architecture of the system (or more + specifically, the architecture the system manager was compiled + for). Set this setting to <literal>native</literal> to + prohibit execution of any non-native binaries. When a binary + executes a system call of an architecture that is not listed + in this setting, it will be immediately terminated with the + SIGSYS signal.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimerSlackNSec=</varname></term> + + <listitem><para>Sets the timer slack in nanoseconds for PID 1, + which is inherited by all executed processes, unless + overridden individually, for example with the + <varname>TimerSlackNSec=</varname> setting in service units + (for details see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + The timer slack controls the accuracy of wake-ups triggered by + system timers. See + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more information. Note that in contrast to most other time + span definitions this parameter takes an integer value in + nano-seconds if no unit is specified. The usual time units are + understood too.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultTimerAccuracySec=</varname></term> + + <listitem><para>Sets the default accuracy of timer units. This + controls the global default for the + <varname>AccuracySec=</varname> setting of timer units, see + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. <varname>AccuracySec=</varname> set in individual + units override the global default for the specific unit. + Defaults to 1min. Note that the accuracy of timer units is + also affected by the configured timer slack for PID 1, see + <varname>TimerSlackNSec=</varname> above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultTimeoutStartSec=</varname></term> + <term><varname>DefaultTimeoutStopSec=</varname></term> + <term><varname>DefaultRestartSec=</varname></term> + + <listitem><para>Configures the default timeouts for starting + and stopping of units, as well as the default time to sleep + between automatic restarts of units, as configured per-unit in + <varname>TimeoutStartSec=</varname>, + <varname>TimeoutStopSec=</varname> and + <varname>RestartSec=</varname> (for services, see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on the per-unit settings). For non-service units, + <varname>DefaultTimeoutStartSec=</varname> sets the default + <varname>TimeoutSec=</varname> + value. <varname>DefaultTimeoutStartSec=</varname> and + <varname>DefaultTimeoutStopSec=</varname> default to + 90s. <varname>DefaultRestartSec=</varname> defaults to + 100ms.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultStartLimitIntervalSec=</varname></term> + <term><varname>DefaultStartLimitBurst=</varname></term> + + <listitem><para>Configure the default unit start rate + limiting, as configured per-service by + <varname>StartLimitIntervalSec=</varname> and + <varname>StartLimitBurst=</varname>. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on the per-service settings. + <varname>DefaultStartLimitIntervalSec=</varname> defaults to + 10s. <varname>DefaultStartLimitBurst=</varname> defaults to + 5.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultEnvironment=</varname></term> + + <listitem><para>Sets manager environment variables passed to + all executed processes. Takes a space-separated list of + variable assignments. See + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about environment variables.</para> + + <para>Example: + + <programlisting>DefaultEnvironment="VAR1=word1 word2" VAR2=word3 "VAR3=word 5 6"</programlisting> + + Sets three variables + <literal>VAR1</literal>, + <literal>VAR2</literal>, + <literal>VAR3</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultCPUAccounting=</varname></term> + <term><varname>DefaultBlockIOAccounting=</varname></term> + <term><varname>DefaultMemoryAccounting=</varname></term> + <term><varname>DefaultTasksAccounting=</varname></term> + + <listitem><para>Configure the default resource accounting + settings, as configured per-unit by + <varname>CPUAccounting=</varname>, + <varname>BlockIOAccounting=</varname>, + <varname>MemoryAccounting=</varname> and + <varname>TasksAccounting=</varname>. See + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on the per-unit + settings. <varname>DefaultTasksAccounting=</varname> defaults + to on, the other three settings to off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultTasksMax=</varname></term> + + <listitem><para>Configure the default value for the per-unit <varname>TasksMax=</varname> setting. See + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. This setting applies to all unit types that support resource control settings, with the exception + of slice units. Defaults to 15%, which equals 4915 with the kernel's defaults on the host, but might be smaller + in OS containers.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultLimitCPU=</varname></term> + <term><varname>DefaultLimitFSIZE=</varname></term> + <term><varname>DefaultLimitDATA=</varname></term> + <term><varname>DefaultLimitSTACK=</varname></term> + <term><varname>DefaultLimitCORE=</varname></term> + <term><varname>DefaultLimitRSS=</varname></term> + <term><varname>DefaultLimitNOFILE=</varname></term> + <term><varname>DefaultLimitAS=</varname></term> + <term><varname>DefaultLimitNPROC=</varname></term> + <term><varname>DefaultLimitMEMLOCK=</varname></term> + <term><varname>DefaultLimitLOCKS=</varname></term> + <term><varname>DefaultLimitSIGPENDING=</varname></term> + <term><varname>DefaultLimitMSGQUEUE=</varname></term> + <term><varname>DefaultLimitNICE=</varname></term> + <term><varname>DefaultLimitRTPRIO=</varname></term> + <term><varname>DefaultLimitRTTIME=</varname></term> + + <listitem><para>These settings control various default + resource limits for units. See + <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. The resource limit is possible to specify in two formats, + <option>value</option> to set soft and hard limits to the same value, + or <option>soft:hard</option> to set both limits individually (e.g. DefaultLimitAS=4G:16G). + Use the string <varname>infinity</varname> to + configure no limit on a specific resource. The multiplicative + suffixes K (=1024), M (=1024*1024) and so on for G, T, P and E + may be used for resource limits measured in bytes + (e.g. DefaultLimitAS=16G). For the limits referring to time values, + the usual time units ms, s, min, h and so on may be used (see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). Note that if no time unit is specified for + <varname>DefaultLimitCPU=</varname> the default unit of seconds is + implied, while for <varname>DefaultLimitRTTIME=</varname> the default + unit of microseconds is implied. Also, note that the effective + granularity of the limits might influence their + enforcement. For example, time limits specified for + <varname>DefaultLimitCPU=</varname> will be rounded up implicitly to + multiples of 1s. These settings may be overridden in individual units + using the corresponding LimitXXX= directives. Note that these resource + limits are only defaults for units, they are not applied to PID 1 + itself.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd-tmpfs.tmpfiles b/src/grp-system/systemd/systemd-tmpfs.tmpfiles new file mode 100644 index 0000000000..98050d329d --- /dev/null +++ b/src/grp-system/systemd/systemd-tmpfs.tmpfiles @@ -0,0 +1,14 @@ +# This file is part of systemd. +# +# systemd is free software; you can redistribute it and/or modify it +# under the terms of the GNU Lesser General Public License as published by +# the Free Software Foundation; either version 2.1 of the License, or +# (at your option) any later version. + +# See tmpfiles.d(5) for details + +# Exclude namespace mountpoints created with PrivateTmp=yes +x /tmp/systemd-private-%b-* +X /tmp/systemd-private-%b-*/tmp +x /var/tmp/systemd-private-%b-* +X /var/tmp/systemd-private-%b-*/tmp diff --git a/src/grp-system/systemd/systemd.automount.xml b/src/grp-system/systemd/systemd.automount.xml new file mode 100644 index 0000000000..a43dc981bd --- /dev/null +++ b/src/grp-system/systemd/systemd.automount.xml @@ -0,0 +1,173 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.automount"> + <refentryinfo> + <title>systemd.automount</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.automount</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.automount</refname> + <refpurpose>Automount unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>automount</replaceable>.automount</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.automount</literal> encodes information about a file + system automount point controlled and supervised by + systemd.</para> + + <para>This man page lists the configuration options specific to + this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic [Unit] and + [Install] sections. The automount specific configuration options + are configured in the [Automount] section.</para> + + <para>Automount units must be named after the automount directories they control. Example: the automount point + <filename noindex='true'>/home/lennart</filename> must be configured in a unit file + <filename>home-lennart.automount</filename>. For details about the escaping logic used to convert a file system + path to a unit name see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that + automount units cannot be templated, nor is it possible to add multiple names to an automount unit by creating + additional symlinks to its unit file.</para> + + <para>For each automount unit file a matching mount unit file (see + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) must exist which is activated when the automount path + is accessed. Example: if an automount unit + <filename>home-lennart.automount</filename> is active and the user + accesses <filename>/home/lennart</filename> the mount unit + <filename>home-lennart.mount</filename> will be activated.</para> + + <para>Automount units may be used to implement on-demand mounting + as well as parallelized mounting of file systems.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>If an automount unit is beneath another mount unit in the + file system hierarchy, both a requirement and an ordering + dependency between both units are created automatically.</para> + + <para>An implicit <varname>Before=</varname> dependency is created + between an automount unit and the mount unit it activates.</para> + + <para>Automount units acquire automatic <varname>Before=</varname> and <varname>Conflicts=</varname> on + <filename>umount.target</filename> in order to be stopped during shutdown, unless + <varname>DefaultDependencies=no</varname> is set in the <literal>[Unit]</literal> section.</para> + + </refsect1> + + <refsect1> + <title><filename>fstab</filename></title> + + <para>Automount units may either be configured via unit files, or + via <filename>/etc/fstab</filename> (see + <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details).</para> + + <para>For details how systemd parses + <filename>/etc/fstab</filename> see + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>If an automount point is configured in both + <filename>/etc/fstab</filename> and a unit file, the configuration + in the latter takes precedence.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Automount files must include an [Automount] section, which + carries information about the file system automount points it + supervises. The options specific to the [Automount] section of + automount units are the following:</para> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>Where=</varname></term> + <listitem><para>Takes an absolute path of a directory of the + automount point. If the automount point does not exist at time + that the automount point is installed, it is created. This + string must be reflected in the unit filename. (See above.) + This option is mandatory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DirectoryMode=</varname></term> + <listitem><para>Directories of automount points (and any + parent directories) are automatically created if needed. This + option specifies the file system access mode used when + creating these directories. Takes an access mode in octal + notation. Defaults to 0755.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>TimeoutIdleSec=</varname></term> + <listitem><para>Configures an idle timeout. Once the mount has been + idle for the specified time, systemd will attempt to unmount. Takes a + unit-less value in seconds, or a time span value such as "5min 20s". + Pass 0 to disable the timeout logic. The timeout is disabled by + default.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>automount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.device.xml b/src/grp-system/systemd/systemd.device.xml new file mode 100644 index 0000000000..effed098dd --- /dev/null +++ b/src/grp-system/systemd/systemd.device.xml @@ -0,0 +1,182 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.device"> + <refentryinfo> + <title>systemd.device</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.device</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.device</refname> + <refpurpose>Device unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>device</replaceable>.device</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.device</literal> encodes information about a device unit + as exposed in the + sysfs/<citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> + device tree.</para> + + <para>This unit type has no specific options. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic + <literal>[Unit]</literal> and <literal>[Install]</literal> + sections. A separate <literal>[Device]</literal> section does not + exist, since no device-specific options may be configured.</para> + + <para>systemd will dynamically create device units for all kernel + devices that are marked with the "systemd" udev tag (by default + all block and network devices, and a few others). This may be used + to define dependencies between devices and other units. To tag a + udev device, use <literal>TAG+="systemd"</literal> in the udev + rules file, see + <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.</para> + + <para>Device units are named after the <filename>/sys</filename> + and <filename>/dev</filename> paths they control. Example: the + device <filename noindex='true'>/dev/sda5</filename> is exposed in + systemd as <filename>dev-sda5.device</filename>. For details about + the escaping logic used to convert a file system path to a unit + name see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>Many unit types automatically acquire dependencies on device + units of devices they require. For example, + <filename>.socket</filename> unit acquire dependencies on the + device units of the network interface specified in + <varname>BindToDevice=</varname>. Similar, swap and mount units + acquire dependencies on the units encapsulating their backing + block devices.</para> + </refsect1> + + <refsect1> + <title>The udev Database</title> + + <para>The settings of device units may either be configured via + unit files, or directly from the udev database (which is + recommended). The following udev device properties are understood + by systemd:</para> + + <variablelist class='udev-directives'> + <varlistentry> + <term><varname>SYSTEMD_WANTS=</varname></term> + <term><varname>SYSTEMD_USER_WANTS=</varname></term> + <listitem><para>Adds dependencies of type + <varname>Wants</varname> from the device unit to all listed + units. The first form is used by the system systemd instance, + the second by user systemd instances. Those settings may be + used to activate arbitrary units when a specific device + becomes available.</para> + + <para>Note that this and the other tags are not taken into + account unless the device is tagged with the + <literal>systemd</literal> string in the udev database, + because otherwise the device is not exposed as a systemd unit + (see above).</para> + + <para>Note that systemd will only act on + <varname>Wants</varname> dependencies when a device first + becomes active. It will not act on them if they are added to + devices that are already active. Use + <varname>SYSTEMD_READY=</varname> (see below) to influence on + which udev event to trigger the dependencies. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SYSTEMD_ALIAS=</varname></term> + <listitem><para>Adds an additional alias name to the device + unit. This must be an absolute path that is automatically + transformed into a unit name. (See above.)</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SYSTEMD_READY=</varname></term> + <listitem><para>If set to 0, systemd will consider this device + unplugged even if it shows up in the udev tree. If this + property is unset or set to 1, the device will be considered + plugged if it is visible in the udev tree. This property has + no influence on the behavior when a device disappears from the + udev tree.</para> + + <para>This option is useful to support devices that initially + show up in an uninitialized state in the tree, and for which a + <literal>changed</literal> event is generated the moment they + are fully set up. Note that <varname>SYSTEMD_WANTS=</varname> + (see above) is not acted on as long as + <varname>SYSTEMD_READY=0</varname> is set for a + device.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ID_MODEL_FROM_DATABASE=</varname></term> + <term><varname>ID_MODEL=</varname></term> + + <listitem><para>If set, this property is used as description + string for the device unit.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.exec.xml b/src/grp-system/systemd/systemd.exec.xml new file mode 100644 index 0000000000..3c350df11f --- /dev/null +++ b/src/grp-system/systemd/systemd.exec.xml @@ -0,0 +1,1863 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.exec"> + <refentryinfo> + <title>systemd.exec</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.exec</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.exec</refname> + <refpurpose>Execution environment configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>service</replaceable>.service</filename>, + <filename><replaceable>socket</replaceable>.socket</filename>, + <filename><replaceable>mount</replaceable>.mount</filename>, + <filename><replaceable>swap</replaceable>.swap</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Unit configuration files for services, sockets, mount + points, and swap devices share a subset of configuration options + which define the execution environment of spawned + processes.</para> + + <para>This man page lists the configuration options shared by + these four unit types. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files, and + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + and + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information on the specific unit configuration files. The + execution specific configuration options are configured in the + [Service], [Socket], [Mount], or [Swap] sections, depending on the + unit type.</para> + + <para>In addition, options which control resources through Linux Control Groups (cgroups) are listed in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Those options complement options listed here.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>A few execution parameters result in additional, automatic + dependencies to be added.</para> + + <para>Units with <varname>WorkingDirectory=</varname> or + <varname>RootDirectory=</varname> set automatically gain + dependencies of type <varname>Requires=</varname> and + <varname>After=</varname> on all mount units required to access + the specified paths. This is equivalent to having them listed + explicitly in <varname>RequiresMountsFor=</varname>.</para> + + <para>Similar, units with <varname>PrivateTmp=</varname> enabled + automatically get mount unit dependencies for all mounts + required to access <filename>/tmp</filename> and + <filename>/var/tmp</filename>.</para> + + <para>Units whose standard output or error output is connected to <option>journal</option>, <option>syslog</option> + or <option>kmsg</option> (or their combinations with console output, see below) automatically acquire dependencies + of type <varname>After=</varname> on <filename>systemd-journald.socket</filename>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>WorkingDirectory=</varname></term> + + <listitem><para>Takes a directory path relative to the service's root directory specified by + <varname>RootDirectory=</varname>, or the special value <literal>~</literal>. Sets the working directory for + executed processes. If set to <literal>~</literal>, the home directory of the user specified in + <varname>User=</varname> is used. If not set, defaults to the root directory when systemd is running as a + system instance and the respective user's home directory if run as user. If the setting is prefixed with the + <literal>-</literal> character, a missing working directory is not considered fatal. If + <varname>RootDirectory=</varname> is not set, then <varname>WorkingDirectory=</varname> is relative to the root + of the system running the service manager. Note that setting this parameter might result in additional + dependencies to be added to the unit (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RootDirectory=</varname></term> + + <listitem><para>Takes a directory path relative to the host's root directory (i.e. the root of the system + running the service manager). Sets the root directory for executed processes, with the <citerefentry + project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system + call. If this is used, it must be ensured that the process binary and all its auxiliary files are available in + the <function>chroot()</function> jail. Note that setting this parameter might result in additional + dependencies to be added to the unit (see above).</para> + + <para>The <varname>PrivateUsers=</varname> setting is particularly useful in conjunction with + <varname>RootDirectory=</varname>. For details, see below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>User=</varname></term> + <term><varname>Group=</varname></term> + + <listitem><para>Set the UNIX user or group that the processes are executed as, respectively. Takes a single + user or group name, or numeric ID as argument. For system services (services run by the system service manager, + i.e. managed by PID 1) and for user services of the root user (services managed by root's instance of + <command>systemd --user</command>), the default is <literal>root</literal>, but <varname>User=</varname> may be + used to specify a different user. For user services of any other user, switching user identity is not + permitted, hence the only valid setting is the same user the user's service manager is running as. If no group + is set, the default group of the user is used. This setting does not affect commands whose command line is + prefixed with <literal>+</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DynamicUser=</varname></term> + + <listitem><para>Takes a boolean parameter. If set, a UNIX user and group pair is allocated dynamically when the + unit is started, and released as soon as it is stopped. The user and group will not be added to + <filename>/etc/passwd</filename> or <filename>/etc/group</filename>, but are managed transiently during + runtime. The <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + glibc NSS module provides integration of these dynamic users/groups into the system's user and group + databases. The user and group name to use may be configured via <varname>User=</varname> and + <varname>Group=</varname> (see above). If these options are not used and dynamic user/group allocation is + enabled for a unit, the name of the dynamic user/group is implicitly derived from the unit name. If the unit + name without the type suffix qualifies as valid user name it is used directly, otherwise a name incorporating a + hash of it is used. If a statically allocated user or group of the configured name already exists, it is used + and no dynamic user/group is allocated. Dynamic users/groups are allocated from the UID/GID range + 61184…65519. It is recommended to avoid this range for regular system or login users. At any point in time + each UID/GID from this range is only assigned to zero or one dynamically allocated users/groups in + use. However, UID/GIDs are recycled after a unit is terminated. Care should be taken that any processes running + as part of a unit for which dynamic users/groups are enabled do not leave files or directories owned by these + users/groups around, as a different unit might get the same UID/GID assigned later on, and thus gain access to + these files or directories. If <varname>DynamicUser=</varname> is enabled, <varname>RemoveIPC=</varname>, + <varname>PrivateTmp=</varname> are implied. This ensures that the lifetime of IPC objects and temporary files + created by the executed processes is bound to the runtime of the service, and hence the lifetime of the dynamic + user/group. Since <filename>/tmp</filename> and <filename>/var/tmp</filename> are usually the only + world-writable directories on a system this ensures that a unit making use of dynamic user/group allocation + cannot leave files around after unit termination. Moreover <varname>ProtectSystem=strict</varname> and + <varname>ProtectHome=read-only</varname> are implied, thus prohibiting the service to write to arbitrary file + system locations. In order to allow the service to write to certain directories, they have to be whitelisted + using <varname>ReadWritePaths=</varname>, but care must be taken so that UID/GID recycling doesn't + create security issues involving files created by the service. Use <varname>RuntimeDirectory=</varname> (see + below) in order to assign a writable runtime directory to a service, owned by the dynamic user/group and + removed automatically when the unit is terminated. Defaults to off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SupplementaryGroups=</varname></term> + + <listitem><para>Sets the supplementary Unix groups the + processes are executed as. This takes a space-separated list + of group names or IDs. This option may be specified more than + once, in which case all listed groups are set as supplementary + groups. When the empty string is assigned, the list of + supplementary groups is reset, and all assignments prior to + this one will have no effect. In any way, this option does not + override, but extends the list of supplementary groups + configured in the system group database for the + user. This does not affect commands prefixed with <literal>+</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RemoveIPC=</varname></term> + + <listitem><para>Takes a boolean parameter. If set, all System V and POSIX IPC objects owned by the user and + group the processes of this unit are run as are removed when the unit is stopped. This setting only has an + effect if at least one of <varname>User=</varname>, <varname>Group=</varname> and + <varname>DynamicUser=</varname> are used. It has no effect on IPC objects owned by the root user. Specifically, + this removes System V semaphores, as well as System V and POSIX shared memory segments and message queues. If + multiple units use the same user or group the IPC objects are removed when the last of these units is + stopped. This setting is implied if <varname>DynamicUser=</varname> is set.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Nice=</varname></term> + + <listitem><para>Sets the default nice level (scheduling + priority) for executed processes. Takes an integer between -20 + (highest priority) and 19 (lowest priority). See + <citerefentry><refentrytitle>setpriority</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>OOMScoreAdjust=</varname></term> + + <listitem><para>Sets the adjustment level for the + Out-Of-Memory killer for executed processes. Takes an integer + between -1000 (to disable OOM killing for this process) and + 1000 (to make killing of this process under memory pressure + very likely). See <ulink + url="https://www.kernel.org/doc/Documentation/filesystems/proc.txt">proc.txt</ulink> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOSchedulingClass=</varname></term> + + <listitem><para>Sets the I/O scheduling class for executed + processes. Takes an integer between 0 and 3 or one of the + strings <option>none</option>, <option>realtime</option>, + <option>best-effort</option> or <option>idle</option>. See + <citerefentry><refentrytitle>ioprio_set</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOSchedulingPriority=</varname></term> + + <listitem><para>Sets the I/O scheduling priority for executed + processes. Takes an integer between 0 (highest priority) and 7 + (lowest priority). The available priorities depend on the + selected I/O scheduling class (see above). See + <citerefentry><refentrytitle>ioprio_set</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUSchedulingPolicy=</varname></term> + + <listitem><para>Sets the CPU scheduling policy for executed + processes. Takes one of + <option>other</option>, + <option>batch</option>, + <option>idle</option>, + <option>fifo</option> or + <option>rr</option>. See + <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUSchedulingPriority=</varname></term> + + <listitem><para>Sets the CPU scheduling priority for executed + processes. The available priority range depends on the + selected CPU scheduling policy (see above). For real-time + scheduling policies an integer between 1 (lowest priority) and + 99 (highest priority) can be used. See + <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUSchedulingResetOnFork=</varname></term> + + <listitem><para>Takes a boolean argument. If true, elevated + CPU scheduling priorities and policies will be reset when the + executed processes fork, and can hence not leak into child + processes. See + <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. Defaults to false.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUAffinity=</varname></term> + + <listitem><para>Controls the CPU affinity of the executed + processes. Takes a list of CPU indices or ranges separated by + either whitespace or commas. CPU ranges are specified by the + lower and upper CPU indices separated by a dash. + This option may be specified more than once, in which case the + specified CPU affinity masks are merged. If the empty string + is assigned, the mask is reset, all assignments prior to this + will have no effect. See + <citerefentry><refentrytitle>sched_setaffinity</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>UMask=</varname></term> + + <listitem><para>Controls the file mode creation mask. Takes an + access mode in octal notation. See + <citerefentry><refentrytitle>umask</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. Defaults to 0022.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Environment=</varname></term> + + <listitem><para>Sets environment variables for executed + processes. Takes a space-separated list of variable + assignments. This option may be specified more than once, in + which case all listed variables will be set. If the same + variable is set twice, the later setting will override the + earlier setting. If the empty string is assigned to this + option, the list of environment variables is reset, all prior + assignments have no effect. Variable expansion is not + performed inside the strings, however, specifier expansion is + possible. The $ character has no special meaning. If you need + to assign a value containing spaces to a variable, use double + quotes (") for the assignment.</para> + + <para>Example: + <programlisting>Environment="VAR1=word1 word2" VAR2=word3 "VAR3=$word 5 6"</programlisting> + gives three variables <literal>VAR1</literal>, + <literal>VAR2</literal>, <literal>VAR3</literal> + with the values <literal>word1 word2</literal>, + <literal>word3</literal>, <literal>$word 5 6</literal>. + </para> + + <para> + See + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about environment variables.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>EnvironmentFile=</varname></term> + <listitem><para>Similar to <varname>Environment=</varname> but + reads the environment variables from a text file. The text + file should contain new-line-separated variable assignments. + Empty lines, lines without an <literal>=</literal> separator, + or lines starting with ; or # will be ignored, + which may be used for commenting. A line ending with a + backslash will be concatenated with the following one, + allowing multiline variable definitions. The parser strips + leading and trailing whitespace from the values of + assignments, unless you use double quotes (").</para> + + <para>The argument passed should be an absolute filename or + wildcard expression, optionally prefixed with + <literal>-</literal>, which indicates that if the file does + not exist, it will not be read and no error or warning message + is logged. This option may be specified more than once in + which case all specified files are read. If the empty string + is assigned to this option, the list of file to read is reset, + all prior assignments have no effect.</para> + + <para>The files listed with this directive will be read + shortly before the process is executed (more specifically, + after all processes from a previous unit state terminated. + This means you can generate these files in one unit state, and + read it with this option in the next).</para> + + <para>Settings from these + files override settings made with + <varname>Environment=</varname>. If the same variable is set + twice from these files, the files will be read in the order + they are specified and the later setting will override the + earlier setting.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PassEnvironment=</varname></term> + + <listitem><para>Pass environment variables from the systemd system + manager to executed processes. Takes a space-separated list of variable + names. This option may be specified more than once, in which case all + listed variables will be set. If the empty string is assigned to this + option, the list of environment variables is reset, all prior + assignments have no effect. Variables that are not set in the system + manager will not be passed and will be silently ignored.</para> + + <para>Variables passed from this setting are overridden by those passed + from <varname>Environment=</varname> or + <varname>EnvironmentFile=</varname>.</para> + + <para>Example: + <programlisting>PassEnvironment=VAR1 VAR2 VAR3</programlisting> + passes three variables <literal>VAR1</literal>, + <literal>VAR2</literal>, <literal>VAR3</literal> + with the values set for those variables in PID1.</para> + + <para> + See + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about environment variables.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>StandardInput=</varname></term> + <listitem><para>Controls where file descriptor 0 (STDIN) of + the executed processes is connected to. Takes one of + <option>null</option>, + <option>tty</option>, + <option>tty-force</option>, + <option>tty-fail</option>, + <option>socket</option> or + <option>fd</option>.</para> + + <para>If <option>null</option> is selected, standard input + will be connected to <filename>/dev/null</filename>, i.e. all + read attempts by the process will result in immediate + EOF.</para> + + <para>If <option>tty</option> is selected, standard input is + connected to a TTY (as configured by + <varname>TTYPath=</varname>, see below) and the executed + process becomes the controlling process of the terminal. If + the terminal is already being controlled by another process, + the executed process waits until the current controlling + process releases the terminal.</para> + + <para><option>tty-force</option> is similar to + <option>tty</option>, but the executed process is forcefully + and immediately made the controlling process of the terminal, + potentially removing previous controlling processes from the + terminal.</para> + + <para><option>tty-fail</option> is similar to + <option>tty</option> but if the terminal already has a + controlling process start-up of the executed process + fails.</para> + + <para>The <option>socket</option> option is only valid in + socket-activated services, and only when the socket + configuration file (see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) specifies a single socket only. If this option is + set, standard input will be connected to the socket the + service was activated from, which is primarily useful for + compatibility with daemons designed for use with the + traditional + <citerefentry project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + daemon.</para> + + <para>The <option>fd</option> option connects + the input stream to a single file descriptor provided by a socket unit. + A custom named file descriptor can be specified as part of this option, + after a <literal>:</literal> (e.g. <literal>fd:<replaceable>foobar</replaceable></literal>). + If no name is specified, <literal>stdin</literal> is assumed + (i.e. <literal>fd</literal> is equivalent to <literal>fd:stdin</literal>). + At least one socket unit defining such name must be explicitly provided via the + <varname>Sockets=</varname> option, and file descriptor name may differ + from the name of its containing socket unit. + If multiple matches are found, the first one will be used. + See <varname>FileDescriptorName=</varname> in + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more details about named descriptors and ordering.</para> + + <para>This setting defaults to + <option>null</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>StandardOutput=</varname></term> + <listitem><para>Controls where file descriptor 1 (STDOUT) of + the executed processes is connected to. Takes one of + <option>inherit</option>, + <option>null</option>, + <option>tty</option>, + <option>journal</option>, + <option>syslog</option>, + <option>kmsg</option>, + <option>journal+console</option>, + <option>syslog+console</option>, + <option>kmsg+console</option>, + <option>socket</option> or + <option>fd</option>.</para> + + <para><option>inherit</option> duplicates the file descriptor + of standard input for standard output.</para> + + <para><option>null</option> connects standard output to + <filename>/dev/null</filename>, i.e. everything written to it + will be lost.</para> + + <para><option>tty</option> connects standard output to a tty + (as configured via <varname>TTYPath=</varname>, see below). If + the TTY is used for output only, the executed process will not + become the controlling process of the terminal, and will not + fail or wait for other processes to release the + terminal.</para> + + <para><option>journal</option> connects standard output with + the journal which is accessible via + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + Note that everything that is written to syslog or kmsg (see + below) is implicitly stored in the journal as well, the + specific two options listed below are hence supersets of this + one.</para> + + <para><option>syslog</option> connects standard output to the + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + system syslog service, in addition to the journal. Note that + the journal daemon is usually configured to forward everything + it receives to syslog anyway, in which case this option is no + different from <option>journal</option>.</para> + + <para><option>kmsg</option> connects standard output with the + kernel log buffer which is accessible via + <citerefentry project='man-pages'><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + in addition to the journal. The journal daemon might be + configured to send all logs to kmsg anyway, in which case this + option is no different from <option>journal</option>.</para> + + <para><option>journal+console</option>, + <option>syslog+console</option> and + <option>kmsg+console</option> work in a similar way as the + three options above but copy the output to the system console + as well.</para> + + <para><option>socket</option> connects standard output to a + socket acquired via socket activation. The semantics are + similar to the same option of + <varname>StandardInput=</varname>.</para> + + <para>The <option>fd</option> option connects + the output stream to a single file descriptor provided by a socket unit. + A custom named file descriptor can be specified as part of this option, + after a <literal>:</literal> (e.g. <literal>fd:<replaceable>foobar</replaceable></literal>). + If no name is specified, <literal>stdout</literal> is assumed + (i.e. <literal>fd</literal> is equivalent to <literal>fd:stdout</literal>). + At least one socket unit defining such name must be explicitly provided via the + <varname>Sockets=</varname> option, and file descriptor name may differ + from the name of its containing socket unit. + If multiple matches are found, the first one will be used. + See <varname>FileDescriptorName=</varname> in + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more details about named descriptors and ordering.</para> + + <para>If the standard output (or error output, see below) of a unit is connected to the journal, syslog or the + kernel log buffer, the unit will implicitly gain a dependency of type <varname>After=</varname> on + <filename>systemd-journald.socket</filename> (also see the automatic dependencies section above).</para> + + <para>This setting defaults to the value set with + <option>DefaultStandardOutput=</option> in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which defaults to <option>journal</option>. Note that setting + this parameter might result in additional dependencies to be + added to the unit (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>StandardError=</varname></term> + <listitem><para>Controls where file descriptor 2 (STDERR) of + the executed processes is connected to. The available options + are identical to those of <varname>StandardOutput=</varname>, + with some exceptions: if set to <option>inherit</option> the + file descriptor used for standard output is duplicated for + standard error, while <option>fd</option> operates on the error + stream and will look by default for a descriptor named + <literal>stderr</literal>.</para> + + <para>This setting defaults to the value set with + <option>DefaultStandardError=</option> in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which defaults to <option>inherit</option>. Note that setting + this parameter might result in additional dependencies to be + added to the unit (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TTYPath=</varname></term> + <listitem><para>Sets the terminal device node to use if + standard input, output, or error are connected to a TTY (see + above). Defaults to + <filename>/dev/console</filename>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>TTYReset=</varname></term> + <listitem><para>Reset the terminal device specified with + <varname>TTYPath=</varname> before and after execution. + Defaults to <literal>no</literal>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>TTYVHangup=</varname></term> + <listitem><para>Disconnect all clients which have opened the + terminal device specified with <varname>TTYPath=</varname> + before and after execution. Defaults to + <literal>no</literal>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>TTYVTDisallocate=</varname></term> + <listitem><para>If the terminal device specified with + <varname>TTYPath=</varname> is a virtual console terminal, try + to deallocate the TTY before and after execution. This ensures + that the screen and scrollback buffer is cleared. Defaults to + <literal>no</literal>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SyslogIdentifier=</varname></term> + <listitem><para>Sets the process name to prefix log lines sent + to the logging system or the kernel log buffer with. If not + set, defaults to the process name of the executed process. + This option is only useful when + <varname>StandardOutput=</varname> or + <varname>StandardError=</varname> are set to + <option>syslog</option>, <option>journal</option> or + <option>kmsg</option> (or to the same settings in combination + with <option>+console</option>).</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SyslogFacility=</varname></term> + <listitem><para>Sets the syslog facility to use when logging + to syslog. One of <option>kern</option>, + <option>user</option>, <option>mail</option>, + <option>daemon</option>, <option>auth</option>, + <option>syslog</option>, <option>lpr</option>, + <option>news</option>, <option>uucp</option>, + <option>cron</option>, <option>authpriv</option>, + <option>ftp</option>, <option>local0</option>, + <option>local1</option>, <option>local2</option>, + <option>local3</option>, <option>local4</option>, + <option>local5</option>, <option>local6</option> or + <option>local7</option>. See + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details. This option is only useful when + <varname>StandardOutput=</varname> or + <varname>StandardError=</varname> are set to + <option>syslog</option>. Defaults to + <option>daemon</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SyslogLevel=</varname></term> + <listitem><para>The default syslog level to use when logging to + syslog or the kernel log buffer. One of + <option>emerg</option>, + <option>alert</option>, + <option>crit</option>, + <option>err</option>, + <option>warning</option>, + <option>notice</option>, + <option>info</option>, + <option>debug</option>. See + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details. This option is only useful when + <varname>StandardOutput=</varname> or + <varname>StandardError=</varname> are set to + <option>syslog</option> or <option>kmsg</option>. Note that + individual lines output by the daemon might be prefixed with a + different log level which can be used to override the default + log level specified here. The interpretation of these prefixes + may be disabled with <varname>SyslogLevelPrefix=</varname>, + see below. For details, see + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + + Defaults to + <option>info</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SyslogLevelPrefix=</varname></term> + <listitem><para>Takes a boolean argument. If true and + <varname>StandardOutput=</varname> or + <varname>StandardError=</varname> are set to + <option>syslog</option>, <option>kmsg</option> or + <option>journal</option>, log lines written by the executed + process that are prefixed with a log level will be passed on + to syslog with this log level set but the prefix removed. If + set to false, the interpretation of these prefixes is disabled + and the logged lines are passed on as-is. For details about + this prefixing see + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Defaults to true.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimerSlackNSec=</varname></term> + <listitem><para>Sets the timer slack in nanoseconds for the + executed processes. The timer slack controls the accuracy of + wake-ups triggered by timers. See + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more information. Note that in contrast to most other time + span definitions this parameter takes an integer value in + nano-seconds if no unit is specified. The usual time units are + understood too.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LimitCPU=</varname></term> + <term><varname>LimitFSIZE=</varname></term> + <term><varname>LimitDATA=</varname></term> + <term><varname>LimitSTACK=</varname></term> + <term><varname>LimitCORE=</varname></term> + <term><varname>LimitRSS=</varname></term> + <term><varname>LimitNOFILE=</varname></term> + <term><varname>LimitAS=</varname></term> + <term><varname>LimitNPROC=</varname></term> + <term><varname>LimitMEMLOCK=</varname></term> + <term><varname>LimitLOCKS=</varname></term> + <term><varname>LimitSIGPENDING=</varname></term> + <term><varname>LimitMSGQUEUE=</varname></term> + <term><varname>LimitNICE=</varname></term> + <term><varname>LimitRTPRIO=</varname></term> + <term><varname>LimitRTTIME=</varname></term> + <listitem><para>Set soft and hard limits on various resources for executed processes. See + <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details on + the resource limit concept. Resource limits may be specified in two formats: either as single value to set a + specific soft and hard limit to the same value, or as colon-separated pair <option>soft:hard</option> to set + both limits individually (e.g. <literal>LimitAS=4G:16G</literal>). Use the string <varname>infinity</varname> + to configure no limit on a specific resource. The multiplicative suffixes K, M, G, T, P and E (to the base + 1024) may be used for resource limits measured in bytes (e.g. LimitAS=16G). For the limits referring to time + values, the usual time units ms, s, min, h and so on may be used (see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for + details). Note that if no time unit is specified for <varname>LimitCPU=</varname> the default unit of seconds + is implied, while for <varname>LimitRTTIME=</varname> the default unit of microseconds is implied. Also, note + that the effective granularity of the limits might influence their enforcement. For example, time limits + specified for <varname>LimitCPU=</varname> will be rounded up implicitly to multiples of 1s. For + <varname>LimitNICE=</varname> the value may be specified in two syntaxes: if prefixed with <literal>+</literal> + or <literal>-</literal>, the value is understood as regular Linux nice value in the range -20..19. If not + prefixed like this the value is understood as raw resource limit parameter in the range 0..40 (with 0 being + equivalent to 1).</para> + + <para>Note that most process resource limits configured with + these options are per-process, and processes may fork in order + to acquire a new set of resources that are accounted + independently of the original process, and may thus escape + limits set. Also note that <varname>LimitRSS=</varname> is not + implemented on Linux, and setting it has no effect. Often it + is advisable to prefer the resource controls listed in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + over these per-process limits, as they apply to services as a + whole, may be altered dynamically at runtime, and are + generally more expressive. For example, + <varname>MemoryLimit=</varname> is a more powerful (and + working) replacement for <varname>LimitRSS=</varname>.</para> + + <para>For system units these resource limits may be chosen freely. For user units however (i.e. units run by a + per-user instance of + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>), these limits are + bound by (possibly more restrictive) per-user limits enforced by the OS.</para> + + <para>Resource limits not configured explicitly for a unit default to the value configured in the various + <varname>DefaultLimitCPU=</varname>, <varname>DefaultLimitFSIZE=</varname>, … options available in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, and – + if not configured there – the kernel or per-user defaults, as defined by the OS (the latter only for user + services, see above).</para> + + <table> + <title>Resource limit directives, their equivalent <command>ulimit</command> shell commands and the unit used</title> + + <tgroup cols='3'> + <colspec colname='directive' /> + <colspec colname='equivalent' /> + <colspec colname='unit' /> + <thead> + <row> + <entry>Directive</entry> + <entry><command>ulimit</command> equivalent</entry> + <entry>Unit</entry> + </row> + </thead> + <tbody> + <row> + <entry>LimitCPU=</entry> + <entry>ulimit -t</entry> + <entry>Seconds</entry> + </row> + <row> + <entry>LimitFSIZE=</entry> + <entry>ulimit -f</entry> + <entry>Bytes</entry> + </row> + <row> + <entry>LimitDATA=</entry> + <entry>ulimit -d</entry> + <entry>Bytes</entry> + </row> + <row> + <entry>LimitSTACK=</entry> + <entry>ulimit -s</entry> + <entry>Bytes</entry> + </row> + <row> + <entry>LimitCORE=</entry> + <entry>ulimit -c</entry> + <entry>Bytes</entry> + </row> + <row> + <entry>LimitRSS=</entry> + <entry>ulimit -m</entry> + <entry>Bytes</entry> + </row> + <row> + <entry>LimitNOFILE=</entry> + <entry>ulimit -n</entry> + <entry>Number of File Descriptors</entry> + </row> + <row> + <entry>LimitAS=</entry> + <entry>ulimit -v</entry> + <entry>Bytes</entry> + </row> + <row> + <entry>LimitNPROC=</entry> + <entry>ulimit -u</entry> + <entry>Number of Processes</entry> + </row> + <row> + <entry>LimitMEMLOCK=</entry> + <entry>ulimit -l</entry> + <entry>Bytes</entry> + </row> + <row> + <entry>LimitLOCKS=</entry> + <entry>ulimit -x</entry> + <entry>Number of Locks</entry> + </row> + <row> + <entry>LimitSIGPENDING=</entry> + <entry>ulimit -i</entry> + <entry>Number of Queued Signals</entry> + </row> + <row> + <entry>LimitMSGQUEUE=</entry> + <entry>ulimit -q</entry> + <entry>Bytes</entry> + </row> + <row> + <entry>LimitNICE=</entry> + <entry>ulimit -e</entry> + <entry>Nice Level</entry> + </row> + <row> + <entry>LimitRTPRIO=</entry> + <entry>ulimit -r</entry> + <entry>Realtime Priority</entry> + </row> + <row> + <entry>LimitRTTIME=</entry> + <entry>No equivalent</entry> + <entry>Microseconds</entry> + </row> + </tbody> + </tgroup> + </table></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PAMName=</varname></term> + <listitem><para>Sets the PAM service name to set up a session + as. If set, the executed process will be registered as a PAM + session under the specified service name. This is only useful + in conjunction with the <varname>User=</varname> setting. If + not set, no PAM session will be opened for the executed + processes. See + <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CapabilityBoundingSet=</varname></term> + + <listitem><para>Controls which capabilities to include in the capability bounding set for the executed + process. See <citerefentry + project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> for + details. Takes a whitespace-separated list of capability names, e.g. <constant>CAP_SYS_ADMIN</constant>, + <constant>CAP_DAC_OVERRIDE</constant>, <constant>CAP_SYS_PTRACE</constant>. Capabilities listed will be + included in the bounding set, all others are removed. If the list of capabilities is prefixed with + <literal>~</literal>, all but the listed capabilities will be included, the effect of the assignment + inverted. Note that this option also affects the respective capabilities in the effective, permitted and + inheritable capability sets. If this option is not used, the capability bounding set is not modified on process + execution, hence no limits on the capabilities of the process are enforced. This option may appear more than + once, in which case the bounding sets are merged. If the empty string is assigned to this option, the bounding + set is reset to the empty capability set, and all prior settings have no effect. If set to + <literal>~</literal> (without any further argument), the bounding set is reset to the full set of available + capabilities, also undoing any previous settings. This does not affect commands prefixed with + <literal>+</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>AmbientCapabilities=</varname></term> + + <listitem><para>Controls which capabilities to include in the ambient capability set for the executed + process. Takes a whitespace-separated list of capability names, e.g. <constant>CAP_SYS_ADMIN</constant>, + <constant>CAP_DAC_OVERRIDE</constant>, <constant>CAP_SYS_PTRACE</constant>. This option may appear more than + once in which case the ambient capability sets are merged. If the list of capabilities is prefixed with + <literal>~</literal>, all but the listed capabilities will be included, the effect of the assignment + inverted. If the empty string is assigned to this option, the ambient capability set is reset to the empty + capability set, and all prior settings have no effect. If set to <literal>~</literal> (without any further + argument), the ambient capability set is reset to the full set of available capabilities, also undoing any + previous settings. Note that adding capabilities to ambient capability set adds them to the process's inherited + capability set. </para><para> Ambient capability sets are useful if you want to execute a process as a + non-privileged user but still want to give it some capabilities. Note that in this case option + <constant>keep-caps</constant> is automatically added to <varname>SecureBits=</varname> to retain the + capabilities over the user change. <varname>AmbientCapabilities=</varname> does not affect commands prefixed + with <literal>+</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SecureBits=</varname></term> + <listitem><para>Controls the secure bits set for the executed + process. Takes a space-separated combination of options from + the following list: + <option>keep-caps</option>, + <option>keep-caps-locked</option>, + <option>no-setuid-fixup</option>, + <option>no-setuid-fixup-locked</option>, + <option>noroot</option>, and + <option>noroot-locked</option>. + This option may appear more than once, in which case the secure + bits are ORed. If the empty string is assigned to this option, + the bits are reset to 0. This does not affect commands prefixed with <literal>+</literal>. + See <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ReadWritePaths=</varname></term> + <term><varname>ReadOnlyPaths=</varname></term> + <term><varname>InaccessiblePaths=</varname></term> + + <listitem><para>Sets up a new file system namespace for executed processes. These options may be used to limit + access a process might have to the file system hierarchy. Each setting takes a space-separated list of paths + relative to the host's root directory (i.e. the system running the service manager). Note that if paths + contain symlinks, they are resolved relative to the root directory set with + <varname>RootDirectory=</varname>.</para> + + <para>Paths listed in <varname>ReadWritePaths=</varname> are accessible from within the namespace with the same + access modes as from outside of it. Paths listed in <varname>ReadOnlyPaths=</varname> are accessible for + reading only, writing will be refused even if the usual file access controls would permit this. Nest + <varname>ReadWritePaths=</varname> inside of <varname>ReadOnlyPaths=</varname> in order to provide writable + subdirectories within read-only directories. Use <varname>ReadWritePaths=</varname> in order to whitelist + specific paths for write access if <varname>ProtectSystem=strict</varname> is used. Paths listed in + <varname>InaccessiblePaths=</varname> will be made inaccessible for processes inside the namespace (along with + everything below them in the file system hierarchy).</para> + + <para>Note that restricting access with these options does not extend to submounts of a directory that are + created later on. Non-directory paths may be specified as well. These options may be specified more than once, + in which case all paths listed will have limited access from within the namespace. If the empty string is + assigned to this option, the specific list is reset, and all prior assignments have no effect.</para> + + <para>Paths in <varname>ReadWritePaths=</varname>, <varname>ReadOnlyPaths=</varname> and + <varname>InaccessiblePaths=</varname> may be prefixed with <literal>-</literal>, in which case they will be ignored + when they do not exist. Note that using this setting will disconnect propagation of mounts from the service to + the host (propagation in the opposite direction continues to work). This means that this setting may not be used + for services which shall be able to install mount points in the main mount namespace. Note that the effect of + these settings may be undone by privileged processes. In order to set up an effective sandboxed environment for + a unit it is thus recommended to combine these settings with either + <varname>CapabilityBoundingSet=~CAP_SYS_ADMIN</varname> or <varname>SystemCallFilter=~@mount</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PrivateTmp=</varname></term> + + <listitem><para>Takes a boolean argument. If true, sets up a new file system namespace for the executed + processes and mounts private <filename>/tmp</filename> and <filename>/var/tmp</filename> directories inside it + that is not shared by processes outside of the namespace. This is useful to secure access to temporary files of + the process, but makes sharing between processes via <filename>/tmp</filename> or <filename>/var/tmp</filename> + impossible. If this is enabled, all temporary files created by a service in these directories will be removed + after the service is stopped. Defaults to false. It is possible to run two or more units within the same + private <filename>/tmp</filename> and <filename>/var/tmp</filename> namespace by using the + <varname>JoinsNamespaceOf=</varname> directive, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details. This setting is implied if <varname>DynamicUser=</varname> is set. For this setting the same + restrictions regarding mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and + related calls, see above.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><varname>PrivateDevices=</varname></term> + + <listitem><para>Takes a boolean argument. If true, sets up a new /dev namespace for the executed processes and + only adds API pseudo devices such as <filename>/dev/null</filename>, <filename>/dev/zero</filename> or + <filename>/dev/random</filename> (as well as the pseudo TTY subsystem) to it, but no physical devices such as + <filename>/dev/sda</filename>, system memory <filename>/dev/mem</filename>, system ports + <filename>/dev/port</filename> and others. This is useful to securely turn off physical device access by the + executed process. Defaults to false. Enabling this option will install a system call filter to block low-level + I/O system calls that are grouped in the <varname>@raw-io</varname> set, will also remove + <constant>CAP_MKNOD</constant> and <constant>CAP_SYS_RAWIO</constant> from the capability bounding set for + the unit (see above), and set <varname>DevicePolicy=closed</varname> (see + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). Note that using this setting will disconnect propagation of mounts from the service to the host + (propagation in the opposite direction continues to work). This means that this setting may not be used for + services which shall be able to install mount points in the main mount namespace. The /dev namespace will be + mounted read-only and 'noexec'. The latter may break old programs which try to set up executable memory by + using <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> of + <filename>/dev/zero</filename> instead of using <constant>MAP_ANON</constant>. This setting is implied if + <varname>DynamicUser=</varname> is set. For this setting the same restrictions regarding mount propagation and + privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PrivateNetwork=</varname></term> + + <listitem><para>Takes a boolean argument. If true, sets up a + new network namespace for the executed processes and + configures only the loopback network device + <literal>lo</literal> inside it. No other network devices will + be available to the executed process. This is useful to + securely turn off network access by the executed process. + Defaults to false. It is possible to run two or more units + within the same private network namespace by using the + <varname>JoinsNamespaceOf=</varname> directive, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. Note that this option will disconnect all socket + families from the host, this includes AF_NETLINK and AF_UNIX. + The latter has the effect that AF_UNIX sockets in the abstract + socket namespace will become unavailable to the processes + (however, those located in the file system will continue to be + accessible).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PrivateUsers=</varname></term> + + <listitem><para>Takes a boolean argument. If true, sets up a new user namespace for the executed processes and + configures a minimal user and group mapping, that maps the <literal>root</literal> user and group as well as + the unit's own user and group to themselves and everything else to the <literal>nobody</literal> user and + group. This is useful to securely detach the user and group databases used by the unit from the rest of the + system, and thus to create an effective sandbox environment. All files, directories, processes, IPC objects and + other resources owned by users/groups not equaling <literal>root</literal> or the unit's own will stay visible + from within the unit but appear owned by the <literal>nobody</literal> user and group. If this mode is enabled, + all unit processes are run without privileges in the host user namespace (regardless if the unit's own + user/group is <literal>root</literal> or not). Specifically this means that the process will have zero process + capabilities on the host's user namespace, but full capabilities within the service's user namespace. Settings + such as <varname>CapabilityBoundingSet=</varname> will affect only the latter, and there's no way to acquire + additional capabilities in the host's user namespace. Defaults to off.</para> + + <para>This setting is particularly useful in conjunction with <varname>RootDirectory=</varname>, as the need to + synchronize the user and group databases in the root directory and on the host is reduced, as the only users + and groups who need to be matched are <literal>root</literal>, <literal>nobody</literal> and the unit's own + user and group.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProtectSystem=</varname></term> + + <listitem><para>Takes a boolean argument or the special values <literal>full</literal> or + <literal>strict</literal>. If true, mounts the <filename>/usr</filename> and <filename>/boot</filename> + directories read-only for processes invoked by this unit. If set to <literal>full</literal>, the + <filename>/etc</filename> directory is mounted read-only, too. If set to <literal>strict</literal> the entire + file system hierarchy is mounted read-only, except for the API file system subtrees <filename>/dev</filename>, + <filename>/proc</filename> and <filename>/sys</filename> (protect these directories using + <varname>PrivateDevices=</varname>, <varname>ProtectKernelTunables=</varname>, + <varname>ProtectControlGroups=</varname>). This setting ensures that any modification of the vendor-supplied + operating system (and optionally its configuration, and local mounts) is prohibited for the service. It is + recommended to enable this setting for all long-running services, unless they are involved with system updates + or need to modify the operating system in other ways. If this option is used, + <varname>ReadWritePaths=</varname> may be used to exclude specific directories from being made read-only. This + setting is implied if <varname>DynamicUser=</varname> is set. For this setting the same restrictions regarding + mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see + above. Defaults to off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProtectHome=</varname></term> + + <listitem><para>Takes a boolean argument or <literal>read-only</literal>. If true, the directories + <filename>/home</filename>, <filename>/root</filename> and <filename>/run/user</filename> are made inaccessible + and empty for processes invoked by this unit. If set to <literal>read-only</literal>, the three directories are + made read-only instead. It is recommended to enable this setting for all long-running services (in particular + network-facing ones), to ensure they cannot get access to private user data, unless the services actually + require access to the user's private data. This setting is implied if <varname>DynamicUser=</varname> is + set. For this setting the same restrictions regarding mount propagation and privileges apply as for + <varname>ReadOnlyPaths=</varname> and related calls, see above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProtectKernelTunables=</varname></term> + + <listitem><para>Takes a boolean argument. If true, kernel variables accessible through + <filename>/proc/sys</filename>, <filename>/sys</filename>, <filename>/proc/sysrq-trigger</filename>, + <filename>/proc/latency_stats</filename>, <filename>/proc/acpi</filename>, + <filename>/proc/timer_stats</filename>, <filename>/proc/fs</filename> and <filename>/proc/irq</filename> will + be made read-only to all processes of the unit. Usually, tunable kernel variables should only be written at + boot-time, with the <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + mechanism. Almost no services need to write to these at runtime; it is hence recommended to turn this on for + most services. For this setting the same restrictions regarding mount propagation and privileges apply as for + <varname>ReadOnlyPaths=</varname> and related calls, see above. Defaults to off. + Note that this option does not prevent kernel tuning through IPC interfaces and external programs. However + <varname>InaccessiblePaths=</varname> can be used to make some IPC file system objects + inaccessible.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProtectControlGroups=</varname></term> + + <listitem><para>Takes a boolean argument. If true, the Linux Control Groups (<citerefentry + project='man-pages'><refentrytitle>cgroups</refentrytitle><manvolnum>7</manvolnum></citerefentry>) hierarchies + accessible through <filename>/sys/fs/cgroup</filename> will be made read-only to all processes of the + unit. Except for container managers no services should require write access to the control groups hierarchies; + it is hence recommended to turn this on for most services. For this setting the same restrictions regarding + mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see + above. Defaults to off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MountFlags=</varname></term> + + <listitem><para>Takes a mount propagation flag: <option>shared</option>, <option>slave</option> or + <option>private</option>, which control whether mounts in the file system namespace set up for this unit's + processes will receive or propagate mounts or unmounts. See <citerefentry + project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry> for + details. Defaults to <option>shared</option>. Use <option>shared</option> to ensure that mounts and unmounts + are propagated from the host to the container and vice versa. Use <option>slave</option> to run processes so + that none of their mounts and unmounts will propagate to the host. Use <option>private</option> to also ensure + that no mounts and unmounts from the host will propagate into the unit processes' namespace. Note that + <option>slave</option> means that file systems mounted on the host might stay mounted continuously in the + unit's namespace, and thus keep the device busy. Note that the file system namespace related options + (<varname>PrivateTmp=</varname>, <varname>PrivateDevices=</varname>, <varname>ProtectSystem=</varname>, + <varname>ProtectHome=</varname>, <varname>ProtectKernelTunables=</varname>, + <varname>ProtectControlGroups=</varname>, <varname>ReadOnlyPaths=</varname>, + <varname>InaccessiblePaths=</varname>, <varname>ReadWritePaths=</varname>) require that mount and unmount + propagation from the unit's file system namespace is disabled, and hence downgrade <option>shared</option> to + <option>slave</option>. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>UtmpIdentifier=</varname></term> + + <listitem><para>Takes a four character identifier string for + an <citerefentry + project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and wtmp entry for this service. This should only be + set for services such as <command>getty</command> + implementations (such as <citerefentry + project='die-net'><refentrytitle>agetty</refentrytitle><manvolnum>8</manvolnum></citerefentry>) + where utmp/wtmp entries must be created and cleared before and + after execution, or for services that shall be executed as if + they were run by a <command>getty</command> process (see + below). If the configured string is longer than four + characters, it is truncated and the terminal four characters + are used. This setting interprets %I style string + replacements. This setting is unset by default, i.e. no + utmp/wtmp entries are created or cleaned up for this + service.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>UtmpMode=</varname></term> + + <listitem><para>Takes one of <literal>init</literal>, + <literal>login</literal> or <literal>user</literal>. If + <varname>UtmpIdentifier=</varname> is set, controls which + type of <citerefentry + project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry>/wtmp + entries for this service are generated. This setting has no + effect unless <varname>UtmpIdentifier=</varname> is set + too. If <literal>init</literal> is set, only an + <constant>INIT_PROCESS</constant> entry is generated and the + invoked process must implement a + <command>getty</command>-compatible utmp/wtmp logic. If + <literal>login</literal> is set, first an + <constant>INIT_PROCESS</constant> entry, followed by a + <constant>LOGIN_PROCESS</constant> entry is generated. In + this case, the invoked process must implement a <citerefentry + project='die-net'><refentrytitle>login</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible + utmp/wtmp logic. If <literal>user</literal> is set, first an + <constant>INIT_PROCESS</constant> entry, then a + <constant>LOGIN_PROCESS</constant> entry and finally a + <constant>USER_PROCESS</constant> entry is generated. In this + case, the invoked process may be any process that is suitable + to be run as session leader. Defaults to + <literal>init</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SELinuxContext=</varname></term> + + <listitem><para>Set the SELinux security context of the + executed process. If set, this will override the automated + domain transition. However, the policy still needs to + authorize the transition. This directive is ignored if SELinux + is disabled. If prefixed by <literal>-</literal>, all errors + will be ignored. This does not affect commands prefixed with <literal>+</literal>. + See <citerefentry project='die-net'><refentrytitle>setexeccon</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>AppArmorProfile=</varname></term> + + <listitem><para>Takes a profile name as argument. The process + executed by the unit will switch to this profile when started. + Profiles must already be loaded in the kernel, or the unit + will fail. This result in a non operation if AppArmor is not + enabled. If prefixed by <literal>-</literal>, all errors will + be ignored. This does not affect commands prefixed with <literal>+</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SmackProcessLabel=</varname></term> + + <listitem><para>Takes a <option>SMACK64</option> security + label as argument. The process executed by the unit will be + started under this label and SMACK will decide whether the + process is allowed to run or not, based on it. The process + will continue to run under the label specified here unless the + executable has its own <option>SMACK64EXEC</option> label, in + which case the process will transition to run under that + label. When not specified, the label that systemd is running + under is used. This directive is ignored if SMACK is + disabled.</para> + + <para>The value may be prefixed by <literal>-</literal>, in + which case all errors will be ignored. An empty value may be + specified to unset previous assignments. This does not affect + commands prefixed with <literal>+</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IgnoreSIGPIPE=</varname></term> + + <listitem><para>Takes a boolean argument. If true, causes + <constant>SIGPIPE</constant> to be ignored in the executed + process. Defaults to true because <constant>SIGPIPE</constant> + generally is useful only in shell pipelines.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>NoNewPrivileges=</varname></term> + + <listitem><para>Takes a boolean argument. If true, ensures that the service + process and all its children can never gain new privileges. This option is more + powerful than the respective secure bits flags (see above), as it also prohibits + UID changes of any kind. This is the simplest and most effective way to ensure that + a process and its children can never elevate privileges again. Defaults to false, + but in the user manager instance certain settings force + <varname>NoNewPrivileges=yes</varname>, ignoring the value of this setting. + Those is the case when <varname>SystemCallFilter=</varname>, + <varname>SystemCallArchitectures=</varname>, + <varname>RestrictAddressFamilies=</varname>, + <varname>PrivateDevices=</varname>, + <varname>ProtectKernelTunables=</varname>, + <varname>ProtectKernelModules=</varname>, + <varname>MemoryDenyWriteExecute=</varname>, or + <varname>RestrictRealtime=</varname> are specified. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SystemCallFilter=</varname></term> + + <listitem><para>Takes a space-separated list of system call names. If this setting is used, all system calls + executed by the unit processes except for the listed ones will result in immediate process termination with the + <constant>SIGSYS</constant> signal (whitelisting). If the first character of the list is <literal>~</literal>, + the effect is inverted: only the listed system calls will result in immediate process termination + (blacklisting). If running in user mode, or in system mode, but without the <constant>CAP_SYS_ADMIN</constant> + capability (e.g. setting <varname>User=nobody</varname>), <varname>NoNewPrivileges=yes</varname> is + implied. This feature makes use of the Secure Computing Mode 2 interfaces of the kernel ('seccomp filtering') + and is useful for enforcing a minimal sandboxing environment. Note that the <function>execve</function>, + <function>exit</function>, <function>exit_group</function>, <function>getrlimit</function>, + <function>rt_sigreturn</function>, <function>sigreturn</function> system calls and the system calls for + querying time and sleeping are implicitly whitelisted and do not need to be listed explicitly. This option may + be specified more than once, in which case the filter masks are merged. If the empty string is assigned, the + filter is reset, all prior assignments will have no effect. This does not affect commands prefixed with + <literal>+</literal>.</para> + + <para>Note that strict system call filters may impact execution and error handling code paths of the service + invocation. Specifically, access to the <function>execve</function> system call is required for the execution + of the service binary — if it is blocked service invocation will necessarily fail. Also, if execution of the + service binary fails for some reason (for example: missing service executable), the error handling logic might + require access to an additional set of system calls in order to process and log this failure correctly. It + might be necessary to temporarily disable system call filters in order to simplify debugging of such + failures.</para> + + <para>If you specify both types of this option (i.e. + whitelisting and blacklisting), the first encountered will + take precedence and will dictate the default action + (termination or approval of a system call). Then the next + occurrences of this option will add or delete the listed + system calls from the set of the filtered system calls, + depending of its type and the default action. (For example, if + you have started with a whitelisting of + <function>read</function> and <function>write</function>, and + right after it add a blacklisting of + <function>write</function>, then <function>write</function> + will be removed from the set.)</para> + + <para>As the number of possible system + calls is large, predefined sets of system calls are provided. + A set starts with <literal>@</literal> character, followed by + name of the set. + + <table> + <title>Currently predefined system call sets</title> + + <tgroup cols='2'> + <colspec colname='set' /> + <colspec colname='description' /> + <thead> + <row> + <entry>Set</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>@basic-io</entry> + <entry>System calls for basic I/O: reading, writing, seeking, file descriptor duplication and closing (<citerefentry project='man-pages'><refentrytitle>read</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>write</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry> + </row> + <row> + <entry>@clock</entry> + <entry>System calls for changing the system clock (<citerefentry project='man-pages'><refentrytitle>adjtimex</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>settimeofday</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry> + </row> + <row> + <entry>@cpu-emulation</entry> + <entry>System calls for CPU emulation functionality (<citerefentry project='man-pages'><refentrytitle>vm86</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> + </row> + <row> + <entry>@debug</entry> + <entry>Debugging, performance monitoring and tracing functionality (<citerefentry project='man-pages'><refentrytitle>ptrace</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>perf_event_open</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> + </row> + <row> + <entry>@io-event</entry> + <entry>Event loop system calls (<citerefentry project='man-pages'><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>select</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>eventfd</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> + </row> + <row> + <entry>@ipc</entry> + <entry>Pipes, SysV IPC, POSIX Message Queues and other IPC (<citerefentry project='man-pages'><refentrytitle>mq_overview</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>svipc</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + </row> + <row> + <entry>@keyring</entry> + <entry>Kernel keyring access (<citerefentry project='man-pages'><refentrytitle>keyctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> + </row> + <row> + <entry>@module</entry> + <entry>Kernel module control (<citerefentry project='man-pages'><refentrytitle>init_module</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>delete_module</refentrytitle><manvolnum>2</manvolnum></citerefentry> and related calls)</entry> + </row> + <row> + <entry>@mount</entry> + <entry>File system mounting and unmounting (<citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>, and related calls)</entry> + </row> + <row> + <entry>@network-io</entry> + <entry>Socket I/O (including local AF_UNIX): <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry></entry> + </row> + <row> + <entry>@obsolete</entry> + <entry>Unusual, obsolete or unimplemented (<citerefentry project='man-pages'><refentrytitle>create_module</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>gtty</refentrytitle><manvolnum>2</manvolnum></citerefentry>, …)</entry> + </row> + <row> + <entry>@privileged</entry> + <entry>All system calls which need super-user capabilities (<citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + </row> + <row> + <entry>@process</entry> + <entry>Process control, execution, namespaces (<citerefentry project='man-pages'><refentrytitle>clone</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>namespaces</refentrytitle><manvolnum>7</manvolnum></citerefentry>, …</entry> + </row> + <row> + <entry>@raw-io</entry> + <entry>Raw I/O port access (<citerefentry project='man-pages'><refentrytitle>ioperm</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>iopl</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <function>pciconfig_read()</function>, …)</entry> + </row> + <row> + <entry>@resources</entry> + <entry>System calls for changing resource limits, memory and scheduling parameters (<citerefentry project='man-pages'><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>setpriority</refentrytitle><manvolnum>2</manvolnum></citerefentry>, …)</entry> + </row> + </tbody> + </tgroup> + </table> + + Note that as new system calls are added to the kernel, additional system calls might be added to the groups + above, so the contents of the sets may change between systemd versions.</para> + + <para>It is recommended to combine the file system namespacing related options with + <varname>SystemCallFilter=~@mount</varname>, in order to prohibit the unit's processes to undo the + mappings. Specifically these are the options <varname>PrivateTmp=</varname>, + <varname>PrivateDevices=</varname>, <varname>ProtectSystem=</varname>, <varname>ProtectHome=</varname>, + <varname>ProtectKernelTunables=</varname>, <varname>ProtectControlGroups=</varname>, + <varname>ReadOnlyPaths=</varname>, <varname>InaccessiblePaths=</varname> and + <varname>ReadWritePaths=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SystemCallErrorNumber=</varname></term> + + <listitem><para>Takes an <literal>errno</literal> error number + name to return when the system call filter configured with + <varname>SystemCallFilter=</varname> is triggered, instead of + terminating the process immediately. Takes an error name such + as <constant>EPERM</constant>, <constant>EACCES</constant> or + <constant>EUCLEAN</constant>. When this setting is not used, + or when the empty string is assigned, the process will be + terminated immediately when the filter is + triggered.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SystemCallArchitectures=</varname></term> + + <listitem><para>Takes a space-separated list of architecture identifiers to + include in the system call filter. The known architecture identifiers are the same + as for <varname>ConditionArchitecture=</varname> described in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + as well as <constant>x32</constant>, <constant>mips64-n32</constant>, + <constant>mips64-le-n32</constant>, and the special identifier + <constant>native</constant>. Only system calls of the specified architectures will + be permitted to processes of this unit. This is an effective way to disable + compatibility with non-native architectures for processes, for example to prohibit + execution of 32-bit x86 binaries on 64-bit x86-64 systems. The special + <constant>native</constant> identifier implicitly maps to the native architecture + of the system (or more strictly: to the architecture the system manager is + compiled for). If running in user mode, or in system mode, but without the + <constant>CAP_SYS_ADMIN</constant> capability (e.g. setting + <varname>User=nobody</varname>), <varname>NoNewPrivileges=yes</varname> is + implied. Note that setting this option to a non-empty list implies that + <constant>native</constant> is included too. By default, this option is set to the + empty list, i.e. no architecture system call filtering is applied. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RestrictAddressFamilies=</varname></term> + + <listitem><para>Restricts the set of socket address families + accessible to the processes of this unit. Takes a + space-separated list of address family names to whitelist, + such as + <constant>AF_UNIX</constant>, + <constant>AF_INET</constant> or + <constant>AF_INET6</constant>. When + prefixed with <constant>~</constant> the listed address + families will be applied as blacklist, otherwise as whitelist. + Note that this restricts access to the + <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system call only. Sockets passed into the process by other + means (for example, by using socket activation with socket + units, see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>) + are unaffected. Also, sockets created with + <function>socketpair()</function> (which creates connected + AF_UNIX sockets only) are unaffected. Note that this option + has no effect on 32-bit x86 and is ignored (but works + correctly on x86-64). If running in user mode, or in system + mode, but without the <constant>CAP_SYS_ADMIN</constant> + capability (e.g. setting <varname>User=nobody</varname>), + <varname>NoNewPrivileges=yes</varname> is implied. By + default, no restriction applies, all address families are + accessible to processes. If assigned the empty string, any + previous list changes are undone.</para> + + <para>Use this option to limit exposure of processes to remote + systems, in particular via exotic network protocols. Note that + in most cases, the local <constant>AF_UNIX</constant> address + family should be included in the configured whitelist as it is + frequently used for local communication, including for + <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>2</manvolnum></citerefentry> + logging. This does not affect commands prefixed with <literal>+</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProtectKernelModules=</varname></term> + + <listitem><para>Takes a boolean argument. If true, explicit module loading will + be denied. This allows to turn off module load and unload operations on modular + kernels. It is recommended to turn this on for most services that do not need special + file systems or extra kernel modules to work. Default to off. Enabling this option + removes <constant>CAP_SYS_MODULE</constant> from the capability bounding set for + the unit, and installs a system call filter to block module system calls, + also <filename>/usr/lib/modules</filename> is made inaccessible. For this + setting the same restrictions regarding mount propagation and privileges + apply as for <varname>ReadOnlyPaths=</varname> and related calls, see above. + Note that limited automatic module loading due to user configuration or kernel + mapping tables might still happen as side effect of requested user operations, + both privileged and unprivileged. To disable module auto-load feature please see + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + <constant>kernel.modules_disabled</constant> mechanism and + <filename>/proc/sys/kernel/modules_disabled</filename> documentation.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Personality=</varname></term> + + <listitem><para>Controls which kernel architecture <citerefentry + project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> shall report, + when invoked by unit processes. Takes one of the architecture identifiers <constant>x86</constant>, + <constant>x86-64</constant>, <constant>ppc</constant>, <constant>ppc-le</constant>, <constant>ppc64</constant>, + <constant>ppc64-le</constant>, <constant>s390</constant> or <constant>s390x</constant>. Which personality + architectures are supported depends on the system architecture. Usually the 64bit versions of the various + system architectures support their immediate 32bit personality architecture counterpart, but no others. For + example, <constant>x86-64</constant> systems support the <constant>x86-64</constant> and + <constant>x86</constant> personalities but no others. The personality feature is useful when running 32-bit + services on a 64-bit host system. If not specified, the personality is left unmodified and thus reflects the + personality of the host system's kernel.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RuntimeDirectory=</varname></term> + <term><varname>RuntimeDirectoryMode=</varname></term> + + <listitem><para>Takes a list of directory names. If set, one + or more directories by the specified names will be created + below <filename>/run</filename> (for system services) or below + <varname>$XDG_RUNTIME_DIR</varname> (for user services) when + the unit is started, and removed when the unit is stopped. The + directories will have the access mode specified in + <varname>RuntimeDirectoryMode=</varname>, and will be owned by + the user and group specified in <varname>User=</varname> and + <varname>Group=</varname>. Use this to manage one or more + runtime directories of the unit and bind their lifetime to the + daemon runtime. The specified directory names must be + relative, and may not include a <literal>/</literal>, i.e. + must refer to simple directories to create or remove. This is + particularly useful for unprivileged daemons that cannot + create runtime directories in <filename>/run</filename> due to + lack of privileges, and to make sure the runtime directory is + cleaned up automatically after use. For runtime directories + that require more complex or different configuration or + lifetime guarantees, please consider using + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MemoryDenyWriteExecute=</varname></term> + + <listitem><para>Takes a boolean argument. If set, attempts to create memory mappings that are writable and + executable at the same time, or to change existing memory mappings to become executable, or mapping shared memory + segments as executable are prohibited. + Specifically, a system call filter is added that rejects + <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system calls with both <constant>PROT_EXEC</constant> and <constant>PROT_WRITE</constant> set, + <citerefentry><refentrytitle>mprotect</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system calls with <constant>PROT_EXEC</constant> set and + <citerefentry><refentrytitle>shmat</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system calls with <constant>SHM_EXEC</constant> set. Note that this option is incompatible with programs + that generate program code dynamically at runtime, such as JIT execution engines, or programs compiled making + use of the code "trampoline" feature of various C compilers. This option improves service security, as it makes + harder for software exploits to change running code dynamically. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RestrictRealtime=</varname></term> + + <listitem><para>Takes a boolean argument. If set, any attempts to enable realtime scheduling in a process of + the unit are refused. This restricts access to realtime task scheduling policies such as + <constant>SCHED_FIFO</constant>, <constant>SCHED_RR</constant> or <constant>SCHED_DEADLINE</constant>. See + <citerefentry project='man-pages'><refentrytitle>sched</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details about + these scheduling policies. Realtime scheduling policies may be used to monopolize CPU time for longer periods + of time, and may hence be used to lock up or otherwise trigger Denial-of-Service situations on the system. It + is hence recommended to restrict access to realtime scheduling to the few programs that actually require + them. Defaults to off.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Environment variables in spawned processes</title> + + <para>Processes started by the system are executed in a clean + environment in which select variables listed below are set. System + processes started by systemd do not inherit variables from PID 1, + but processes started by user systemd instances inherit all + environment variables from the user systemd instance. + </para> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$PATH</varname></term> + + <listitem><para>Colon-separated list of directories to use + when launching executables. Systemd uses a fixed value of + <filename>/usr/local/sbin</filename>:<filename>/usr/local/bin</filename>:<filename>/usr/sbin</filename>:<filename>/usr/bin</filename>:<filename>/sbin</filename>:<filename>/bin</filename>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$LANG</varname></term> + + <listitem><para>Locale. Can be set in + <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + or on the kernel command line (see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$USER</varname></term> + <term><varname>$LOGNAME</varname></term> + <term><varname>$HOME</varname></term> + <term><varname>$SHELL</varname></term> + + <listitem><para>User name (twice), home directory, and the + login shell. The variables are set for the units that have + <varname>User=</varname> set, which includes user + <command>systemd</command> instances. See + <citerefentry project='die-net'><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$INVOCATION_ID</varname></term> + + <listitem><para>Contains a randomized, unique 128bit ID identifying each runtime cycle of the unit, formatted + as 32 character hexadecimal string. A new ID is assigned each time the unit changes from an inactive state into + an activating or active state, and may be used to identify this specific runtime cycle, in particular in data + stored offline, such as the journal. The same ID is passed to all processes run as part of the + unit.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$XDG_RUNTIME_DIR</varname></term> + + <listitem><para>The directory for volatile state. Set for the + user <command>systemd</command> instance, and also in user + sessions. See + <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$XDG_SESSION_ID</varname></term> + <term><varname>$XDG_SEAT</varname></term> + <term><varname>$XDG_VTNR</varname></term> + + <listitem><para>The identifier of the session, the seat name, + and virtual terminal of the session. Set by + <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for login sessions. <varname>$XDG_SEAT</varname> and + <varname>$XDG_VTNR</varname> will only be set when attached to + a seat and a tty.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$MAINPID</varname></term> + + <listitem><para>The PID of the unit's main process if it is + known. This is only set for control processes as invoked by + <varname>ExecReload=</varname> and similar. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$MANAGERPID</varname></term> + + <listitem><para>The PID of the user <command>systemd</command> + instance, set for processes spawned by it. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$LISTEN_FDS</varname></term> + <term><varname>$LISTEN_PID</varname></term> + <term><varname>$LISTEN_FDNAMES</varname></term> + + <listitem><para>Information about file descriptors passed to a + service for socket activation. See + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$NOTIFY_SOCKET</varname></term> + + <listitem><para>The socket + <function>sd_notify()</function> talks to. See + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$WATCHDOG_PID</varname></term> + <term><varname>$WATCHDOG_USEC</varname></term> + + <listitem><para>Information about watchdog keep-alive notifications. See + <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$TERM</varname></term> + + <listitem><para>Terminal type, set only for units connected to + a terminal (<varname>StandardInput=tty</varname>, + <varname>StandardOutput=tty</varname>, or + <varname>StandardError=tty</varname>). See + <citerefentry project='man-pages'><refentrytitle>termcap</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$JOURNAL_STREAM</varname></term> + + <listitem><para>If the standard output or standard error output of the executed processes are connected to the + journal (for example, by setting <varname>StandardError=journal</varname>) <varname>$JOURNAL_STREAM</varname> + contains the device and inode numbers of the connection file descriptor, formatted in decimal, separated by a + colon (<literal>:</literal>). This permits invoked processes to safely detect whether their standard output or + standard error output are connected to the journal. The device and inode numbers of the file descriptors should + be compared with the values set in the environment variable to determine whether the process output is still + connected to the journal. Note that it is generally not sufficient to only check whether + <varname>$JOURNAL_STREAM</varname> is set at all as services might invoke external processes replacing their + standard output or standard error output, without unsetting the environment variable.</para> + + <para>This environment variable is primarily useful to allow services to optionally upgrade their used log + protocol to the native journal protocol (using + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> and other + functions) if their standard output or standard error output is connected to the journal anyway, thus enabling + delivery of structured metadata along with logged messages.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SERVICE_RESULT</varname></term> + + <listitem><para>Only defined for the service unit type, this environment variable is passed to all + <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname> processes, and encodes the service + "result". Currently, the following values are defined: <literal>timeout</literal> (in case of an operation + timeout), <literal>exit-code</literal> (if a service process exited with a non-zero exit code; see + <varname>$EXIT_CODE</varname> below for the actual exit code returned), <literal>signal</literal> (if a + service process was terminated abnormally by a signal; see <varname>$EXIT_CODE</varname> below for the actual + signal used for the termination), <literal>core-dump</literal> (if a service process terminated abnormally and + dumped core), <literal>watchdog</literal> (if the watchdog keep-alive ping was enabled for the service but it + missed the deadline), or <literal>resources</literal> (a catch-all condition in case a system operation + failed).</para> + + <para>This environment variable is useful to monitor failure or successful termination of a service. Even + though this variable is available in both <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname>, it + is usually a better choice to place monitoring tools in the latter, as the former is only invoked for services + that managed to start up correctly, and the latter covers both services that failed during their start-up and + those which failed during their runtime.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$EXIT_CODE</varname></term> + <term><varname>$EXIT_STATUS</varname></term> + + <listitem><para>Only defined for the service unit type, these environment variables are passed to all + <varname>ExecStop=</varname>, <varname>ExecStopPost=</varname> processes and contain exit status/code + information of the main process of the service. For the precise definition of the exit code and status, see + <citerefentry><refentrytitle>wait</refentrytitle><manvolnum>2</manvolnum></citerefentry>. <varname>$EXIT_CODE</varname> + is one of <literal>exited</literal>, <literal>killed</literal>, + <literal>dumped</literal>. <varname>$EXIT_STATUS</varname> contains the numeric exit code formatted as string + if <varname>$EXIT_CODE</varname> is <literal>exited</literal>, and the signal name in all other cases. Note + that these environment variables are only set if the service manager succeeded to start and identify the main + process of the service.</para> + + <table> + <title>Summary of possible service result variable values</title> + <tgroup cols='3'> + <colspec colname='result' /> + <colspec colname='status' /> + <colspec colname='code' /> + <thead> + <row> + <entry><varname>$SERVICE_RESULT</varname></entry> + <entry><varname>$EXIT_STATUS</varname></entry> + <entry><varname>$EXIT_CODE</varname></entry> + </row> + </thead> + + <tbody> + <row> + <entry morerows="1" valign="top"><literal>timeout</literal></entry> + <entry valign="top"><literal>killed</literal></entry> + <entry><literal>TERM</literal>, <literal>KILL</literal></entry> + </row> + + <row> + <entry valign="top"><literal>exited</literal></entry> + <entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal + >3</literal>, …, <literal>255</literal></entry> + </row> + + <row> + <entry valign="top"><literal>exit-code</literal></entry> + <entry valign="top"><literal>exited</literal></entry> + <entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal + >3</literal>, …, <literal>255</literal></entry> + </row> + + <row> + <entry valign="top"><literal>signal</literal></entry> + <entry valign="top"><literal>killed</literal></entry> + <entry><literal>HUP</literal>, <literal>INT</literal>, <literal>KILL</literal>, …</entry> + </row> + + <row> + <entry valign="top"><literal>core-dump</literal></entry> + <entry valign="top"><literal>dumped</literal></entry> + <entry><literal>ABRT</literal>, <literal>SEGV</literal>, <literal>QUIT</literal>, …</entry> + </row> + + <row> + <entry morerows="2" valign="top"><literal>watchdog</literal></entry> + <entry><literal>dumped</literal></entry> + <entry><literal>ABRT</literal></entry> + </row> + <row> + <entry><literal>killed</literal></entry> + <entry><literal>TERM</literal>, <literal>KILL</literal></entry> + </row> + <row> + <entry><literal>exited</literal></entry> + <entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal + >3</literal>, …, <literal>255</literal></entry> + </row> + + <row> + <entry><literal>resources</literal></entry> + <entry>any of the above</entry> + <entry>any of the above</entry> + </row> + + <row> + <entry namest="results" nameend="code">Note: the process may be also terminated by a signal not sent by systemd. In particular the process may send an arbitrary signal to itself in a handler for any of the non-maskable signals. Nevertheless, in the <literal>timeout</literal> and <literal>watchdog</literal> rows above only the signals that systemd sends have been included.</entry> + </row> + </tbody> + </tgroup> + </table> + + </listitem> + </varlistentry> + </variablelist> + + <para>Additional variables may be configured by the following + means: for processes spawned in specific units, use the + <varname>Environment=</varname>, <varname>EnvironmentFile=</varname> + and <varname>PassEnvironment=</varname> options above; to specify + variables globally, use <varname>DefaultEnvironment=</varname> + (see + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>) + or the kernel option <varname>systemd.setenv=</varname> (see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>). + Additional variables may also be set through PAM, + cf. <citerefentry project='man-pages'><refentrytitle>pam_env</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>exec</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + + +</refentry> diff --git a/src/grp-system/systemd/systemd.generator.xml b/src/grp-system/systemd/systemd.generator.xml new file mode 100644 index 0000000000..b268104c9d --- /dev/null +++ b/src/grp-system/systemd/systemd.generator.xml @@ -0,0 +1,348 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2015 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.generator"> + <refentryinfo> + <title>systemd.generator</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.generator</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.generator</refname> + <refpurpose>Systemd unit generators</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>/path/to/generator</command> + <arg choice="plain"><replaceable>normal-dir</replaceable></arg> + <arg choice="plain"><replaceable>early-dir</replaceable></arg> + <arg choice="plain"><replaceable>late-dir</replaceable></arg> + </cmdsynopsis> + + <para> + <literallayout><filename>/run/systemd/system-generators/*</filename> +<filename>/etc/systemd/system-generators/*</filename> +<filename>/usr/local/lib/systemd/system-generators/*</filename> +<filename>&systemgeneratordir;/*</filename></literallayout> + </para> + + <para> + <literallayout><filename>/run/systemd/user-generators/*</filename> +<filename>/etc/systemd/user-generators/*</filename> +<filename>/usr/local/lib/systemd/user-generators/*</filename> +<filename>&usergeneratordir;/*</filename></literallayout> + </para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para>Generators are small binaries that live in + <filename>&usergeneratordir;/</filename> and other directories + listed above. + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + will execute those binaries very early at bootup and at + configuration reload time — before unit files are loaded. + Generators can dynamically generate unit files or create symbolic + links to unit files to add additional dependencies, thus extending + or overriding existing definitions. Their main purpose is to + convert configuration files that are not native unit files + dynamically into native unit files.</para> + + <para>Generators are loaded from a set of paths determined during + compilation, as listed above. System and user generators are loaded + from directories with names ending in + <filename>system-generators/</filename> and + <filename>user-generators/</filename>, respectively. Generators + found in directories listed earlier override the ones with the + same name in directories lower in the list. A symlink to + <filename>/dev/null</filename> or an empty file can be used to + mask a generator, thereby preventing it from running. Please note + that the order of the two directories with the highest priority is + reversed with respect to the unit load path, and generators in + <filename>/run</filename> overwrite those in + <filename>/etc</filename>.</para> + + <para>After installing new generators or updating the + configuration, <command>systemctl daemon-reload</command> may be + executed. This will delete the previous configuration created by + generators, re-run all generators, and cause + <command>systemd</command> to reload units from disk. See + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for more information. + </para> + </refsect1> + + <refsect1> + <title>Writing generators</title> + + <para>Generators are invoked with three arguments: paths to + runtime directories where generators can place their generated + unit files or symlinks.</para> + + <orderedlist> + <listitem> + <para><parameter>normal-dir</parameter></para> + <para>argv[1] may be used to override unit files in + <filename>/usr</filename>, but not those in + <filename>/etc</filename>. This means that unit files placed + in this directory take precedence over vendor unit + configuration but not over native user/administrator unit + configuration.</para> + </listitem> + + <listitem> + <para><parameter>early-dir</parameter></para> + <para>argv[2] may be used to override unit files in + <filename>/usr</filename> and in + <filename>/etc</filename>. This means that unit files placed + in this directory take precedence over all configuration, + both vendor and user/administrator.</para> + </listitem> + + <listitem> + <para><parameter>late-dir</parameter></para> + <para>argv[3] may be used to extend the unit file tree without + overriding any other unit files. Any native configuration + files supplied by the vendor or user/administrator take + precedence over the generated ones placed in this directory. + </para> + </listitem> + </orderedlist> + + <refsect2> + <title>Notes</title> + + <itemizedlist> + <listitem> + <para> + All generators are executed in parallel. That means all + executables are started at the very same time and need to + be able to cope with this parallelism. + </para> + </listitem> + + <listitem> + <para> + Generators are run very early at boot and cannot rely on + any external services. They may not talk to any other + process. That includes simple things such as logging to + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + or <command>systemd</command> itself (this means: no + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>)! + Non-essential file systems like + <filename>/var</filename> and <filename>/home</filename> + are mounted after generators have run. Generators + can however rely on the most basic kernel functionality to be + available, including a mounted <filename>/sys</filename>, + <filename>/proc</filename>, <filename>/dev</filename>, + <filename>/usr</filename>. + </para> + </listitem> + + <listitem> + <para> + Units written by generators are removed when the configuration + is reloaded. That means the lifetime of the generated + units is closely bound to the reload cycles of + <command>systemd</command> itself. + </para> + </listitem> + + <listitem> + <para> + Generators should only be used to generate unit files, not + any other kind of configuration. Due to the lifecycle + logic mentioned above, generators are not a good fit to + generate dynamic configuration for other services. If you + need to generate dynamic configuration for other services, + do so in normal services you order before the service in + question. + </para> + </listitem> + + <listitem> + <para> + Since + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + is not available (see above), log messages have to be + written to <filename>/dev/kmsg</filename> instead. + </para> + </listitem> + + <listitem> + <para> + It is a good idea to use the + <varname>SourcePath=</varname> directive in generated unit + files to specify the source configuration file you are + generating the unit from. This makes things more easily + understood by the user and also has the benefit that + systemd can warn the user about configuration files that + changed on disk but have not been read yet by systemd. + </para> + </listitem> + + <listitem> + <para> + Generators may write out dynamic unit files or just hook + unit files into other units with the usual + <filename>.wants/</filename> or + <filename>.requires/</filename> symlinks. Often, it is + nicer to simply instantiate a template unit file from + <filename>/usr</filename> with a generator instead of + writing out entirely dynamic unit files. Of course, this + works only if a single parameter is to be used. + </para> + </listitem> + + <listitem> + <para> + If you are careful, you can implement generators in shell + scripts. We do recommend C code however, since generators + are executed synchronously and hence delay the + entire boot if they are slow. + </para> + </listitem> + + <listitem> + <para>Regarding overriding semantics: there are two rules we + try to follow when thinking about the overriding semantics: + </para> + + <orderedlist numeration="lowerroman"> + <listitem> + <para>User configuration should override vendor + configuration. This (mostly) means that stuff from + <filename>/etc</filename> should override stuff from + <filename>/usr</filename>.</para> + </listitem> + + <listitem> + <para>Native configuration should override non-native + configuration. This (mostly) means that stuff you + generate should never override native unit files for the + same purpose.</para> + </listitem> + </orderedlist> + + <para>Of these two rules the first rule is probably the more + important one and breaks the second one sometimes. Hence, + when deciding whether to user argv[1], argv[2], or argv[3], + your default choice should probably be argv[1].</para> + </listitem> + + <listitem> + <para> + Instead of heading off now and writing all kind of + generators for legacy configuration file formats, please + think twice! It is often a better idea to just deprecate + old stuff instead of keeping it artificially alive. + </para> + </listitem> + </itemizedlist> + </refsect2> + </refsect1> + + <refsect1> + <title>Examples</title> + <example> + <title>systemd-fstab-generator</title> + + <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + converts <filename>/etc/fstab</filename> into native mount + units. It uses argv[1] as location to place the generated unit + files in order to allow the user to override + <filename>/etc/fstab</filename> with her own native unit files, + but also to ensure that <filename>/etc/fstab</filename> + overrides any vendor default from <filename>/usr</filename>. + </para> + + <para>After editing <filename>/etc/fstab</filename>, the user + should invoke <command>systemctl daemon-reload</command>. This + will re-run all generators and cause <command>systemd</command> + to reload units from disk. To actually mount new directories + added to <filename>fstab</filename>, <command>systemctl start + <replaceable>/path/to/mountpoint</replaceable></command> or + <command>systemctl start local-fs.target</command> may be used. + </para> + </example> + + <example> + <title>systemd-system-update-generator</title> + + <para><citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + temporarily redirects <filename>default.target</filename> to + <filename>system-update.target</filename>, if a system update is + scheduled. Since this needs to override the default user + configuration for <filename>default.target</filename>, it uses + argv[2]. For details about this logic, see + <citerefentry><refentrytitle>systemd.offline-updates</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para> + </example> + + <example> + <title>Debugging a generator</title> + + <programlisting>dir=$(mktemp -d) +SYSTEMD_LOG_LEVEL=debug &systemgeneratordir;/systemd-fstab-generator \ + "$dir" "$dir" "$dir" +find $dir</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-getty-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-sysv-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> +</refentry> diff --git a/src/grp-system/systemd/systemd.journal-fields.xml b/src/grp-system/systemd/systemd.journal-fields.xml new file mode 100644 index 0000000000..494f97aad1 --- /dev/null +++ b/src/grp-system/systemd/systemd.journal-fields.xml @@ -0,0 +1,525 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.journal-fields"> + + <refentryinfo> + <title>systemd.journal-fields</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.journal-fields</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.journal-fields</refname> + <refpurpose>Special journal fields</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>Entries in the journal resemble an environment block in + their syntax but with fields that can include binary data. + Primarily, fields are formatted UTF-8 text strings, and binary + formatting is used only where formatting as UTF-8 text strings + makes little sense. New fields may freely be defined by + applications, but a few fields have special meaning. All fields + with special meanings are optional. In some cases, fields may + appear more than once per entry.</para> + </refsect1> + + <refsect1> + <title>User Journal Fields</title> + + <para>User fields are fields that are directly passed from clients + and stored in the journal.</para> + + <variablelist class='journal-directives'> + <varlistentry> + <term><varname>MESSAGE=</varname></term> + <listitem> + <para>The human-readable message string for this entry. This + is supposed to be the primary text shown to the user. It is + usually not translated (but might be in some cases), and is + not supposed to be parsed for metadata.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MESSAGE_ID=</varname></term> + <listitem> + <para>A 128-bit message identifier ID for recognizing + certain message types, if this is desirable. This should + contain a 128-bit ID formatted as a lower-case hexadecimal + string, without any separating dashes or suchlike. This is + recommended to be a UUID-compatible ID, but this is not + enforced, and formatted differently. Developers can generate + a new ID for this purpose with <command>journalctl + <option>--new-id</option></command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>PRIORITY=</varname></term> + <listitem> + <para>A priority value between 0 (<literal>emerg</literal>) + and 7 (<literal>debug</literal>) formatted as a decimal + string. This field is compatible with syslog's priority + concept.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>CODE_FILE=</varname></term> + <term><varname>CODE_LINE=</varname></term> + <term><varname>CODE_FUNC=</varname></term> + <listitem> + <para>The code location generating this message, if known. + Contains the source filename, the line number and the + function name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ERRNO=</varname></term> + <listitem> + <para>The low-level Unix error number causing this entry, if + any. Contains the numeric value of + <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> + formatted as a decimal string.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>SYSLOG_FACILITY=</varname></term> + <term><varname>SYSLOG_IDENTIFIER=</varname></term> + <term><varname>SYSLOG_PID=</varname></term> + <listitem> + <para>Syslog compatibility fields containing the facility + (formatted as decimal string), the identifier string (i.e. + "tag"), and the client PID. (Note that the tag is usually + derived from glibc's + <varname>program_invocation_short_name</varname> variable, + see + <citerefentry project='die-net'><refentrytitle>program_invocation_short_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>.)</para> + </listitem> + + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Trusted Journal Fields</title> + + <para>Fields prefixed with an underscore are trusted fields, i.e. + fields that are implicitly added by the journal and cannot be + altered by client code.</para> + + <variablelist class='journal-directives'> + <varlistentry> + <term><varname>_PID=</varname></term> + <term><varname>_UID=</varname></term> + <term><varname>_GID=</varname></term> + <listitem> + <para>The process, user, and group ID of the process the + journal entry originates from formatted as a decimal + string.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_COMM=</varname></term> + <term><varname>_EXE=</varname></term> + <term><varname>_CMDLINE=</varname></term> + <listitem> + <para>The name, the executable path, and the command line of + the process the journal entry originates from.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_CAP_EFFECTIVE=</varname></term> + <listitem> + <para>The effective + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + of the process the journal entry originates from.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_AUDIT_SESSION=</varname></term> + <term><varname>_AUDIT_LOGINUID=</varname></term> + <listitem> + <para>The session and login UID of the process the journal + entry originates from, as maintained by the kernel audit + subsystem.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_SYSTEMD_CGROUP=</varname></term> + <term><varname>_SYSTEMD_SESSION=</varname></term> + <term><varname>_SYSTEMD_UNIT=</varname></term> + <term><varname>_SYSTEMD_USER_UNIT=</varname></term> + <term><varname>_SYSTEMD_OWNER_UID=</varname></term> + <term><varname>_SYSTEMD_SLICE=</varname></term> + + <listitem> + <para>The control group path in the systemd hierarchy, the + systemd session ID (if any), the systemd unit name (if any), + the systemd user session unit name (if any), the owner UID + of the systemd session (if any) and the systemd slice unit + of the process the journal entry originates from.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_SELINUX_CONTEXT=</varname></term> + <listitem> + <para>The SELinux security context (label) of the process + the journal entry originates from.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term> + <listitem> + <para>The earliest trusted timestamp of the message, if any + is known that is different from the reception time of the + journal. This is the time in microseconds since the epoch + UTC, formatted as a decimal string.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_BOOT_ID=</varname></term> + <listitem> + <para>The kernel boot ID for the boot the message was + generated in, formatted as a 128-bit hexadecimal + string.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_MACHINE_ID=</varname></term> + <listitem> + <para>The machine ID of the originating host, as available + in + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_HOSTNAME=</varname></term> + <listitem> + <para>The name of the originating host.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_TRANSPORT=</varname></term> + <listitem> + <para>How the entry was received by the journal service. + Valid transports are: + </para> + <variablelist> + <varlistentry> + <term> + <option>audit</option> + </term> + <listitem> + <para>for those read from the kernel audit subsystem + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>driver</option> + </term> + <listitem> + <para>for internally generated messages + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>syslog</option> + </term> + <listitem> + <para>for those received via the local syslog socket + with the syslog protocol + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>journal</option> + </term> + <listitem> + <para>for those received via the native journal + protocol + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>stdout</option> + </term> + <listitem> + <para>for those read from a service's standard output + or error output + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>kernel</option> + </term> + <listitem> + <para>for those read from the kernel + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Kernel Journal Fields</title> + + <para>Kernel fields are fields that are used by messages + originating in the kernel and stored in the journal.</para> + + <variablelist class='journal-directives'> + <varlistentry> + <term><varname>_KERNEL_DEVICE=</varname></term> + <listitem> + <para>The kernel device name. If the entry is associated to + a block device, the major and minor of the device node, + separated by <literal>:</literal> and prefixed by + <literal>b</literal>. Similar for character devices but + prefixed by <literal>c</literal>. For network devices, this + is the interface index prefixed by <literal>n</literal>. For + all other devices, this is the subsystem name prefixed by + <literal>+</literal>, followed by <literal>:</literal>, + followed by the kernel device name.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>_KERNEL_SUBSYSTEM=</varname></term> + <listitem> + <para>The kernel subsystem name.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>_UDEV_SYSNAME=</varname></term> + <listitem> + <para>The kernel device name as it shows up in the device + tree below <filename>/sys</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>_UDEV_DEVNODE=</varname></term> + <listitem> + <para>The device node path of this device in + <filename>/dev</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>_UDEV_DEVLINK=</varname></term> + <listitem> + <para>Additional symlink names pointing to the device node + in <filename>/dev</filename>. This field is frequently set + more than once per entry.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Fields to log on behalf of a different program</title> + + <para>Fields in this section are used by programs to specify that + they are logging on behalf of another program or unit. + </para> + + <para>Fields used by the <command>systemd-coredump</command> + coredump kernel helper: + </para> + + <variablelist class='journal-directives'> + <varlistentry> + <term><varname>COREDUMP_UNIT=</varname></term> + <term><varname>COREDUMP_USER_UNIT=</varname></term> + <listitem> + <para>Used to annotate messages containing coredumps from + system and session units. See + <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para>Privileged programs (currently UID 0) may attach + <varname>OBJECT_PID=</varname> to a message. This will instruct + <command>systemd-journald</command> to attach additional fields on + behalf of the caller:</para> + + <variablelist class='journal-directives'> + <varlistentry> + <term><varname>OBJECT_PID=<replaceable>PID</replaceable></varname></term> + <listitem> + <para>PID of the program that this message pertains to. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>OBJECT_UID=</varname></term> + <term><varname>OBJECT_GID=</varname></term> + <term><varname>OBJECT_COMM=</varname></term> + <term><varname>OBJECT_EXE=</varname></term> + <term><varname>OBJECT_CMDLINE=</varname></term> + <term><varname>OBJECT_AUDIT_SESSION=</varname></term> + <term><varname>OBJECT_AUDIT_LOGINUID=</varname></term> + <term><varname>OBJECT_SYSTEMD_CGROUP=</varname></term> + <term><varname>OBJECT_SYSTEMD_SESSION=</varname></term> + <term><varname>OBJECT_SYSTEMD_OWNER_UID=</varname></term> + <term><varname>OBJECT_SYSTEMD_UNIT=</varname></term> + <term><varname>OBJECT_SYSTEMD_USER_UNIT=</varname></term> + <listitem> + <para>These are additional fields added automatically by + <command>systemd-journald</command>. Their meaning is the + same as + <varname>_UID=</varname>, + <varname>_GID=</varname>, + <varname>_COMM=</varname>, + <varname>_EXE=</varname>, + <varname>_CMDLINE=</varname>, + <varname>_AUDIT_SESSION=</varname>, + <varname>_AUDIT_LOGINUID=</varname>, + <varname>_SYSTEMD_CGROUP=</varname>, + <varname>_SYSTEMD_SESSION=</varname>, + <varname>_SYSTEMD_UNIT=</varname>, + <varname>_SYSTEMD_USER_UNIT=</varname>, and + <varname>_SYSTEMD_OWNER_UID=</varname> + as described above, except that the process identified by + <replaceable>PID</replaceable> is described, instead of the + process which logged the message.</para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Address Fields</title> + + <para>During serialization into external formats, such as the + <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal + Export Format</ulink> or the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal + JSON Format</ulink>, the addresses of journal entries are + serialized into fields prefixed with double underscores. Note that + these are not proper fields when stored in the journal but for + addressing metadata of entries. They cannot be written as part of + structured log entries via calls such as + <citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + They may also not be used as matches for + <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para> + + <variablelist class='journal-directives'> + <varlistentry> + <term><varname>__CURSOR=</varname></term> + <listitem> + <para>The cursor for the entry. A cursor is an opaque text + string that uniquely describes the position of an entry in + the journal and is portable across machines, platforms and + journal files. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>__REALTIME_TIMESTAMP=</varname></term> + <listitem> + <para>The wallclock time + (<constant>CLOCK_REALTIME</constant>) at the point in time + the entry was received by the journal, in microseconds since + the epoch UTC, formatted as a decimal string. This has + different properties from + <literal>_SOURCE_REALTIME_TIMESTAMP=</literal>, as it is + usually a bit later but more likely to be monotonic. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>__MONOTONIC_TIMESTAMP=</varname></term> + <listitem> + <para>The monotonic time + (<constant>CLOCK_MONOTONIC</constant>) at the point in time + the entry was received by the journal in microseconds, + formatted as a decimal string. To be useful as an address + for the entry, this should be combined with the boot ID in + <literal>_BOOT_ID=</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.kill.xml b/src/grp-system/systemd/systemd.kill.xml new file mode 100644 index 0000000000..13b7ab14df --- /dev/null +++ b/src/grp-system/systemd/systemd.kill.xml @@ -0,0 +1,189 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2012 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.kill"> + <refentryinfo> + <title>systemd.kill</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.kill</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.kill</refname> + <refpurpose>Process killing procedure + configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>service</replaceable>.service</filename>, + <filename><replaceable>socket</replaceable>.socket</filename>, + <filename><replaceable>mount</replaceable>.mount</filename>, + <filename><replaceable>swap</replaceable>.swap</filename>, + <filename><replaceable>scope</replaceable>.scope</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Unit configuration files for services, sockets, mount + points, swap devices and scopes share a subset of configuration + options which define the killing procedure of processes belonging + to the unit.</para> + + <para>This man page lists the configuration options shared by + these five unit types. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options shared by all unit configuration files, and + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information on the configuration file options specific to + each unit type.</para> + + <para>The kill procedure configuration options are configured in + the [Service], [Socket], [Mount] or [Swap] section, depending on + the unit type.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>KillMode=</varname></term> + <listitem><para>Specifies how processes of this unit shall be + killed. One of + <option>control-group</option>, + <option>process</option>, + <option>mixed</option>, + <option>none</option>.</para> + + <para>If set to <option>control-group</option>, all remaining + processes in the control group of this unit will be killed on + unit stop (for services: after the stop command is executed, + as configured with <varname>ExecStop=</varname>). If set to + <option>process</option>, only the main process itself is + killed. If set to <option>mixed</option>, the + <constant>SIGTERM</constant> signal (see below) is sent to the + main process while the subsequent <constant>SIGKILL</constant> + signal (see below) is sent to all remaining processes of the + unit's control group. If set to <option>none</option>, no + process is killed. In this case, only the stop command will be + executed on unit stop, but no process be killed otherwise. + Processes remaining alive after stop are left in their control + group and the control group continues to exist after stop + unless it is empty.</para> + + <para>Processes will first be terminated via + <constant>SIGTERM</constant> (unless the signal to send is + changed via <varname>KillSignal=</varname>). Optionally, this + is immediately followed by a <constant>SIGHUP</constant> (if + enabled with <varname>SendSIGHUP=</varname>). If then, after a + delay (configured via the <varname>TimeoutStopSec=</varname> + option), processes still remain, the termination request is + repeated with the <constant>SIGKILL</constant> signal (unless + this is disabled via the <varname>SendSIGKILL=</varname> + option). See + <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more information.</para> + + <para>Defaults to + <option>control-group</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillSignal=</varname></term> + <listitem><para>Specifies which signal to use when killing a + service. This controls the signal that is sent as first step + of shutting down a unit (see above), and is usually followed + by <constant>SIGKILL</constant> (see above and below). For a + list of valid signals, see + <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + Defaults to <constant>SIGTERM</constant>. </para> + + <para>Note that, right after sending the signal specified in + this setting, systemd will always send + <constant>SIGCONT</constant>, to ensure that even suspended + tasks can be terminated cleanly.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>SendSIGHUP=</varname></term> + <listitem><para>Specifies whether to send + <constant>SIGHUP</constant> to remaining processes immediately + after sending the signal configured with + <varname>KillSignal=</varname>. This is useful to indicate to + shells and shell-like programs that their connection has been + severed. Takes a boolean value. Defaults to "no". + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SendSIGKILL=</varname></term> + <listitem><para>Specifies whether to send + <constant>SIGKILL</constant> to remaining processes after a + timeout, if the normal shutdown procedure left processes of + the service around. Takes a boolean value. Defaults to "yes". + </para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.link.xml b/src/grp-system/systemd/systemd.link.xml new file mode 100644 index 0000000000..8edbe758d9 --- /dev/null +++ b/src/grp-system/systemd/systemd.link.xml @@ -0,0 +1,517 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Tom Gundersen + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.link"> + <refentryinfo> + <title>systemd.link</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Tom</firstname> + <surname>Gundersen</surname> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.link</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.link</refname> + <refpurpose>Network device configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>link</replaceable>.link</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Network link configuration is performed by the + <command>net_setup_link</command> udev builtin.</para> + + <para>The link files are read from the files located in the system + network directory <filename>/usr/lib/systemd/network</filename>, + the volatile runtime network directory + <filename>/run/systemd/network</filename>, and the local + administration network directory + <filename>/etc/systemd/network</filename>. Link files must have + the extension <filename>.link</filename>; other extensions are + ignored. All link files are collectively sorted and processed in + lexical order, regardless of the directories in which they live. + However, files with identical filenames replace each other. Files + in <filename>/etc</filename> have the highest priority, files in + <filename>/run</filename> take precedence over files with the same + name in <filename>/usr/lib</filename>. This can be used to + override a system-supplied link file with a local file if needed. + As a special case, an empty file (file size 0) or symlink with the + same name pointing to <filename>/dev/null</filename> disables the + configuration file entirely (it is "masked").</para> + + <para>The link file contains a <literal>[Match]</literal> section, + which determines if a given link file may be applied to a given + device, as well as a <literal>[Link]</literal> section specifying + how the device should be configured. The first (in lexical order) + of the link files that matches a given device is applied. Note + that a default file <filename>99-default.link</filename> is + shipped by the system, any user-supplied + <filename>.link</filename> should hence have a lexically earlier + name to be considered at all.</para> + + <para>See + <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for diagnosing problems with <filename>.link</filename> files.</para> + </refsect1> + + <refsect1> + <title>[Match] Section Options</title> + + <para>A link file is said to match a device if each of the entries + in the <literal>[Match]</literal> section matches, or if the + section is empty. The following keys are accepted:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>The hardware address.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>OriginalName=</varname></term> + <listitem> + <para>A whitespace-separated list of shell-style globs matching + the device name, as exposed by the udev property + "INTERFACE". This cannot be used to match on names that have + already been changed from userspace. Caution is advised when matching on + kernel-assigned names, as they are known to be unstable + between reboots.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Path=</varname></term> + <listitem> + <para>A whitespace-separated list of shell-style globs matching + the persistent path, as exposed by the udev property + <literal>ID_PATH</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Driver=</varname></term> + <listitem> + <para>A whitespace-separated list of shell-style globs matching + the driver currently bound to the device, + as exposed by the udev property <literal>DRIVER</literal> + of its parent device, or if that is not set, the + driver as exposed by <literal>ethtool -i</literal> + of the device itself.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Type=</varname></term> + <listitem> + <para>A whitespace-separated list of shell-style globs matching + the device type, as exposed by the udev + property <literal>DEVTYPE</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Host=</varname></term> + <listitem> + <para>Matches against the hostname or machine + ID of the host. See <literal>ConditionHost=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Virtualization=</varname></term> + <listitem> + <para>Checks whether the system is executed in + a virtualized environment and optionally test + whether it is a specific implementation. See + <literal>ConditionVirtualization=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>KernelCommandLine=</varname></term> + <listitem> + <para>Checks whether a specific kernel command line option + is set (or if prefixed with the exclamation mark unset). See + <literal>ConditionKernelCommandLine=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Architecture=</varname></term> + <listitem> + <para>Checks whether the system is running on a specific + architecture. See <literal>ConditionArchitecture=</literal> + in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>[Link] Section Options</title> + + <para>The <literal>[Link]</literal> section accepts the following + keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Description=</varname></term> + <listitem> + <para>A description of the device.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Alias=</varname></term> + <listitem> + <para>The <literal>ifalias</literal> is set to this + value.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MACAddressPolicy=</varname></term> + <listitem> + <para>The policy by which the MAC address should be set. The + available policies are: + </para> + + <variablelist> + <varlistentry> + <term><literal>persistent</literal></term> + <listitem> + <para>If the hardware has a persistent MAC address, as + most hardware should, and if it is used by the kernel, + nothing is done. Otherwise, a new MAC address is + generated which is guaranteed to be the same on every + boot for the given machine and the given device, but + which is otherwise random. This feature depends on ID_NET_NAME_* + properties to exist for the link. On hardware where these + properties are not set, the generation of a persistent MAC address + will fail.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>random</literal></term> + <listitem> + <para>If the kernel is using a random MAC address, + nothing is done. Otherwise, a new address is randomly + generated each time the device appears, typically at + boot. Either way, the random address will have the + <literal>unicast</literal> and + <literal>locally administered</literal> bits set.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>none</literal></term> + <listitem> + <para>Keeps the MAC address assigned by the kernel.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>The MAC address to use, if no + <literal>MACAddressPolicy=</literal> + is specified.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>NamePolicy=</varname></term> + <listitem> + <para>An ordered, space-separated list of policies by which + the interface name should be set. + <literal>NamePolicy</literal> may be disabled by specifying + <literal>net.ifnames=0</literal> on the kernel command line. + Each of the policies may fail, and the first successful one + is used. The name is not set directly, but is exported to + udev as the property <literal>ID_NET_NAME</literal>, which + is, by default, used by a udev rule to set + <literal>NAME</literal>. If the name has already been set by + userspace, no renaming is performed. The available policies + are:</para> + + <variablelist> + <varlistentry> + <term><literal>kernel</literal></term> + <listitem> + <para>If the kernel claims that the name it has set + for a device is predictable, then no renaming is + performed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>database</literal></term> + <listitem> + <para>The name is set based on entries in the udev's + Hardware Database with the key + <literal>ID_NET_NAME_FROM_DATABASE</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>onboard</literal></term> + <listitem> + <para>The name is set based on information given by + the firmware for on-board devices, as exported by the + udev property <literal>ID_NET_NAME_ONBOARD</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>slot</literal></term> + <listitem> + <para>The name is set based on information given by + the firmware for hot-plug devices, as exported by the + udev property <literal>ID_NET_NAME_SLOT</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>path</literal></term> + <listitem> + <para>The name is set based on the device's physical + location, as exported by the udev property + <literal>ID_NET_NAME_PATH</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>mac</literal></term> + <listitem> + <para>The name is set based on the device's persistent + MAC address, as exported by the udev property + <literal>ID_NET_NAME_MAC</literal>.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Name=</varname></term> + <listitem> + <para>The interface name to use in case all the + policies specified in + <varname>NamePolicy=</varname> fail, or in case + <varname>NamePolicy=</varname> is missing or + disabled.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MTUBytes=</varname></term> + <listitem> + <para>The maximum transmission unit in bytes to set for the + device. The usual suffixes K, M, G, are supported and are + understood to the base of 1024.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>BitsPerSecond=</varname></term> + <listitem> + <para>The speed to set for the device, the value is rounded + down to the nearest Mbps. The usual suffixes K, M, G, are + supported and are understood to the base of 1000.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Duplex=</varname></term> + <listitem> + <para>The duplex mode to set for the device. The accepted + values are <literal>half</literal> and + <literal>full</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>WakeOnLan=</varname></term> + <listitem> + <para>The Wake-on-LAN policy to set for the device. The + supported values are:</para> + + <variablelist> + <varlistentry> + <term><literal>phy</literal></term> + <listitem> + <para>Wake on PHY activity.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>magic</literal></term> + <listitem> + <para>Wake on receipt of a magic packet. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>off</literal></term> + <listitem> + <para>Never wake.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>TCPSegmentationOffload=</varname></term> + <listitem> + <para>The TCP Segmentation Offload (TSO) when true enables + TCP segmentation offload. Takes a boolean value. + Defaults to "unset".</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>GenericSegmentationOffload=</varname></term> + <listitem> + <para>The Generic Segmentation Offload (GSO) when true enables + generic segmentation offload. Takes a boolean value. + Defaults to "unset".</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UDPSegmentationOffload=</varname></term> + <listitem> + <para>The UDP Segmentation Offload (USO) when true enables + UDP segmentation offload. Takes a boolean value. + Defaults to "unset".</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>GenericReceiveOffload=</varname></term> + <listitem> + <para>The Generic Receive Offload (GRO) when true enables + generic receive offload. Takes a boolean value. + Defaults to "unset".</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>LargeReceiveOffload=</varname></term> + <listitem> + <para>The Large Receive Offload (LRO) when true enables + large receive offload. Takes a boolean value. + Defaults to "unset".</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>/usr/lib/systemd/network/99-default.link</title> + + <para>The link file <filename>99-default.link</filename> that is + shipped with systemd defines the default naming policy for + links.</para> + + <programlisting>[Link] +NamePolicy=kernel database onboard slot path +MACAddressPolicy=persistent</programlisting> + </example> + + <example> + <title>/etc/systemd/network/10-dmz.link</title> + + <para>This example assigns the fixed name + <literal>dmz0</literal> to the interface with the MAC address + 00:a0:de:63:7a:e6:</para> + + <programlisting>[Match] +MACAddress=00:a0:de:63:7a:e6 + +[Link] +Name=dmz0</programlisting> + </example> + + <example> + <title>/etc/systemd/network/10-internet.link</title> + + <para>This example assigns the fixed name + <literal>internet0</literal> to the interface with the device + path <literal>pci-0000:00:1a.0-*</literal>:</para> + + <programlisting>[Match] +Path=pci-0000:00:1a.0-* + +[Link] +Name=internet0</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-wireless.link</title> + + <para>Here's an overly complex example that shows the use of a large number of [Match] and [Link] settings.</para> + + <programlisting>[Match] +MACAddress=12:34:56:78:9a:bc +Driver=brcmsmac +Path=pci-0000:02:00.0-* +Type=wlan +Virtualization=no +Host=my-laptop +Architecture=x86-64 + +[Link] +Name=wireless0 +MTUBytes=1450 +BitsPerSecond=10M +WakeOnLan=magic +MACAddress=cb:a9:87:65:43:21</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry> + <refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum> + </citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.mount.xml b/src/grp-system/systemd/systemd.mount.xml new file mode 100644 index 0000000000..b0f156f6df --- /dev/null +++ b/src/grp-system/systemd/systemd.mount.xml @@ -0,0 +1,430 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.mount"> + <refentryinfo> + <title>systemd.mount</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.mount</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.mount</refname> + <refpurpose>Mount unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>mount</replaceable>.mount</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.mount</literal> encodes information about a file system + mount point controlled and supervised by systemd.</para> + + <para>This man page lists the configuration options specific to + this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic [Unit] and + [Install] sections. The mount specific configuration options are + configured in the [Mount] section.</para> + + <para>Additional options are listed in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the execution environment the + <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + binary is executed in, and in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the way the processes are terminated, and in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which configure resource control settings for the processes of the + service. Note that the User= and Group= options are not + particularly useful for mount units specifying a + <literal>Type=</literal> option or using configuration not + specified in <filename>/etc/fstab</filename>; + <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + will refuse options that are not listed in + <filename>/etc/fstab</filename> if it is not run as UID 0.</para> + + <para>Mount units must be named after the mount point directories they control. Example: the mount point <filename + noindex='true'>/home/lennart</filename> must be configured in a unit file <filename>home-lennart.mount</filename>. + For details about the escaping logic used to convert a file system path to a unit name, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that mount + units cannot be templated, nor is possible to add multiple names to a mount unit by creating additional symlinks to + it.</para> + + <para>Optionally, a mount unit may be accompanied by an automount + unit, to allow on-demand or parallelized mounting. See + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>Mount points created at runtime (independently of unit files + or <filename>/etc/fstab</filename>) will be monitored by systemd + and appear like any other mount unit in systemd. See + <filename>/proc/self/mountinfo</filename> description in + <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para>Some file systems have special semantics as API file systems + for kernel-to-userspace and userspace-to-userspace interfaces. Some + of them may not be changed via mount units, and cannot be + disabled. For a longer discussion see <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API + File Systems</ulink>.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>If a mount unit is beneath another mount unit in the file + system hierarchy, both a requirement dependency and an ordering + dependency between both units are created automatically.</para> + + <para>Block device backed file systems automatically gain + <varname>BindsTo=</varname> and <varname>After=</varname> type + dependencies on the device unit encapsulating the block + device (see below).</para> + + <para>If traditional file system quota is enabled for a mount + unit, automatic <varname>Wants=</varname> and + <varname>Before=</varname> dependencies on + <filename>systemd-quotacheck.service</filename> and + <filename>quotaon.service</filename> are added.</para> + + <para>For mount units with <varname>DefaultDependencies=yes</varname> in the <literal>[Unit]</literal> section (the + default) a couple additional dependencies are added. Mount units referring to local file systems automatically gain + an <varname>After=</varname> dependency on <filename>local-fs-pre.target</filename>. Network mount units + automatically acquire <varname>After=</varname> dependencies on <filename>remote-fs-pre.target</filename>, + <filename>network.target</filename> and <filename>network-online.target</filename>. Towards the latter a + <varname>Wants=</varname> unit is added as well. Mount units referring to local and network file systems are + distinguished by their file system type specification. In some cases this is not sufficient (for example network + block device based mounts, such as iSCSI), in which case <option>_netdev</option> may be added to the mount option + string of the unit, which forces systemd to consider the mount unit a network mount. Mount units (regardless if + local or network) also acquire automatic <varname>Before=</varname> and <varname>Conflicts=</varname> on + <filename>umount.target</filename> in order to be stopped during shutdown.</para> + + <para>Additional implicit dependencies may be added as result of + execution and resource control parameters as documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title><filename>fstab</filename></title> + + <para>Mount units may either be configured via unit files, or via + <filename>/etc/fstab</filename> (see + <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). Mounts listed in <filename>/etc/fstab</filename> + will be converted into native units dynamically at boot and when + the configuration of the system manager is reloaded. In general, + configuring mount points through <filename>/etc/fstab</filename> + is the preferred approach. See + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details about the conversion.</para> + + <para>The NFS mount option <option>bg</option> for NFS background mounts + as documented in <citerefentry project='man-pages'><refentrytitle>nfs</refentrytitle><manvolnum>5</manvolnum></citerefentry> + is not supported in <filename>/etc/fstab</filename> entries. The systemd mount option <option>nofail</option> + provides similar functionality and should be used instead.</para> + + <para>When reading <filename>/etc/fstab</filename> a few special + mount options are understood by systemd which influence how + dependencies are created for mount points. systemd will create a + dependency of type <varname>Wants=</varname> or + <option>Requires</option> (see option <option>nofail</option> + below), from either <filename>local-fs.target</filename> or + <filename>remote-fs.target</filename>, depending whether the file + system is local or remote.</para> + + <variablelist class='fstab-options'> + + <varlistentry> + <term><option>x-systemd.requires=</option></term> + + <listitem><para>Configures a <varname>Requires=</varname> and + an <varname>After=</varname> dependency between the created + mount unit and another systemd unit, such as a device or mount + unit. The argument should be a unit name, or an absolute path + to a device node or mount point. This option may be specified + more than once. This option is particularly useful for mount + point declarations that need an additional device to be around + (such as an external journal device for journal file systems) + or an additional mount to be in place (such as an overlay file + system that merges multiple mount points). See + <varname>After=</varname> and <varname>Requires=</varname> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>x-systemd.requires-mounts-for=</option></term> + + <listitem><para>Configures a + <varname>RequiresMountsFor=</varname> dependency between the + created mount unit and other mount units. The argument must be + an absolute path. This option may be specified more than once. + See <varname>RequiresMountsFor=</varname> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>x-systemd.automount</option></term> + + <listitem><para>An automount unit will be created for the file + system. See + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>x-systemd.idle-timeout=</option></term> + + <listitem><para>Configures the idle timeout of the + automount unit. See <varname>TimeoutIdleSec=</varname> in + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>x-systemd.device-timeout=</option></term> + + <listitem><para>Configure how long systemd should wait for a + device to show up before giving up on an entry from + <filename>/etc/fstab</filename>. Specify a time in seconds or + explicitly append a unit such as <literal>s</literal>, + <literal>min</literal>, <literal>h</literal>, + <literal>ms</literal>.</para> + + <para>Note that this option can only be used in + <filename>/etc/fstab</filename>, and will be + ignored when part of the <varname>Options=</varname> + setting in a unit file.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>noauto</option></term> + <term><option>auto</option></term> + + <listitem><para>With <option>noauto</option>, this mount will + not be added as a dependency for + <filename>local-fs.target</filename> or + <filename>remote-fs.target</filename>. This means that it will + not be mounted automatically during boot, unless it is pulled + in by some other unit. The <option>auto</option> option has the + opposite meaning and is the default.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>nofail</option></term> + + <listitem><para>With <option>nofail</option>, this mount will + be only wanted, not required, by + <filename>local-fs.target</filename> or + <filename>remote-fs.target</filename>. This means that the + boot will continue even if this mount point is not mounted + successfully.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>x-initrd.mount</option></term> + + <listitem><para>An additional filesystem to be mounted in the + initramfs. See <filename>initrd-fs.target</filename> + description in + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + </variablelist> + + <para>If a mount point is configured in both + <filename>/etc/fstab</filename> and a unit file that is stored + below <filename>/usr</filename>, the former will take precedence. + If the unit file is stored below <filename>/etc</filename>, it + will take precedence. This means: native unit files take + precedence over traditional configuration files, but this is + superseded by the rule that configuration in + <filename>/etc</filename> will always take precedence over + configuration in <filename>/usr</filename>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Mount files must include a [Mount] section, which carries + information about the file system mount points it supervises. A + number of options that may be used in this section are shared with + other unit types. These options are documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + The options specific to the [Mount] section of mount units are the + following:</para> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>What=</varname></term> + <listitem><para>Takes an absolute path of a device node, file + or other resource to mount. See + <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details. If this refers to a device node, a dependency on + the respective device unit is automatically created. (See + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information.) This option is + mandatory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Where=</varname></term> + <listitem><para>Takes an absolute path of a directory of the + mount point. If the mount point does not exist at the time of + mounting, it is created. This string must be reflected in the + unit filename. (See above.) This option is + mandatory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Type=</varname></term> + <listitem><para>Takes a string for the file system type. See + <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details. This setting is optional.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Options=</varname></term> + + <listitem><para>Mount options to use when mounting. This takes + a comma-separated list of options. This setting is + optional.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SloppyOptions=</varname></term> + + <listitem><para>Takes a boolean argument. If true, parsing of + the options specified in <varname>Options=</varname> is + relaxed, and unknown mount options are tolerated. This + corresponds with + <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s + <parameter>-s</parameter> switch. Defaults to + off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LazyUnmount=</varname></term> + + <listitem><para>Takes a boolean argument. If true, detach the + filesystem from the filesystem hierarchy at time of the unmount + operation, and clean up all references to the filesystem as + soon as they are not busy anymore. + This corresponds with + <citerefentry project='man-pages'><refentrytitle>umount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s + <parameter>-l</parameter> switch. Defaults to + off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ForceUnmount=</varname></term> + + <listitem><para>Takes a boolean argument. If true, force an + unmount (in case of an unreachable NFS system). + This corresponds with + <citerefentry project='man-pages'><refentrytitle>umount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s + <parameter>-f</parameter> switch. Defaults to + off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DirectoryMode=</varname></term> + <listitem><para>Directories of mount points (and any parent + directories) are automatically created if needed. This option + specifies the file system access mode used when creating these + directories. Takes an access mode in octal notation. Defaults + to 0755.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutSec=</varname></term> + <listitem><para>Configures the time to wait for the mount + command to finish. If a command does not exit within the + configured time, the mount will be considered failed and be + shut down again. All commands still running will be terminated + forcibly via <constant>SIGTERM</constant>, and after another + delay of this time with <constant>SIGKILL</constant>. (See + <option>KillMode=</option> in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.) + Takes a unit-less value in seconds, or a time span value such + as "5min 20s". Pass 0 to disable the timeout logic. The + default value is set from the manager configuration file's + <varname>DefaultTimeoutStartSec=</varname> + variable.</para></listitem> + </varlistentry> + </variablelist> + + <para>Check + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more settings.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.netdev.xml b/src/grp-system/systemd/systemd.netdev.xml new file mode 100644 index 0000000000..ffb66e735b --- /dev/null +++ b/src/grp-system/systemd/systemd.netdev.xml @@ -0,0 +1,1213 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2013 Tom Gundersen + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.netdev" conditional='ENABLE_NETWORKD'> + + <refentryinfo> + <title>systemd.network</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Tom</firstname> + <surname>Gundersen</surname> + <email>teg@jklm.no</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.netdev</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.netdev</refname> + <refpurpose>Virtual Network Device configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>netdev</replaceable>.netdev</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Network setup is performed by + <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para> + + <para>The main Virtual Network Device file must have the extension <filename>.netdev</filename>; + other extensions are ignored. Virtual network devices are created as soon as networkd is + started. If a netdev with the specified name already exists, networkd will use that as-is rather + than create its own. Note that the settings of the pre-existing netdev will not be changed by + networkd.</para> + + <para>The <filename>.netdev</filename> files are read from the files located in the system + network directory <filename>/usr/lib/systemd/network</filename>, the volatile runtime network + directory <filename>/run/systemd/network</filename> and the local administration network + directory <filename>/etc/systemd/network</filename>. All configuration files are collectively + sorted and processed in lexical order, regardless of the directories in which they live. + However, files with identical filenames replace each other. Files in <filename>/etc</filename> + have the highest priority, files in <filename>/run</filename> take precedence over files with + the same name in <filename>/usr/lib</filename>. This can be used to override a system-supplied + configuration file with a local file if needed. As a special case, an empty file (file size 0) + or symlink with the same name pointing to <filename>/dev/null</filename> disables the + configuration file entirely (it is "masked").</para> + + <para>Along with the netdev file <filename>foo.netdev</filename>, a "drop-in" directory + <filename>foo.netdev.d/</filename> may exist. All files with the suffix <literal>.conf</literal> + from this directory will be parsed after the file itself is parsed. This is useful to alter or + add configuration settings, without having to modify the main configuration file. Each drop-in + file must have appropriate section headers.</para> + + <para>In addition to <filename>/etc/systemd/network</filename>, drop-in <literal>.d</literal> + directories can be placed in <filename>/usr/lib/systemd/network</filename> or + <filename>/run/systemd/network</filename> directories. Drop-in files in + <filename>/etc</filename> take precedence over those in <filename>/run</filename> which in turn + take precedence over those in <filename>/usr/lib</filename>. Drop-in files under any of these + directories take precedence over the main netdev file wherever located. (Of course, since + <filename>/run</filename> is temporary and <filename>/usr/lib</filename> is for vendors, it is + unlikely drop-ins should be used in either of those places.)</para> + </refsect1> + + <refsect1> + <title>Supported netdev kinds</title> + + <para>The following kinds of virtual network devices may be + configured in <filename>.netdev</filename> files:</para> + + <table> + <title>Supported kinds of virtual network devices</title> + + <tgroup cols='2'> + <colspec colname='kind' /> + <colspec colname='explanation' /> + <thead><row> + <entry>Kind</entry> + <entry>Description</entry> + </row></thead> + <tbody> + <row><entry><varname>bond</varname></entry> + <entry>A bond device is an aggregation of all its slave devices. See <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt">Linux Ethernet Bonding Driver HOWTO</ulink> for details.Local configuration</entry></row> + + <row><entry><varname>bridge</varname></entry> + <entry>A bridge device is a software switch, and each of its slave devices and the bridge itself are ports of the switch.</entry></row> + + <row><entry><varname>dummy</varname></entry> + <entry>A dummy device drops all packets sent to it.</entry></row> + + <row><entry><varname>gre</varname></entry> + <entry>A Level 3 GRE tunnel over IPv4. See <ulink url="https://tools.ietf.org/html/rfc2784">RFC 2784</ulink> for details.</entry></row> + + <row><entry><varname>gretap</varname></entry> + <entry>A Level 2 GRE tunnel over IPv4.</entry></row> + + <row><entry><varname>ip6gre</varname></entry> + <entry>A Level 3 GRE tunnel over IPv6.</entry></row> + + <row><entry><varname>ip6tnl</varname></entry> + <entry>An IPv4 or IPv6 tunnel over IPv6</entry></row> + + <row><entry><varname>ip6gretap</varname></entry> + <entry>A Level 2 GRE tunnel over IPv6.</entry></row> + + <row><entry><varname>ipip</varname></entry> + <entry>An IPv4 over IPv4 tunnel.</entry></row> + + <row><entry><varname>ipvlan</varname></entry> + <entry>An ipvlan device is a stacked device which receives packets from its underlying device based on IP address filtering.</entry></row> + + <row><entry><varname>macvlan</varname></entry> + <entry>A macvlan device is a stacked device which receives packets from its underlying device based on MAC address filtering.</entry></row> + + <row><entry><varname>macvtap</varname></entry> + <entry>A macvtap device is a stacked device which receives packets from its underlying device based on MAC address filtering.</entry></row> + + <row><entry><varname>sit</varname></entry> + <entry>An IPv6 over IPv4 tunnel.</entry></row> + + <row><entry><varname>tap</varname></entry> + <entry>A persistent Level 2 tunnel between a network device and a device node.</entry></row> + + <row><entry><varname>tun</varname></entry> + <entry>A persistent Level 3 tunnel between a network device and a device node.</entry></row> + + <row><entry><varname>veth</varname></entry> + <entry>An Ethernet tunnel between a pair of network devices.</entry></row> + + <row><entry><varname>vlan</varname></entry> + <entry>A VLAN is a stacked device which receives packets from its underlying device based on VLAN tagging. See <ulink url="http://www.ieee802.org/1/pages/802.1Q.html">IEEE 802.1Q</ulink> for details.</entry></row> + + <row><entry><varname>vti</varname></entry> + <entry>An IPv4 over IPSec tunnel.</entry></row> + + <row><entry><varname>vti6</varname></entry> + <entry>An IPv6 over IPSec tunnel.</entry></row> + + <row><entry><varname>vxlan</varname></entry> + <entry>A virtual extensible LAN (vxlan), for connecting Cloud computing deployments.</entry></row> + + <row><entry><varname>vrf</varname></entry> + <entry>A Virtual Routing and Forwarding (<ulink url="https://www.kernel.org/doc/Documentation/networking/vrf.txt">VRF</ulink>) interface to create separate routing and forwarding domains.</entry></row> + + <row><entry><varname>vcan</varname></entry> + <entry>The virtual CAN driver (vcan). Similar to the network loopback devices, vcan offers a virtual local CAN interface.</entry></row> + + </tbody> + </tgroup> + </table> + + </refsect1> + + <refsect1> + <title>[Match] Section Options</title> + + <para>A virtual network device is only created if the + <literal>[Match]</literal> section matches the current + environment, or if the section is empty. The following keys are + accepted:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Host=</varname></term> + <listitem> + <para>Matches against the hostname or machine ID of the + host. See <literal>ConditionHost=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Virtualization=</varname></term> + <listitem> + <para>Checks whether the system is executed in a virtualized + environment and optionally test whether it is a specific + implementation. See + <literal>ConditionVirtualization=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>KernelCommandLine=</varname></term> + <listitem> + <para>Checks whether a specific kernel command line option + is set (or if prefixed with the exclamation mark unset). See + <literal>ConditionKernelCommandLine=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Architecture=</varname></term> + <listitem> + <para>Checks whether the system is running on a specific + architecture. See <literal>ConditionArchitecture=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>[NetDev] Section Options</title> + + <para>The <literal>[NetDev]</literal> section accepts the + following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Description=</varname></term> + <listitem> + <para>A free-form description of the netdev.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Name=</varname></term> + <listitem> + <para>The interface name used when creating the netdev. + This option is compulsory.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Kind=</varname></term> + <listitem> + <para>The netdev kind. This option is compulsory. See the + <literal>Supported netdev kinds</literal> section for the + valid keys.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MTUBytes=</varname></term> + <listitem> + <para>The maximum transmission unit in bytes to set for + the device. The usual suffixes K, M, G, are supported and + are understood to the base of 1024. This key is not + currently supported for <literal>tun</literal> or + <literal>tap</literal> devices. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>The MAC address to use for the device. If none is + given, one is generated based on the interface name and + the + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + This key is not currently supported for + <literal>tun</literal> or <literal>tap</literal> devices. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[Bridge] Section Options</title> + + <para>The <literal>[Bridge]</literal> section only applies for + netdevs of kind <literal>bridge</literal>, and accepts the + following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>HelloTimeSec=</varname></term> + <listitem> + <para>HelloTimeSec specifies the number of seconds between two hello packets + sent out by the root bridge and the designated bridges. Hello packets are + used to communicate information about the topology throughout the entire + bridged local area network.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MaxAgeSec=</varname></term> + <listitem> + <para>MaxAgeSec specifies the number of seconds of maximum message age. + If the last seen (received) hello packet is more than this number of + seconds old, the bridge in question will start the takeover procedure + in attempt to become the Root Bridge itself.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>ForwardDelaySec=</varname></term> + <listitem> + <para>ForwardDelaySec specifies the number of seconds spent in each + of the Listening and Learning states before the Forwarding state is entered.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>AgeingTimeSec=</varname></term> + <listitem> + <para>This specifies the number of seconds a MAC Address will be kept in + the forwarding database after having a packet received from this MAC Address.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Priority=</varname></term> + <listitem> + <para>The priority of the bridge. An integer between 0 and 65535. A lower value + means higher priority. The bridge having the lowest priority will be elected as root bridge.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DefaultPVID=</varname></term> + <listitem> + <para>This specifies the default port VLAN ID of a newly attached bridge port.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MulticastQuerier=</varname></term> + <listitem> + <para>A boolean. This setting controls the IFLA_BR_MCAST_QUERIER option in the kernel. + If enabled, the kernel will send general ICMP queries from a zero source address. + This feature should allow faster convergence on startup, but it causes some + multicast-aware switches to misbehave and disrupt forwarding of multicast packets. + When unset, the kernel's default setting applies. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MulticastSnooping=</varname></term> + <listitem> + <para>A boolean. This setting controls the IFLA_BR_MCAST_SNOOPING option in the kernel. + If enabled, IGMP snooping monitors the Internet Group Management Protocol (IGMP) traffic + between hosts and multicast routers. When unset, the kernel's default setting applies. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>VLANFiltering=</varname></term> + <listitem> + <para>A boolean. This setting controls the IFLA_BR_VLAN_FILTERING option in the kernel. + If enabled, the bridge will be started in VLAN-filtering mode. When unset, the kernel's + default setting applies. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>STP=</varname></term> + <listitem> + <para>A boolean. This enables the bridge's Spanning Tree Protocol (STP). When unset, + the kernel's default setting applies. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[VLAN] Section Options</title> + + <para>The <literal>[VLAN]</literal> section only applies for + netdevs of kind <literal>vlan</literal>, and accepts the + following key:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Id=</varname></term> + <listitem> + <para>The VLAN ID to use. An integer in the range 0–4094. + This option is compulsory.</para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>[MACVLAN] Section Options</title> + + <para>The <literal>[MACVLAN]</literal> section only applies for + netdevs of kind <literal>macvlan</literal>, and accepts the + following key:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Mode=</varname></term> + <listitem> + <para>The MACVLAN mode to use. The supported options are + <literal>private</literal>, + <literal>vepa</literal>, + <literal>bridge</literal>, and + <literal>passthru</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>[MACVTAP] Section Options</title> + + <para>The <literal>[MACVTAP]</literal> section applies for + netdevs of kind <literal>macvtap</literal> and accepts the + same key as <literal>[MACVLAN]</literal>.</para> + + </refsect1> + + <refsect1> + <title>[IPVLAN] Section Options</title> + + <para>The <literal>[IPVLAN]</literal> section only applies for + netdevs of kind <literal>ipvlan</literal>, and accepts the + following key:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Mode=</varname></term> + <listitem> + <para>The IPVLAN mode to use. The supported options are + <literal>L2</literal> and <literal>L3</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>[VXLAN] Section Options</title> + <para>The <literal>[VXLAN]</literal> section only applies for + netdevs of kind <literal>vxlan</literal>, and accepts the + following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Id=</varname></term> + <listitem> + <para>The VXLAN ID to use.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Group=</varname></term> + <listitem> + <para>An assigned multicast group IP address.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>TOS=</varname></term> + <listitem> + <para>The Type Of Service byte value for a vxlan interface.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>TTL=</varname></term> + <listitem> + <para>A fixed Time To Live N on Virtual eXtensible Local + Area Network packets. N is a number in the range 1–255. 0 + is a special value meaning that packets inherit the TTL + value.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MacLearning=</varname></term> + <listitem> + <para>A boolean. When true, enables dynamic MAC learning + to discover remote MAC addresses.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>FDBAgeingSec=</varname></term> + <listitem> + <para>The lifetime of Forwarding Database entry learnt by + the kernel, in seconds.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MaximumFDBEntries=</varname></term> + <listitem> + <para>Configures maximum number of FDB entries.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>ARPProxy=</varname></term> + <listitem> + <para>A boolean. When true, enables ARP proxying.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>L2MissNotification=</varname></term> + <listitem> + <para>A boolean. When true, enables netlink LLADDR miss + notifications.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>L3MissNotification=</varname></term> + <listitem> + <para>A boolean. When true, enables netlink IP address miss + notifications.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>RouteShortCircuit=</varname></term> + <listitem> + <para>A boolean. When true, route short circuiting is turned + on.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UDPChecksum=</varname></term> + <listitem> + <para>A boolean. When true, transmitting UDP checksums when doing VXLAN/IPv4 is turned on.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UDP6ZeroChecksumTx=</varname></term> + <listitem> + <para>A boolean. When true, sending zero checksums in VXLAN/IPv6 is turned on.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UDP6ZeroChecksumRx=</varname></term> + <listitem> + <para>A boolean. When true, receiving zero checksums in VXLAN/IPv6 is turned on.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>RemoteChecksumTx=</varname></term> + <listitem> + <para>A boolean. When true, remote transmit checksum offload of VXLAN is turned on.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>RemoteChecksumRx=</varname></term> + <listitem> + <para>A boolean. When true, remote receive checksum offload in VXLAN is turned on.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>GroupPolicyExtension=</varname></term> + <listitem> + <para>A boolean. When true, it enables Group Policy VXLAN extension security label mechanism + across network peers based on VXLAN. For details about the Group Policy VXLAN, see the + <ulink url="https://tools.ietf.org/html/draft-smith-vxlan-group-policy"> + VXLAN Group Policy </ulink> document. Defaults to false.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DestinationPort=</varname></term> + <listitem> + <para>Configures the default destination UDP port on a per-device basis. + If destination port is not specified then Linux kernel default will be used. + Set destination port 4789 to get the IANA assigned value, + and destination port 0 to get default values.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>PortRange=</varname></term> + <listitem> + <para>Configures VXLAN port range. VXLAN bases source + UDP port based on flow to help the receiver to be able + to load balance based on outer header flow. It + restricts the port range to the normal UDP local + ports, and allows overriding via configuration.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>[Tunnel] Section Options</title> + + <para>The <literal>[Tunnel]</literal> section only applies for + netdevs of kind + <literal>ipip</literal>, + <literal>sit</literal>, + <literal>gre</literal>, + <literal>gretap</literal>, + <literal>ip6gre</literal>, + <literal>ip6gretap</literal>, + <literal>vti</literal>, + <literal>vti6</literal>, and + <literal>ip6tnl</literal> and accepts + the following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Local=</varname></term> + <listitem> + <para>A static local address for tunneled packets. It must + be an address on another interface of this host.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Remote=</varname></term> + <listitem> + <para>The remote endpoint of the tunnel.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>TOS=</varname></term> + <listitem> + <para>The Type Of Service byte value for a tunnel interface. + For details about the TOS, see the + <ulink url="http://tools.ietf.org/html/rfc1349"> Type of + Service in the Internet Protocol Suite </ulink> document. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>TTL=</varname></term> + <listitem> + <para>A fixed Time To Live N on tunneled packets. N is a + number in the range 1–255. 0 is a special value meaning that + packets inherit the TTL value. The default value for IPv4 + tunnels is: inherit. The default value for IPv6 tunnels is + 64.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DiscoverPathMTU=</varname></term> + <listitem> + <para>A boolean. When true, enables Path MTU Discovery on + the tunnel.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>IPv6FlowLabel=</varname></term> + <listitem> + <para>Configures the 20-bit flow label (see <ulink url="https://tools.ietf.org/html/rfc6437"> + RFC 6437</ulink>) field in the IPv6 header (see <ulink url="https://tools.ietf.org/html/rfc2460"> + RFC 2460</ulink>), which is used by a node to label packets of a flow. + It is only used for IPv6 tunnels. + A flow label of zero is used to indicate packets that have + not been labeled. + It can be configured to a value in the range 0–0xFFFFF, or be + set to <literal>inherit</literal>, in which case the original flowlabel is used.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>CopyDSCP=</varname></term> + <listitem> + <para>A boolean. When true, the Differentiated Service Code + Point (DSCP) field will be copied to the inner header from + outer header during the decapsulation of an IPv6 tunnel + packet. DSCP is a field in an IP packet that enables different + levels of service to be assigned to network traffic. + Defaults to <literal>no</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>EncapsulationLimit=</varname></term> + <listitem> + <para>The Tunnel Encapsulation Limit option specifies how many additional + levels of encapsulation are permitted to be prepended to the packet. + For example, a Tunnel Encapsulation Limit option containing a limit + value of zero means that a packet carrying that option may not enter + another tunnel before exiting the current tunnel. + (see <ulink url="https://tools.ietf.org/html/rfc2473#section-4.1.1"> RFC 2473</ulink>). + The valid range is 0–255 and <literal>none</literal>. Defaults to 4. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Key=</varname></term> + <listitem> + <para>The <varname>Key=</varname> parameter specifies the same key to use in + both directions (<varname>InputKey=</varname> and <varname>OutputKey=</varname>). + The <varname>Key=</varname> is either a number or an IPv4 address-like dotted quad. + It is used as mark-configured SAD/SPD entry as part of the lookup key (both in data + and control path) in ip xfrm (framework used to implement IPsec protocol). + See <ulink url="http://man7.org/linux/man-pages/man8/ip-xfrm.8.html"> + ip-xfrm — transform configuration</ulink> for details. It is only used for VTI/VTI6 + tunnels.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>InputKey=</varname></term> + <listitem> + <para>The <varname>InputKey=</varname> parameter specifies the key to use for input. + The format is same as <varname>Key=</varname>. It is only used for VTI/VTI6 tunnels.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>OutputKey=</varname></term> + <listitem> + <para>The <varname>OutputKey=</varname> parameter specifies the key to use for output. + The format is same as <varname>Key=</varname>. It is only used for VTI/VTI6 tunnels.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Mode=</varname></term> + <listitem> + <para>An <literal>ip6tnl</literal> tunnel can be in one of three + modes + <literal>ip6ip6</literal> for IPv6 over IPv6, + <literal>ipip6</literal> for IPv4 over IPv6 or + <literal>any</literal> for either. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>[Peer] Section Options</title> + + <para>The <literal>[Peer]</literal> section only applies for + netdevs of kind <literal>veth</literal> and accepts the + following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Name=</varname></term> + <listitem> + <para>The interface name used when creating the netdev. + This option is compulsory.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>The peer MACAddress, if not set, it is generated in + the same way as the MAC address of the main + interface.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>[Tun] Section Options</title> + + <para>The <literal>[Tun]</literal> section only applies for + netdevs of kind <literal>tun</literal>, and accepts the following + keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>OneQueue=</varname></term> + <listitem><para>Takes a boolean argument. Configures whether + all packets are queued at the device (enabled), or a fixed + number of packets are queued at the device and the rest at the + <literal>qdisc</literal>. Defaults to + <literal>no</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MultiQueue=</varname></term> + <listitem><para>Takes a boolean argument. Configures whether + to use multiple file descriptors (queues) to parallelize + packets sending and receiving. Defaults to + <literal>no</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>PacketInfo=</varname></term> + <listitem><para>Takes a boolean argument. Configures whether + packets should be prepended with four extra bytes (two flag + bytes and two protocol bytes). If disabled, it indicates that + the packets will be pure IP packets. Defaults to + <literal>no</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>VNetHeader=</varname></term> + <listitem><para>Takes a boolean argument. Configures + IFF_VNET_HDR flag for a tap device. It allows sending + and receiving larger Generic Segmentation Offload (GSO) + packets. This may increase throughput significantly. + Defaults to + <literal>no</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>User=</varname></term> + <listitem><para>User to grant access to the + <filename>/dev/net/tun</filename> device.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Group=</varname></term> + <listitem><para>Group to grant access to the + <filename>/dev/net/tun</filename> device.</para> + </listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>[Tap] Section Options</title> + + <para>The <literal>[Tap]</literal> section only applies for + netdevs of kind <literal>tap</literal>, and accepts the same keys + as the <literal>[Tun]</literal> section.</para> + </refsect1> + + <refsect1> + <title>[Bond] Section Options</title> + + <para>The <literal>[Bond]</literal> section accepts the following + key:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Mode=</varname></term> + <listitem> + <para>Specifies one of the bonding policies. The default is + <literal>balance-rr</literal> (round robin). Possible values are + <literal>balance-rr</literal>, + <literal>active-backup</literal>, + <literal>balance-xor</literal>, + <literal>broadcast</literal>, + <literal>802.3ad</literal>, + <literal>balance-tlb</literal>, and + <literal>balance-alb</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>TransmitHashPolicy=</varname></term> + <listitem> + <para>Selects the transmit hash policy to use for slave + selection in balance-xor, 802.3ad, and tlb modes. Possible + values are + <literal>layer2</literal>, + <literal>layer3+4</literal>, + <literal>layer2+3</literal>, + <literal>encap2+3</literal>, and + <literal>encap3+4</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>LACPTransmitRate=</varname></term> + <listitem> + <para>Specifies the rate with which link partner transmits + Link Aggregation Control Protocol Data Unit packets in + 802.3ad mode. Possible values are <literal>slow</literal>, + which requests partner to transmit LACPDUs every 30 seconds, + and <literal>fast</literal>, which requests partner to + transmit LACPDUs every second. The default value is + <literal>slow</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MIIMonitorSec=</varname></term> + <listitem> + <para>Specifies the frequency that Media Independent + Interface link monitoring will occur. A value of zero + disables MII link monitoring. This value is rounded down to + the nearest millisecond. The default value is 0.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>UpDelaySec=</varname></term> + <listitem> + <para>Specifies the delay before a link is enabled after a + link up status has been detected. This value is rounded down + to a multiple of MIIMonitorSec. The default value is + 0.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>DownDelaySec=</varname></term> + <listitem> + <para>Specifies the delay before a link is disabled after a + link down status has been detected. This value is rounded + down to a multiple of MIIMonitorSec. The default value is + 0.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>LearnPacketIntervalSec=</varname></term> + <listitem> + <para>Specifies the number of seconds between instances where the bonding + driver sends learning packets to each slave peer switch. + The valid range is 1–0x7fffffff; the default value is 1. This option + has an effect only for the balance-tlb and balance-alb modes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>AdSelect=</varname></term> + <listitem> + <para>Specifies the 802.3ad aggregation selection logic to use. Possible values are + <literal>stable</literal>, + <literal>bandwidth</literal> and + <literal>count</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>FailOverMACPolicy=</varname></term> + <listitem> + <para>Specifies whether the active-backup mode should set all slaves to + the same MAC address at the time of enslavement or, when enabled, to perform special handling of the + bond's MAC address in accordance with the selected policy. The default policy is none. + Possible values are + <literal>none</literal>, + <literal>active</literal> and + <literal>follow</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ARPValidate=</varname></term> + <listitem> + <para>Specifies whether or not ARP probes and replies should be + validated in any mode that supports ARP monitoring, or whether + non-ARP traffic should be filtered (disregarded) for link + monitoring purposes. Possible values are + <literal>none</literal>, + <literal>active</literal>, + <literal>backup</literal> and + <literal>all</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ARPIntervalSec=</varname></term> + <listitem> + <para>Specifies the ARP link monitoring frequency in milliseconds. + A value of 0 disables ARP monitoring. The default value is 0. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ARPIPTargets=</varname></term> + <listitem> + <para>Specifies the IP addresses to use as ARP monitoring peers when + ARPIntervalSec is greater than 0. These are the targets of the ARP request + sent to determine the health of the link to the targets. + Specify these values in IPv4 dotted decimal format. At least one IP + address must be given for ARP monitoring to function. The + maximum number of targets that can be specified is 16. The + default value is no IP addresses. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ARPAllTargets=</varname></term> + <listitem> + <para>Specifies the quantity of ARPIPTargets that must be reachable + in order for the ARP monitor to consider a slave as being up. + This option affects only active-backup mode for slaves with + ARPValidate enabled. Possible values are + <literal>any</literal> and + <literal>all</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>PrimaryReselectPolicy=</varname></term> + <listitem> + <para>Specifies the reselection policy for the primary slave. This + affects how the primary slave is chosen to become the active slave + when failure of the active slave or recovery of the primary slave + occurs. This option is designed to prevent flip-flopping between + the primary slave and other slaves. Possible values are + <literal>always</literal>, + <literal>better</literal> and + <literal>failure</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ResendIGMP=</varname></term> + <listitem> + <para>Specifies the number of IGMP membership reports to be issued after + a failover event. One membership report is issued immediately after + the failover, subsequent packets are sent in each 200ms interval. + The valid range is 0–255. Defaults to 1. A value of 0 + prevents the IGMP membership report from being issued in response + to the failover event. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>PacketsPerSlave=</varname></term> + <listitem> + <para>Specify the number of packets to transmit through a slave before + moving to the next one. When set to 0, then a slave is chosen at + random. The valid range is 0–65535. Defaults to 1. This option + only has effect when in balance-rr mode. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>GratuitousARP=</varname></term> + <listitem> + <para>Specify the number of peer notifications (gratuitous ARPs and + unsolicited IPv6 Neighbor Advertisements) to be issued after a + failover event. As soon as the link is up on the new slave, + a peer notification is sent on the bonding device and each + VLAN sub-device. This is repeated at each link monitor interval + (ARPIntervalSec or MIIMonitorSec, whichever is active) if the number is + greater than 1. The valid range is 0–255. The default value is 1. + These options affect only the active-backup mode. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>AllSlavesActive=</varname></term> + <listitem> + <para>A boolean. Specifies that duplicate frames (received on inactive ports) + should be dropped when false, or delivered when true. Normally, bonding will drop + duplicate frames (received on inactive ports), which is desirable for + most users. But there are some times it is nice to allow duplicate + frames to be delivered. The default value is false (drop duplicate frames + received on inactive ports). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MinLinks=</varname></term> + <listitem> + <para>Specifies the minimum number of links that must be active before + asserting carrier. The default value is 0. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para>For more detail information see + <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt"> + Linux Ethernet Bonding Driver HOWTO</ulink></para> + + </refsect1> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/systemd/network/25-bridge.netdev</title> + + <programlisting>[NetDev] +Name=bridge0 +Kind=bridge</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-vlan1.netdev</title> + + <programlisting>[Match] +Virtualization=no + +[NetDev] +Name=vlan1 +Kind=vlan + +[VLAN] +Id=1</programlisting> + </example> + <example> + <title>/etc/systemd/network/25-ipip.netdev</title> + <programlisting>[NetDev] +Name=ipip-tun +Kind=ipip +MTUBytes=1480 + +[Tunnel] +Local=192.168.223.238 +Remote=192.169.224.239 +TTL=64</programlisting> + </example> + <example> + <title>/etc/systemd/network/25-tap.netdev</title> + <programlisting>[NetDev] +Name=tap-test +Kind=tap + +[Tap] +MultiQueue=true +PacketInfo=true</programlisting> </example> + + <example> + <title>/etc/systemd/network/25-sit.netdev</title> + <programlisting>[NetDev] +Name=sit-tun +Kind=sit +MTUBytes=1480 + +[Tunnel] +Local=10.65.223.238 +Remote=10.65.223.239</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-gre.netdev</title> + <programlisting>[NetDev] +Name=gre-tun +Kind=gre +MTUBytes=1480 + +[Tunnel] +Local=10.65.223.238 +Remote=10.65.223.239</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-vti.netdev</title> + + <programlisting>[NetDev] +Name=vti-tun +Kind=vti +MTUBytes=1480 + +[Tunnel] +Local=10.65.223.238 +Remote=10.65.223.239</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-veth.netdev</title> + <programlisting>[NetDev] +Name=veth-test +Kind=veth + +[Peer] +Name=veth-peer</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-bond.netdev</title> + <programlisting>[NetDev] +Name=bond1 +Kind=bond + +[Bond] +Mode=802.3ad +TransmitHashPolicy=layer3+4 +MIIMonitorSec=1s +LACPTransmitRate=fast +</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-dummy.netdev</title> + <programlisting>[NetDev] +Name=dummy-test +Kind=dummy +MACAddress=12:34:56:78:9a:bc</programlisting> + </example> + <example> + <title>/etc/systemd/network/25-vrf.netdev</title> + <para>Create a VRF interface with table 42.</para> + <programlisting>[NetDev] +Name=vrf-test +Kind=vrf + +[VRF] +TableId=42</programlisting> + </example> + </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.network.xml b/src/grp-system/systemd/systemd.network.xml new file mode 100644 index 0000000000..2fb4907634 --- /dev/null +++ b/src/grp-system/systemd/systemd.network.xml @@ -0,0 +1,1409 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2013 Tom Gundersen + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.network" conditional='ENABLE_NETWORKD'> + + <refentryinfo> + <title>systemd.network</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Tom</firstname> + <surname>Gundersen</surname> + <email>teg@jklm.no</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.network</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.network</refname> + <refpurpose>Network configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>network</replaceable>.network</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Network setup is performed by + <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para> + + <para>The main network file must have the extension <filename>.network</filename>; other + extensions are ignored. Networks are applied to links whenever the links appear.</para> + + <para>The <filename>.network</filename> files are read from the files located in the system + network directory <filename>/usr/lib/systemd/network</filename>, the volatile runtime network + directory <filename>/run/systemd/network</filename> and the local administration network + directory <filename>/etc/systemd/network</filename>. All configuration files are collectively + sorted and processed in lexical order, regardless of the directories in which they live. + However, files with identical filenames replace each other. Files in <filename>/etc</filename> + have the highest priority, files in <filename>/run</filename> take precedence over files with + the same name in <filename>/usr/lib</filename>. This can be used to override a system-supplied + configuration file with a local file if needed. As a special case, an empty file (file size 0) + or symlink with the same name pointing to <filename>/dev/null</filename> disables the + configuration file entirely (it is "masked").</para> + + <para>Along with the network file <filename>foo.network</filename>, a "drop-in" directory + <filename>foo.network.d/</filename> may exist. All files with the suffix + <literal>.conf</literal> from this directory will be parsed after the file itself is + parsed. This is useful to alter or add configuration settings, without having to modify the main + configuration file. Each drop-in file must have appropriate section headers.</para> + + <para>In addition to <filename>/etc/systemd/network</filename>, drop-in <literal>.d</literal> + directories can be placed in <filename>/usr/lib/systemd/network</filename> or + <filename>/run/systemd/network</filename> directories. Drop-in files in + <filename>/etc</filename> take precedence over those in <filename>/run</filename> which in turn + take precedence over those in <filename>/usr/lib</filename>. Drop-in files under any of these + directories take precedence over the main netdev file wherever located. (Of course, since + <filename>/run</filename> is temporary and <filename>/usr/lib</filename> is for vendors, it is + unlikely drop-ins should be used in either of those places.)</para> + + <para>Note that an interface without any static IPv6 addresses configured, and neither DHCPv6 + nor IPv6LL enabled, shall be considered to have no IPv6 support. IPv6 will be automatically + disabled for that interface by writing "1" to + <filename>/proc/sys/net/ipv6/conf/<replaceable>ifname</replaceable>/disable_ipv6</filename>. + </para> + </refsect1> + + <refsect1> + <title>[Match] Section Options</title> + + <para>The network file contains a <literal>[Match]</literal> + section, which determines if a given network file may be applied + to a given device; and a <literal>[Network]</literal> section + specifying how the device should be configured. The first (in + lexical order) of the network files that matches a given device + is applied, all later files are ignored, even if they match as + well.</para> + + <para>A network file is said to match a device if each of the + entries in the <literal>[Match]</literal> section matches, or if + the section is empty. The following keys are accepted:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>The hardware address of the interface (use full colon-delimited hexadecimal, e.g., + 01:23:45:67:89:ab).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Path=</varname></term> + <listitem> + <para>A whitespace-separated list of shell-style globs + matching the persistent path, as exposed by the udev + property <literal>ID_PATH</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Driver=</varname></term> + <listitem> + <para>A whitespace-separated list of shell-style globs + matching the driver currently bound to the device, as + exposed by the udev property <literal>DRIVER</literal> + of its parent device, or if that is not set the driver + as exposed by <literal>ethtool -i</literal> of the + device itself.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Type=</varname></term> + <listitem> + <para>A whitespace-separated list of shell-style globs + matching the device type, as exposed by the udev property + <literal>DEVTYPE</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Name=</varname></term> + <listitem> + <para>A whitespace-separated list of shell-style globs + matching the device name, as exposed by the udev property + <literal>INTERFACE</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Host=</varname></term> + <listitem> + <para>Matches against the hostname or machine ID of the + host. See <literal>ConditionHost=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Virtualization=</varname></term> + <listitem> + <para>Checks whether the system is executed in a virtualized + environment and optionally test whether it is a specific + implementation. See <literal>ConditionVirtualization=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>KernelCommandLine=</varname></term> + <listitem> + <para>Checks whether a specific kernel command line option is + set (or if prefixed with the exclamation mark unset). See + <literal>ConditionKernelCommandLine=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Architecture=</varname></term> + <listitem> + <para>Checks whether the system is running on a specific + architecture. See <literal>ConditionArchitecture=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>[Link] Section Options</title> + + <para> The <literal>[Link]</literal> section accepts the following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>The hardware address to set for the device.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MTUBytes=</varname></term> + <listitem> + <para>The maximum transmission unit in bytes to set for the + device. The usual suffixes K, M, G, are supported and are + understood to the base of 1024.</para> + <para>Note that if IPv6 is enabled on the interface, and the MTU is chosen + below 1280 (the minimum MTU for IPv6) it will automatically be increased to this value.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>ARP=</varname></term> + <listitem> + <para> A boolean. Enables or disables the ARP (low-level Address Resolution Protocol) + for this interface. Defaults to unset, which means that the kernel default will be used.</para> + <para> For example, disabling ARP is useful when creating multiple MACVLAN or VLAN virtual + interfaces atop a single lower-level physical interface, which will then only serve as a + link/"bridge" device aggregating traffic to the same physical link and not participate in + the network otherwise.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[Network] Section Options</title> + + <para>The <literal>[Network]</literal> section accepts the following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Description=</varname></term> + <listitem> + <para>A description of the device. This is only used for + presentation purposes.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DHCP=</varname></term> + <listitem> + <para>Enables DHCPv4 and/or DHCPv6 client support. Accepts + <literal>yes</literal>, <literal>no</literal>, + <literal>ipv4</literal>, or <literal>ipv6</literal>.</para> + + <para>Note that DHCPv6 will by default be triggered by Router + Advertisement, if that is enabled, regardless of this parameter. + By enabling DHCPv6 support explicitly, the DHCPv6 client will + be started regardless of the presence of routers on the link, + or what flags the routers pass. See + <literal>IPv6AcceptRA=</literal>.</para> + + <para>Furthermore, note that by default the domain name + specified through DHCP is not used for name resolution. + See option <option>UseDomains=</option> below.</para> + + <para>See the <literal>[DHCP]</literal> section below for further configuration options for the DHCP client + support.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DHCPServer=</varname></term> + <listitem> + <para>A boolean. Enables DHCPv4 server support. Defaults + to <literal>no</literal>. Further settings for the DHCP + server may be set in the <literal>[DHCPServer]</literal> + section described below.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>LinkLocalAddressing=</varname></term> + <listitem> + <para>Enables link-local address autoconfiguration. Accepts + <literal>yes</literal>, <literal>no</literal>, + <literal>ipv4</literal>, or <literal>ipv6</literal>. Defaults to + <literal>ipv6</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>IPv4LLRoute=</varname></term> + <listitem> + <para>A boolean. When true, sets up the route needed for + non-IPv4LL hosts to communicate with IPv4LL-only hosts. Defaults + to false. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>IPv6Token=</varname></term> + <listitem> + <para>An IPv6 address with the top 64 bits unset. When set, indicates the + 64-bit interface part of SLAAC IPv6 addresses for this link. Note that + the token is only ever used for SLAAC, and not for DHCPv6 addresses, even + in the case DHCP is requested by router advertisement. By default, the + token is autogenerated.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>LLMNR=</varname></term> + <listitem> + <para>A boolean or <literal>resolve</literal>. When true, + enables <ulink + url="https://tools.ietf.org/html/rfc4795">Link-Local + Multicast Name Resolution</ulink> on the link. When set to + <literal>resolve</literal>, only resolution is enabled, + but not host registration and announcement. Defaults to + true. This setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MulticastDNS=</varname></term> + <listitem> + <para>A boolean or <literal>resolve</literal>. When true, + enables <ulink + url="https://tools.ietf.org/html/rfc6762">Multicast + DNS</ulink> support on the link. When set to + <literal>resolve</literal>, only resolution is enabled, + but not host or service registration and + announcement. Defaults to false. This setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DNSSEC=</varname></term> + <listitem> + <para>A boolean or + <literal>allow-downgrade</literal>. When true, enables + <ulink + url="https://tools.ietf.org/html/rfc4033">DNSSEC</ulink> + DNS validation support on the link. When set to + <literal>allow-downgrade</literal>, compatibility with + non-DNSSEC capable networks is increased, by automatically + turning off DNSEC in this case. This option defines a + per-interface setting for + <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s + global <varname>DNSSEC=</varname> option. Defaults to + false. This setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DNSSECNegativeTrustAnchors=</varname></term> + <listitem><para>A space-separated list of DNSSEC negative + trust anchor domains. If specified and DNSSEC is enabled, + look-ups done via the interface's DNS server will be subject + to the list of negative trust anchors, and not require + authentication for the specified domains, or anything below + it. Use this to disable DNSSEC authentication for specific + private domains, that cannot be proven valid using the + Internet DNS hierarchy. Defaults to the empty list. This + setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>LLDP=</varname></term> + <listitem> + <para>Controls support for Ethernet LLDP packet reception. LLDP is a link-layer protocol commonly + implemented on professional routers and bridges which announces which physical port a system is connected + to, as well as other related data. Accepts a boolean or the special value + <literal>routers-only</literal>. When true, incoming LLDP packets are accepted and a database of all LLDP + neighbors maintained. If <literal>routers-only</literal> is set only LLDP data of various types of routers + is collected and LLDP data about other types of devices ignored (such as stations, telephones and + others). If false, LLDP reception is disabled. Defaults to <literal>routers-only</literal>. Use + <citerefentry><refentrytitle>networkctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to query the + collected neighbor data. LLDP is only available on Ethernet links. See <varname>EmitLLDP=</varname> below + for enabling LLDP packet emission from the local system. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>EmitLLDP=</varname></term> + <listitem> + <para>Controls support for Ethernet LLDP packet emission. Accepts a boolean parameter or the special values + <literal>nearest-bridge</literal>, <literal>non-tpmr-bridge</literal> and + <literal>customer-bridge</literal>. Defaults to false, which turns off LLDP packet emission. If not false, + a short LLDP packet with information about the local system is sent out in regular intervals on the + link. The LLDP packet will contain information about the local host name, the local machine ID (as stored + in <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>) and the + local interface name, as well as the pretty hostname of the system (as set in + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>). LLDP + emission is only available on Ethernet links. Note that this setting passes data suitable for + identification of host to the network and should thus not be enabled on untrusted networks, where such + identification data should not be made available. Use this option to permit other systems to identify on + which interfaces they are connected to this system. The three special values control propagation of the + LLDP packets. The <literal>nearest-bridge</literal> setting permits propagation only to the nearest + connected bridge, <literal>non-tpmr-bridge</literal> permits propagation across Two-Port MAC Relays, but + not any other bridges, and <literal>customer-bridge</literal> permits propagation until a customer bridge + is reached. For details about these concepts, see <ulink + url="http://standards.ieee.org/getieee802/download/802.1AB-2009.pdf">IEEE 802.1AB-2009</ulink>. Note that + configuring this setting to true is equivalent to <literal>nearest-bridge</literal>, the recommended and + most restricted level of propagation. See <varname>LLDP=</varname> above for an option to enable LLDP + reception.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>BindCarrier=</varname></term> + <listitem> + <para>A link name or a list of link names. When set, controls the behavior of the current + link. When all links in the list are in an operational down state, the current link is brought + down. When at least one link has carrier, the current interface is brought up. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Address=</varname></term> + <listitem> + <para>A static IPv4 or IPv6 address and its prefix length, + separated by a <literal>/</literal> character. Specify + this key more than once to configure several addresses. + The format of the address must be as described in + <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This is a short-hand for an [Address] section only + containing an Address key (see below). This option may be + specified more than once. + </para> + + <para>If the specified address is 0.0.0.0 (for IPv4) or + [::] (for IPv6), a new address range of the requested size + is automatically allocated from a system-wide pool of + unused ranges. The allocated range is checked against all + current network interfaces and all known network + configuration files to avoid address range conflicts. The + default system-wide pool consists of 192.168.0.0/16, + 172.16.0.0/12 and 10.0.0.0/8 for IPv4, and fc00::/7 for + IPv6. This functionality is useful to manage a large + number of dynamically created network interfaces with the + same network configuration and automatic address range + assignment.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Gateway=</varname></term> + <listitem> + <para>The gateway address, which must be in the format + described in + <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This is a short-hand for a [Route] section only containing + a Gateway key. This option may be specified more than + once.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DNS=</varname></term> + <listitem> + <para>A DNS server address, which must be in the format + described in + <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This option may be specified more than once. This setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Domains=</varname></term> + <listitem> + <para>A list of domains which should be resolved using the DNS servers on this link. Each item in the list + should be a domain name, optionally prefixed with a tilde (<literal>~</literal>). The domains with the + prefix are called "routing-only domains". The domains without the prefix are called "search domains" and + are first used as search suffixes for extending single-label host names (host names containing no dots) to + become fully qualified domain names (FQDNs). If a single-label host name is resolved on this interface, + each of the specified search domains are appended to it in turn, converting it into a fully qualified + domain name, until one of them may be successfully resolved.</para> + + <para>Both "search" and "routing-only" domains are used for routing of DNS queries: look-ups for host names + ending in those domains (hence also single label names, if any "search domains" are listed), are routed to + the DNS servers configured for this interface. The domain routing logic is particularly useful on + multi-homed hosts with DNS servers serving particular private DNS zones on each interface.</para> + + <para>The "routing-only" domain <literal>~.</literal> (the tilde indicating definition of a routing domain, + the dot referring to the DNS root domain which is the implied suffix of all valid DNS names) has special + effect. It causes all DNS traffic which does not match another configured domain routing entry to be routed + to DNS servers specified for this interface. This setting is useful to prefer a certain set of DNS servers + if a link on which they are connected is available.</para> + + <para>This setting is read by + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + "Search domains" correspond to the <varname>domain</varname> and <varname>search</varname> entries in + <citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Domain name routing has no equivalent in the traditional glibc API, which has no concept of domain + name servers limited to a specific link.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>NTP=</varname></term> + <listitem> + <para>An NTP server address. This option may be specified more than once. This setting is read by + <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>IPForward=</varname></term> + <listitem><para>Configures IP packet forwarding for the + system. If enabled, incoming packets on any network + interface will be forwarded to any other interfaces + according to the routing table. Takes either a boolean + argument, or the values <literal>ipv4</literal> or + <literal>ipv6</literal>, which only enable IP packet + forwarding for the specified address family. This controls + the <filename>net.ipv4.ip_forward</filename> and + <filename>net.ipv6.conf.all.forwarding</filename> sysctl + options of the network interface (see <ulink + url="https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt">ip-sysctl.txt</ulink> + for details about sysctl options). Defaults to + <literal>no</literal>.</para> + + <para>Note: this setting controls a global kernel option, + and does so one way only: if a network that has this setting + enabled is set up the global setting is turned on. However, + it is never turned off again, even after all networks with + this setting enabled are shut down again.</para> + + <para>To allow IP packet forwarding only between specific + network interfaces use a firewall.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>IPMasquerade=</varname></term> + <listitem><para>Configures IP masquerading for the network + interface. If enabled, packets forwarded from the network + interface will be appear as coming from the local host. + Takes a boolean argument. Implies + <varname>IPForward=ipv4</varname>. Defaults to + <literal>no</literal>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>IPv6PrivacyExtensions=</varname></term> + <listitem><para>Configures use of stateless temporary + addresses that change over time (see <ulink + url="https://tools.ietf.org/html/rfc4941">RFC 4941</ulink>, + Privacy Extensions for Stateless Address Autoconfiguration + in IPv6). Takes a boolean or the special values + <literal>prefer-public</literal> and + <literal>kernel</literal>. When true, enables the privacy + extensions and prefers temporary addresses over public + addresses. When <literal>prefer-public</literal>, enables the + privacy extensions, but prefers public addresses over + temporary addresses. When false, the privacy extensions + remain disabled. When <literal>kernel</literal>, the kernel's + default setting will be left in place. Defaults to + <literal>no</literal>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>IPv6AcceptRA=</varname></term> + <listitem><para>Enable or disable IPv6 Router Advertisement (RA) reception support for the interface. Takes + a boolean parameter. If true, RAs are accepted; if false, RAs are ignored, independently of the local + forwarding state. When not set, the kernel default is used, and RAs are accepted only when local forwarding + is disabled for that interface. When RAs are accepted, they may trigger the start of the DHCPv6 client if + the relevant flags are set in the RA data, or if no routers are found on the link.</para> + + <para>Further settings for the IPv6 RA support may be configured in the + <literal>[IPv6AcceptRA]</literal> section, see below.</para> + + <para>Also see <ulink + url="https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt">ip-sysctl.txt</ulink> in the kernel + documentation regarding <literal>accept_ra</literal>, but note that systemd's setting of + <constant>1</constant> (i.e. true) corresponds to kernel's setting of <constant>2</constant>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>IPv6DuplicateAddressDetection=</varname></term> + <listitem><para>Configures the amount of IPv6 Duplicate + Address Detection (DAD) probes to send. Defaults to unset. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>IPv6HopLimit=</varname></term> + <listitem><para>Configures IPv6 Hop Limit. For each router that + forwards the packet, the hop limit is decremented by 1. When the + hop limit field reaches zero, the packet is discarded. + Defaults to unset. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>ProxyARP=</varname></term> + <listitem><para>A boolean. Configures proxy ARP. Proxy ARP is the technique in which one host, + usually a router, answers ARP requests intended for another machine. By "faking" its identity, + the router accepts responsibility for routing packets to the "real" destination. (see <ulink + url="https://tools.ietf.org/html/rfc1027">RFC 1027</ulink>. + Defaults to unset. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>Bridge=</varname></term> + <listitem> + <para>The name of the bridge to add the link to.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Bond=</varname></term> + <listitem> + <para>The name of the bond to add the link to.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>VRF=</varname></term> + <listitem> + <para>The name of the VRF to add the link to.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>VLAN=</varname></term> + <listitem> + <para>The name of a VLAN to create on the link. This + option may be specified more than once.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MACVLAN=</varname></term> + <listitem> + <para>The name of a MACVLAN to create on the link. This + option may be specified more than once.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>VXLAN=</varname></term> + <listitem> + <para>The name of a VXLAN to create on the link. This + option may be specified more than once.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Tunnel=</varname></term> + <listitem> + <para>The name of a Tunnel to create on the link. This + option may be specified more than once.</para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>[Address] Section Options</title> + + <para>An <literal>[Address]</literal> section accepts the + following keys. Specify several <literal>[Address]</literal> + sections to configure several addresses.</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Address=</varname></term> + <listitem> + <para>As in the <literal>[Network]</literal> section. This + key is mandatory.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Peer=</varname></term> + <listitem> + <para>The peer address in a point-to-point connection. + Accepts the same format as the <literal>Address</literal> + key.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Broadcast=</varname></term> + <listitem> + <para>The broadcast address, which must be in the format + described in + <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This key only applies to IPv4 addresses. If it is not + given, it is derived from the <literal>Address</literal> + key.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Label=</varname></term> + <listitem> + <para>An address label.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>PreferredLifetime=</varname></term> + <listitem> + <para>Allows the default "preferred lifetime" of the address to be overridden. + Only three settings are accepted: <literal>forever</literal> or <literal>infinity</literal> + which is the default and means that the address never expires, and <literal>0</literal> which means + that the address is considered immediately "expired" and will not be used, + unless explicitly requested. A setting of PreferredLifetime=0 is useful for + addresses which are added to be used only by a specific application, + which is then configured to use them explicitly.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>HomeAddress=</varname></term> + <listitem> + <para>Takes a boolean argument. Designates this address the "home address" as defined in + <ulink url="https://tools.ietf.org/html/rfc6275">RFC 6275</ulink>. + Supported only on IPv6. Defaults to false.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DuplicateAddressDetection=</varname></term> + <listitem> + <para>Takes a boolean argument. Do not perform Duplicate Address Detection + <ulink url="https://tools.ietf.org/html/rfc4862">RFC 4862</ulink> when adding this address. + Supported only on IPv6. Defaults to false.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>ManageTemporaryAddress=</varname></term> + <listitem> + <para>Takes a boolean argument. If true the kernel manage temporary addresses created + from this one as template on behalf of Privacy Extensions + <ulink url="https://tools.ietf.org/html/rfc3041">RFC 3041</ulink>. For this to become + active, the use_tempaddr sysctl setting has to be set to a value greater than zero. + The given address needs to have a prefix length of 64. This flag allows to use privacy + extensions in a manually configured network, just like if stateless auto-configuration + was active. Defaults to false. </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>PrefixRoute=</varname></term> + <listitem> + <para>Takes a boolean argument. When adding or modifying an IPv6 address, the userspace + application needs a way to suppress adding a prefix route. This is for example relevant + together with IFA_F_MANAGERTEMPADDR, where userspace creates autoconf generated addresses, + but depending on on-link, no route for the prefix should be added. Defaults to false.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>AutoJoin=</varname></term> + <listitem> + <para>Takes a boolean argument. Joining multicast group on ethernet level via + <command>ip maddr</command> command would not work if we have an Ethernet switch that does + IGMP snooping since the switch would not replicate multicast packets on ports that did not + have IGMP reports for the multicast addresses. Linux vxlan interfaces created via + <command>ip link add vxlan</command> or networkd's netdev kind vxlan have the group option + that enables then to do the required join. By extending ip address command with option + <literal>autojoin</literal> we can get similar functionality for openvswitch (OVS) vxlan + interfaces as well as other tunneling mechanisms that need to receive multicast traffic. + Defaults to <literal>no</literal>.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[Route] Section Options</title> + <para>The <literal>[Route]</literal> section accepts the + following keys. Specify several <literal>[Route]</literal> + sections to configure several routes.</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Gateway=</varname></term> + <listitem> + <para>As in the <literal>[Network]</literal> section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Destination=</varname></term> + <listitem> + <para>The destination prefix of the route. Possibly + followed by a slash and the prefix length. If omitted, a + full-length host route is assumed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Source=</varname></term> + <listitem> + <para>The source prefix of the route. Possibly followed by + a slash and the prefix length. If omitted, a full-length + host route is assumed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Metric=</varname></term> + <listitem> + <para>The metric of the route (an unsigned integer).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Scope=</varname></term> + <listitem> + <para>The scope of the route, which can be <literal>global</literal>, + <literal>link</literal> or <literal>host</literal>. Defaults to + <literal>global</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>PreferredSource=</varname></term> + <listitem> + <para>The preferred source address of the route. The address + must be in the format described in + <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Table=<replaceable>num</replaceable></varname></term> + <listitem> + <para>The table identifier for the route (a number between 1 and 4294967295, or 0 to unset). + The table can be retrieved using <command>ip route show table <replaceable>num</replaceable></command>. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[DHCP] Section Options</title> + <para>The <literal>[DHCP]</literal> section configures the + DHCPv4 and DHCP6 client, if it is enabled with the + <varname>DHCP=</varname> setting described above:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>UseDNS=</varname></term> + <listitem> + <para>When true (the default), the DNS servers received + from the DHCP server will be used and take precedence over + any statically configured ones.</para> + + <para>This corresponds to the <option>nameserver</option> + option in <citerefentry + project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UseNTP=</varname></term> + <listitem> + <para>When true (the default), the NTP servers received + from the DHCP server will be used by systemd-timesyncd + and take precedence over any statically configured ones.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UseMTU=</varname></term> + <listitem> + <para>When true, the interface maximum transmission unit + from the DHCP server will be used on the current link. + Defaults to false.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>SendHostname=</varname></term> + <listitem> + <para>When true (the default), the machine's hostname will + be sent to the DHCP server.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UseHostname=</varname></term> + <listitem> + <para>When true (the default), the hostname received from + the DHCP server will be set as the transient hostname of the system + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Hostname=</varname></term> + <listitem> + <para>Use this value for the hostname which is sent to the + DHCP server, instead of machine's hostname.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UseDomains=</varname></term> + <listitem> + <para>Takes a boolean argument, or the special value <literal>route</literal>. When true, the domain name + received from the DHCP server will be used as DNS search domain over this link, similar to the effect of + the <option>Domains=</option> setting. If set to <literal>route</literal>, the domain name received from + the DHCP server will be used for routing DNS queries only, but not for searching, similar to the effect of + the <option>Domains=</option> setting when the argument is prefixed with <literal>~</literal>. Defaults to + false.</para> + + <para>It is recommended to enable this option only on trusted networks, as setting this affects resolution + of all host names, in particular of single-label names. It is generally safer to use the supplied domain + only as routing domain, rather than as search domain, in order to not have it affect local resolution of + single-label names.</para> + + <para>When set to true, this setting corresponds to the <option>domain</option> option in <citerefentry + project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UseRoutes=</varname></term> + <listitem> + <para>When true (the default), the static routes will be + requested from the DHCP server and added to the routing + table with a metric of 1024.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>UseTimezone=</varname></term> + + <listitem><para>When true, the timezone received from the + DHCP server will be set as timezone of the local + system. Defaults to <literal>no</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CriticalConnection=</varname></term> + <listitem> + <para>When true, the connection will never be torn down + even if the DHCP lease expires. This is contrary to the + DHCP specification, but may be the best choice if, say, + the root filesystem relies on this connection. Defaults to + false.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ClientIdentifier=</varname></term> + <listitem> + <para>The DHCPv4 client identifier to use. Either <literal>mac</literal> to use the MAC address of the link + or <literal>duid</literal> (the default, see below) to use an RFC4361-compliant Client ID.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>VendorClassIdentifier=</varname></term> + <listitem> + <para>The vendor class identifier used to identify vendor + type and configuration.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>DUIDType=</varname></term> + <listitem> + <para>Override the global <varname>DUIDType</varname> setting for this network. See + <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for a description of possible values.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>DUIDRawData=</varname></term> + <listitem> + <para>Override the global <varname>DUIDRawData</varname> setting for this network. See + <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for a description of possible values.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IAID=</varname></term> + <listitem> + <para>The DHCP Identity Association Identifier (IAID) for the interface, a 32-bit unsigned integer.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>RequestBroadcast=</varname></term> + <listitem> + <para>Request the server to use broadcast messages before + the IP address has been configured. This is necessary for + devices that cannot receive RAW packets, or that cannot + receive packets at all before an IP address has been + configured. On the other hand, this must not be enabled on + networks where broadcasts are filtered out.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>RouteMetric=</varname></term> + <listitem> + <para>Set the routing metric for routes specified by the + DHCP server.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>RouteTable=<replaceable>num</replaceable></varname></term> + <listitem> + <para>The table identifier for DHCP routes (a number between 1 and 4294967295, or 0 to unset). + The table can be retrieved using <command>ip route show table <replaceable>num</replaceable></command>. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[IPv6AcceptRA] Section Options</title> + <para>The <literal>[IPv6AcceptRA]</literal> section configures the IPv6 Router Advertisement + (RA) client, if it is enabled with the <varname>IPv6AcceptRA=</varname> setting described + above:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>UseDNS=</varname></term> + <listitem> + <para>When true (the default), the DNS servers received in the Router Advertisement will be used and take + precedence over any statically configured ones.</para> + + <para>This corresponds to the <option>nameserver</option> option in <citerefentry + project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>UseDomains=</varname></term> + <listitem> + <para>Takes a boolean argument, or the special value <literal>route</literal>. When true, the domain name + received via IPv6 Router Advertisement (RA) will be used as DNS search domain over this link, similar to + the effect of the <option>Domains=</option> setting. If set to <literal>route</literal>, the domain name + received via IPv6 RA will be used for routing DNS queries only, but not for searching, similar to the + effect of the <option>Domains=</option> setting when the argument is prefixed with + <literal>~</literal>. Defaults to false.</para> + + <para>It is recommended to enable this option only on trusted networks, as setting this affects resolution + of all host names, in particular of single-label names. It is generally safer to use the supplied domain + only as routing domain, rather than as search domain, in order to not have it affect local resolution of + single-label names.</para> + + <para>When set to true, this setting corresponds to the <option>domain</option> option in <citerefentry + project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>RouteTable=<replaceable>num</replaceable></varname></term> + <listitem> + <para>The table identifier for the routes received in the Router Advertisement + (a number between 1 and 4294967295, or 0 to unset). + The table can be retrieved using <command>ip route show table <replaceable>num</replaceable></command>. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + + <refsect1> + <title>[DHCPServer] Section Options</title> + <para>The <literal>[DHCPServer]</literal> section contains + settings for the DHCP server, if enabled via the + <varname>DHCPServer=</varname> option described above:</para> + + <variablelist class='network-directives'> + + <varlistentry> + <term><varname>PoolOffset=</varname></term> + <term><varname>PoolSize=</varname></term> + + <listitem><para>Configures the pool of addresses to hand out. The pool + is a contiguous sequence of IP addresses in the subnet configured for + the server address, which does not include the subnet nor the broadcast + address. <varname>PoolOffset=</varname> takes the offset of the pool + from the start of subnet, or zero to use the default value. + <varname>PoolSize=</varname> takes the number of IP addresses in the + pool or zero to use the default value. By default, the pool starts at + the first address after the subnet address and takes up the rest of + the subnet, excluding the broadcast address. If the pool includes + the server address (the default), this is reserved and not handed + out to clients.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultLeaseTimeSec=</varname></term> + <term><varname>MaxLeaseTimeSec=</varname></term> + + <listitem><para>Control the default and maximum DHCP lease + time to pass to clients. These settings take time values in seconds or + another common time unit, depending on the suffix. The default + lease time is used for clients that did not ask for a specific + lease time. If a client asks for a lease time longer than the + maximum lease time, it is automatically shortened to the + specified time. The default lease time defaults to 1h, the + maximum lease time to 12h. Shorter lease times are beneficial + if the configuration data in DHCP leases changes frequently + and clients shall learn the new settings with shorter + latencies. Longer lease times reduce the generated DHCP + network traffic.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>EmitDNS=</varname></term> + <term><varname>DNS=</varname></term> + + <listitem><para>Configures whether the DHCP leases handed out + to clients shall contain DNS server information. The + <varname>EmitDNS=</varname> setting takes a boolean argument + and defaults to <literal>yes</literal>. The DNS servers to + pass to clients may be configured with the + <varname>DNS=</varname> option, which takes a list of IPv4 + addresses. If the <varname>EmitDNS=</varname> option is + enabled but no servers configured, the servers are + automatically propagated from an "uplink" interface that has + appropriate servers set. The "uplink" interface is determined + by the default route of the system with the highest + priority. Note that this information is acquired at the time + the lease is handed out, and does not take uplink interfaces + into account that acquire DNS or NTP server information at a + later point. DNS server propagation does not take + <filename>/etc/resolv.conf</filename> into account. Also, note + that the leases are not refreshed if the uplink network + configuration changes. To ensure clients regularly acquire the + most current uplink DNS server information, it is thus + advisable to shorten the DHCP lease time via + <varname>MaxLeaseTimeSec=</varname> described + above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>EmitNTP=</varname></term> + <term><varname>NTP=</varname></term> + + <listitem><para>Similar to the <varname>EmitDNS=</varname> and + <varname>DNS=</varname> settings described above, these + settings configure whether and what NTP server information + shall be emitted as part of the DHCP lease. The same syntax, + propagation semantics and defaults apply as for + <varname>EmitDNS=</varname> and + <varname>DNS=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>EmitRouter=</varname></term> + + <listitem><para>Similar to the <varname>EmitDNS=</varname> + setting described above, this setting configures whether the + DHCP lease should contain the router option. The same syntax, + propagation semantics and defaults apply as for + <varname>EmitDNS=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>EmitTimezone=</varname></term> + <term><varname>Timezone=</varname></term> + + <listitem><para>Configures whether the DHCP leases handed out + to clients shall contain timezone information. The + <varname>EmitTimezone=</varname> setting takes a boolean + argument and defaults to <literal>yes</literal>. The + <varname>Timezone=</varname> setting takes a timezone string + (such as <literal>Europe/Berlin</literal> or + <literal>UTC</literal>) to pass to clients. If no explicit + timezone is set, the system timezone of the local host is + propagated, as determined by the + <filename>/etc/localtime</filename> symlink.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>[Bridge] Section Options</title> + <para>The <literal>[Bridge]</literal> section accepts the + following keys.</para> + <variablelist class='network-directives'> + <varlistentry> + <term><varname>UnicastFlood=</varname></term> + <listitem> + <para>A boolean. Controls whether the bridge should flood + traffic for which an FDB entry is missing and the destination + is unknown through this port. Defaults to on. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>HairPin=</varname></term> + <listitem> + <para>A boolean. Configures whether traffic may be sent back + out of the port on which it was received. By default, this + flag is false, and the bridge will not forward traffic back + out of the receiving port.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UseBPDU=</varname></term> + <listitem> + <para>A boolean. Configures whether STP Bridge Protocol Data Units will be + processed by the bridge port. Defaults to yes.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>FastLeave=</varname></term> + <listitem> + <para>A boolean. This flag allows the bridge to immediately stop multicast + traffic on a port that receives an IGMP Leave message. It is only used with + IGMP snooping if enabled on the bridge. Defaults to off.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>AllowPortToBeRoot=</varname></term> + <listitem> + <para>A boolean. Configures whether a given port is allowed to + become a root port. Only used when STP is enabled on the bridge. + Defaults to on.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Cost=</varname></term> + <listitem> + <para>Sets the "cost" of sending packets of this interface. + Each port in a bridge may have a different speed and the cost + is used to decide which link to use. Faster interfaces + should have lower costs.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>[BridgeFDB] Section Options</title> + <para>The <literal>[BridgeFDB]</literal> section manages the + forwarding database table of a port and accepts the following + keys. Specify several <literal>[BridgeFDB]</literal> sections to + configure several static MAC table entries.</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>As in the <literal>[Network]</literal> section. This + key is mandatory.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>VLANId=</varname></term> + <listitem> + <para>The VLAN ID for the new static MAC table entry. If + omitted, no VLAN ID info is appended to the new static MAC + table entry.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>[BridgeVLAN] Section Options</title> + <para>The <literal>[BridgeVLAN]</literal> section manages the VLAN ID configuration of a bridge port and accepts + the following keys. Specify several <literal>[BridgeVLAN]</literal> sections to configure several VLAN entries. + The <varname>VLANFiltering=</varname> option has to be enabled, see <literal>[Bridge]</literal> section in + <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>VLAN=</varname></term> + <listitem> + <para>The VLAN ID allowed on the port. This can be either a single ID or a range M-N. VLAN IDs are valid + from 1 to 4094.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>EgressUntagged=</varname></term> + <listitem> + <para>The VLAN ID specified here will be used to untag frames on egress. Configuring + <varname>EgressUntagged=</varname> implicates the use of <varname>VLAN=</varname> above and will enable the + VLAN ID for ingress as well. This can be either a single ID or a range M-N.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>PVID=</varname></term> + <listitem> + <para>The Port VLAN ID specified here is assigned to all untagged frames at ingress. + <varname>PVID=</varname> can be used only once. Configuring <varname>PVID=</varname> implicates the use of + <varname>VLAN=</varname> above and will enable the VLAN ID for ingress as well.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/systemd/network/50-static.network</title> + + <programlisting>[Match] +Name=enp2s0 + +[Network] +Address=192.168.0.15/24 +Gateway=192.168.0.1</programlisting> + </example> + + <example> + <title>/etc/systemd/network/80-dhcp.network</title> + + <programlisting>[Match] +Name=en* + +[Network] +DHCP=yes</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-bridge-static.network</title> + + <programlisting>[Match] +Name=bridge0 + +[Network] +Address=192.168.0.15/24 +Gateway=192.168.0.1 +DNS=192.168.0.1</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-bridge-slave-interface.network</title> + + <programlisting>[Match] +Name=enp2s0 + +[Network] +Bridge=bridge0</programlisting> + </example> + <example> + <title>/etc/systemd/network/25-bridge-slave-interface-vlan.network</title> + + <programlisting>[Match] +Name=enp2s0 + +[Network] +Bridge=bridge0 + +[BridgeVLAN] +VLAN=1-32 +PVID=42 +EgressUntagged=42 + +[BridgeVLAN] +VLAN=100-200 + +[BridgeVLAN] +EgressUntagged=300-400</programlisting> + </example> + <example> + <title>/etc/systemd/network/25-ipip.network</title> + + <programlisting>[Match] +Name=em1 + +[Network] +Tunnel=ipip-tun</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-sit.network</title> + + <programlisting>[Match] +Name=em1 + +[Network] +Tunnel=sit-tun</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-gre.network</title> + + <programlisting>[Match] +Name=em1 + +[Network] +Tunnel=gre-tun</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-vti.network</title> + + <programlisting>[Match] +Name=em1 + +[Network] +Tunnel=vti-tun</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-bond.network</title> + + <programlisting>[Match] +Name=bond1 + +[Network] +DHCP=yes +</programlisting> + </example> + + <example> + <title>/etc/systemd/network/25-vrf.network</title> + <para>Add the bond1 interface to the VRF master interface vrf-test. This will redirect routes generated on this interface to be within the routing table defined during VRF creation. Traffic won't be redirected towards the VRFs routing table unless specific ip-rules are added.</para> + <programlisting>[Match] +Name=bond1 + +[Network] +VRF=vrf-test +</programlisting> + </example> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.nspawn.xml b/src/grp-system/systemd/systemd.nspawn.xml new file mode 100644 index 0000000000..b1344d6c10 --- /dev/null +++ b/src/grp-system/systemd/systemd.nspawn.xml @@ -0,0 +1,463 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.nspawn"> + + <refentryinfo> + <title>systemd.nspawn</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.nspawn</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.nspawn</refname> + <refpurpose>Container settings</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></para> + <para><filename>/run/systemd/nspawn/<replaceable>machine</replaceable>.nspawn</filename></para> + <para><filename>/var/lib/machines/<replaceable>machine</replaceable>.nspawn</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>An nspawn container settings file (suffix + <filename>.nspawn</filename>) encodes additional runtime + information about a local container, and is searched, read and + used by + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + when starting a container. Files of this type are named after the + containers they define settings for. They are optional, and only + required for containers whose execution environment shall differ + from the defaults. Files of this type mostly contain settings that + may also be set on the <command>systemd-nspawn</command> command + line, and make it easier to persistently attach specific settings + to specific containers. The syntax of these files is inspired by + <filename>.desktop</filename> files following the <ulink + url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG + Desktop Entry Specification</ulink>, which in turn are inspired by + Microsoft Windows <filename>.ini</filename> files.</para> + + <para>Boolean arguments used in these settings files can be + written in various formats. For positive settings, the strings + <option>1</option>, <option>yes</option>, <option>true</option> + and <option>on</option> are equivalent. For negative settings, the + strings <option>0</option>, <option>no</option>, + <option>false</option> and <option>off</option> are + equivalent.</para> + + <para>Empty lines and lines starting with # or ; are + ignored. This may be used for commenting. Lines ending + in a backslash are concatenated with the following + line while reading and the backslash is replaced by a + space character. This may be used to wrap long lines.</para> + + </refsect1> + + <refsect1> + <title><filename>.nspawn</filename> File Discovery</title> + + <para>Files are searched by appending the + <filename>.nspawn</filename> suffix to the machine name of the + container, as specified with the <option>--machine=</option> + switch of <command>systemd-nspawn</command>, or derived from the + directory or image file name. This file is first searched in + <filename>/etc/systemd/nspawn/</filename> and + <filename>/run/systemd/nspawn/</filename>. If found in these + directories, its settings are read and all of them take full effect + (but are possibly overridden by corresponding command line + arguments). If not found, the file will then be searched next to + the image file or in the immediate parent of the root directory of + the container. If the file is found there, only a subset of the + settings will take effect however. All settings that possibly + elevate privileges or grant additional access to resources of the + host (such as files or directories) are ignored. To which options + this applies is documented below.</para> + + <para>Persistent settings files created and maintained by the + administrator (and thus trusted) should be placed in + <filename>/etc/systemd/nspawn/</filename>, while automatically + downloaded (and thus potentially untrusted) settings files are + placed in <filename>/var/lib/machines/</filename> instead (next to + the container images), where their security impact is limited. In + order to add privileged settings to <filename>.nspawn</filename> + files acquired from the image vendor, it is recommended to copy the + settings files into <filename>/etc/systemd/nspawn/</filename> and + edit them there, so that the privileged options become + available. The precise algorithm for how the files are searched and + interpreted may be configured with + <command>systemd-nspawn</command>'s <option>--settings=</option> + switch, see + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details.</para> + </refsect1> + + <refsect1> + <title>[Exec] Section Options</title> + + <para>Settings files may include an <literal>[Exec]</literal> + section, which carries various execution parameters:</para> + + <variablelist> + + <varlistentry> + <term><varname>Boot=</varname></term> + + <listitem><para>Takes a boolean argument, which defaults to off. If enabled, <command>systemd-nspawn</command> + will automatically search for an <filename>init</filename> executable and invoke it. In this case, the + specified parameters using <varname>Parameters=</varname> are passed as additional arguments to the + <filename>init</filename> process. This setting corresponds to the <option>--boot</option> switch on the + <command>systemd-nspawn</command> command line. This option may not be combined with + <varname>ProcessTwo=yes</varname>. This option is the default if the + <filename>systemd-nspawn@.service</filename> template unit file is used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProcessTwo=</varname></term> + + <listitem><para>Takes a boolean argument, which defaults to off. If enabled, the specified program is run as + PID 2. A stub init process is run as PID 1. This setting corresponds to the <option>--as-pid2</option> switch + on the <command>systemd-nspawn</command> command line. This option may not be combined with + <varname>Boot=yes</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Parameters=</varname></term> + + <listitem><para>Takes a space-separated list of + arguments. This is either a command line, beginning with the + binary name to execute, or – if <varname>Boot=</varname> is + enabled – the list of arguments to pass to the init + process. This setting corresponds to the command line + parameters passed on the <command>systemd-nspawn</command> + command line.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Environment=</varname></term> + + <listitem><para>Takes an environment variable assignment + consisting of key and value, separated by + <literal>=</literal>. Sets an environment variable for the + main process invoked in the container. This setting may be + used multiple times to set multiple environment variables. It + corresponds to the <option>--setenv=</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>User=</varname></term> + + <listitem><para>Takes a UNIX user name. Specifies the user + name to invoke the main process of the container as. This user + must be known in the container's user database. This + corresponds to the <option>--user=</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>WorkingDirectory=</varname></term> + + <listitem><para>Selects the working directory for the process invoked in the container. Expects an absolute + path in the container's file system namespace. This corresponds to the <option>--chdir=</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Capability=</varname></term> + <term><varname>DropCapability=</varname></term> + + <listitem><para>Takes a space-separated list of Linux process + capabilities (see + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). The <varname>Capability=</varname> setting + specifies additional capabilities to pass on top of the + default set of capabilities. The + <varname>DropCapability=</varname> setting specifies + capabilities to drop from the default set. These settings + correspond to the <option>--capability=</option> and + <option>--drop-capability=</option> command line + switches. Note that <varname>Capability=</varname> is a + privileged setting, and only takes effect in + <filename>.nspawn</filename> files in + <filename>/etc/systemd/nspawn/</filename> and + <filename>/run/system/nspawn/</filename> (see above). On the + other hand, <varname>DropCapability=</varname> takes effect in + all cases.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillSignal=</varname></term> + + <listitem><para>Specify the process signal to send to the + container's PID 1 when nspawn itself receives SIGTERM, in + order to trigger an orderly shutdown of the container. + Defaults to SIGRTMIN+3 if <option>Boot=</option> is used + (on systemd-compatible init systems SIGRTMIN+3 triggers an + orderly shutdown). For a list of valid signals, see + <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Personality=</varname></term> + + <listitem><para>Configures the kernel personality for the + container. This is equivalent to the + <option>--personality=</option> switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MachineID=</varname></term> + + <listitem><para>Configures the 128-bit machine ID (UUID) to pass to + the container. This is equivalent to the + <option>--uuid=</option> command line switch. This option is + privileged (see above). </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PrivateUsers=</varname></term> + + <listitem><para>Configures support for usernamespacing. This is equivalent to the + <option>--private-users=</option> command line switch, and takes the same options. This option is privileged + (see above). This option is the default if the <filename>systemd-nspawn@.service</filename> template unit file + is used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>NotifyReady=</varname></term> + + <listitem><para>Configures support for notifications from the container's init process. + This is equivalent to use <option>--notify-ready=</option> command line switch, + and takes the same options. See <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details about the specific options supported.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[Files] Section Options</title> + + <para>Settings files may include a <literal>[Files]</literal> + section, which carries various parameters configuring the file + system of the container:</para> + + <variablelist> + + <varlistentry> + <term><varname>ReadOnly=</varname></term> + + <listitem><para>Takes a boolean argument, which defaults to off. If + specified, the container will be run with a read-only file + system. This setting corresponds to the + <option>--read-only</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Volatile=</varname></term> + + <listitem><para>Takes a boolean argument, or the special value + <literal>state</literal>. This configures whether to run the + container with volatile state and/or configuration. This + option is equivalent to <option>--volatile=</option>, see + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details about the specific options + supported.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Bind=</varname></term> + <term><varname>BindReadOnly=</varname></term> + + <listitem><para>Adds a bind mount from the host into the + container. Takes a single path, a pair of two paths separated + by a colon, or a triplet of two paths plus an option string + separated by colons. This option may be used multiple times to + configure multiple bind mounts. This option is equivalent to + the command line switches <option>--bind=</option> and + <option>--bind-ro=</option>, see + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details about the specific options supported. This setting + is privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TemporaryFileSystem=</varname></term> + + <listitem><para>Adds a <literal>tmpfs</literal> mount to the + container. Takes a path or a pair of path and option string, + separated by a colon. This option may be used multiple times to + configure multiple <literal>tmpfs</literal> mounts. This + option is equivalent to the command line switch + <option>--tmpfs=</option>, see + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details about the specific options supported. This setting + is privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PrivateUsersChown=</varname></term> + + <listitem><para>Configures whether the ownership of the files and directories in the container tree shall be + adjusted to the UID/GID range used, if necessary and user namespacing is enabled. This is equivalent to the + <option>--private-users-chown</option> command line switch. This option is privileged (see + above). </para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>[Network] Section Options</title> + + <para>Settings files may include a <literal>[Network]</literal> + section, which carries various parameters configuring the network + connectivity of the container:</para> + + <variablelist> + + <varlistentry> + <term><varname>Private=</varname></term> + + <listitem><para>Takes a boolean argument, which defaults to off. If + enabled, the container will run in its own network namespace + and not share network interfaces and configuration with the + host. This setting corresponds to the + <option>--private-network</option> command line + switch.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VirtualEthernet=</varname></term> + + <listitem><para>Takes a boolean argument. Configures whether to create a virtual Ethernet connection + (<literal>veth</literal>) between host and the container. This setting implies + <varname>Private=yes</varname>. This setting corresponds to the <option>--network-veth</option> command line + switch. This option is privileged (see above). This option is the default if the + <filename>systemd-nspawn@.service</filename> template unit file is used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VirtualEthernetExtra=</varname></term> + + <listitem><para>Takes a colon-separated pair of interface + names. Configures an additional virtual Ethernet connection + (<literal>veth</literal>) between host and the container. The + first specified name is the interface name on the host, the + second the interface name in the container. The latter may be + omitted in which case it is set to the same name as the host + side interface. This setting implies + <varname>Private=yes</varname>. This setting corresponds to + the <option>--network-veth-extra=</option> command line + switch, and maybe be used multiple times. It is independent of + <varname>VirtualEthernet=</varname>. This option is privileged + (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Interface=</varname></term> + + <listitem><para>Takes a space-separated list of interfaces to + add to the container. This option corresponds to the + <option>--network-interface=</option> command line switch and + implies <varname>Private=yes</varname>. This option is + privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MACVLAN=</varname></term> + <term><varname>IPVLAN=</varname></term> + + <listitem><para>Takes a space-separated list of interfaces to + add MACLVAN or IPVLAN interfaces to, which are then added to + the container. These options correspond to the + <option>--network-macvlan=</option> and + <option>--network-ipvlan=</option> command line switches and + imply <varname>Private=yes</varname>. These options are + privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Bridge=</varname></term> + + <listitem><para>Takes an interface name. This setting implies + <varname>VirtualEthernet=yes</varname> and + <varname>Private=yes</varname> and has the effect that the + host side of the created virtual Ethernet link is connected to + the specified bridge interface. This option corresponds to the + <option>--network-bridge=</option> command line switch. This + option is privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Zone=</varname></term> + + <listitem><para>Takes a network zone name. This setting implies <varname>VirtualEthernet=yes</varname> and + <varname>Private=yes</varname> and has the effect that the host side of the created virtual Ethernet link is + connected to an automatically managed bridge interface named after the passed argument, prefixed with + <literal>vz-</literal>. This option corresponds to the <option>--network-zone=</option> command line + switch. This option is privileged (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Port=</varname></term> + + <listitem><para>Exposes a TCP or UDP port of the container on + the host. This option corresponds to the + <option>--port=</option> command line switch, see + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for the precise syntax of the argument this option takes. This + option is privileged (see above).</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.offline-updates.xml b/src/grp-system/systemd/systemd.offline-updates.xml new file mode 100644 index 0000000000..07a5225512 --- /dev/null +++ b/src/grp-system/systemd/systemd.offline-updates.xml @@ -0,0 +1,169 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2013 Lennart Poettering + Copyright 2016 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.offline-updates"> + <refentryinfo> + <title>systemd.offline-updates</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.offline-updates</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.offline-updates</refname> + <refpurpose>Implementation of offline updates in systemd</refpurpose> + </refnamediv> + + <refsect1> + <title>Implementing Offline System Updates</title> + + <para>This man page describes how to implement "offline" system updates with systemd. By "offline" + OS updates we mean package installations and updates that are run with the system booted into a + special system update mode, in order to avoid problems related to conflicts of libraries and + services that are currently running with those on disk. This document is inspired by this + <ulink url="https://wiki.gnome.org/Design/OS/SoftwareUpdates">GNOME design whiteboard</ulink>. + </para> + + <para>The logic:</para> + + <orderedlist> + <listitem> + <para>The package manager prepares system updates by downloading all (RPM or DEB or + whatever) packages to update off-line in a special directory + <filename noindex="true">/var/lib/system-update</filename> (or + another directory of the package/upgrade manager's choice).</para> + </listitem> + + <listitem> + <para>When the user OK'ed the update, the symlink <filename>/system-update</filename> is + created that points to <filename noindex="true">/var/lib/system-update</filename> (or + wherever the directory with the upgrade files is located) and the system is rebooted. This + symlink is in the root directory, since we need to check for it very early at boot, at a + time where <filename>/var</filename> is not available yet.</para> + </listitem> + + <listitem> + <para>Very early in the new boot + <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + checks whether <filename>/system-update</filename> exists. If so, it (temporarily and for + this boot only) redirects (i.e. symlinks) <filename>default.target</filename> to + <filename>system-update.target</filename>, a special target that is pulls in the base system + (i.e. <filename>sysinit.target</filename>, so that all file systems are mounted but little + else) and the system update units.</para> + </listitem> + + <listitem> + <para>The system now continues to boot into <filename>default.target</filename>, and thus + into <filename>system-update.target</filename>. This target pulls in the system update unit, + which starts the system update script after all file systems have been mounted.</para> + </listitem> + + <listitem> + <para>As the first step, the update script should check if the + <filename>/system-update</filename> symlink points to the location used by that update + script. In case it does not exists or points to a different location, the script must exit + without error. It is possible for multiple update services to be installed, and for multiple + update scripts to be launched in parallel, and only the one that corresponds to the tool + that <emphasis>created</emphasis> the symlink before reboot should perform any actions. It + is unsafe to run multiple updates in parallel.</para> + </listitem> + + <listitem> + <para>The update script should now do its job. If applicable and possible, it should + create a file system snapshot, then install all packages. + After completion (regardless whether the update succeeded or failed) the machine + must be rebooted, for example by calling <command>systemctl reboot</command>. + In addition, on failure the script should revert to the old file system snapshot + (without the symlink).</para> + </listitem> + + <listitem> + <para>The system is rebooted. Since the <filename>/system-update</filename> symlink is gone, + the generator won't redirect <filename>default.target</filename> after reboot and the + system now boots into the default target again.</para> + </listitem> + </orderedlist> + </refsect1> + + <refsect1> + <title>Recommendations</title> + + <orderedlist> + <listitem> + <para>To make things a bit more robust we recommend hooking the update script into + <filename>system-update.target</filename> via a <filename noindex='true'>.wants/</filename> + symlink in the distribution package, rather than depending on <command>systemctl + enable</command> in the postinst scriptlets of your package. More specifically, for your + update script create a .service file, without [Install] section, and then add a symlink like + <filename noindex='true'>/usr/lib/systemd/system-update.target.wants/foobar.service</filename> + → <filename noindex='true'>../foobar.service</filename> to your package.</para> + </listitem> + + <listitem> + <para>Make sure to remove the <filename>/system-update</filename> symlink as early as + possible in the update script to avoid reboot loops in case the update fails.</para> + </listitem> + + <listitem> + <para>Use <varname>FailureAction=reboot</varname> in the service file for your update script + to ensure that a reboot is automatically triggered if the update fails. + <varname>FailureAction=</varname> makes sure that the specified unit is activated if your + script exits uncleanly (by non-zero error code, or signal/coredump). If your script succeeds + you should trigger the reboot in your own code, for example by invoking logind's + <command>Reboot()</command> call or calling <command>systemctl reboot</command>. See + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/logind">logind dbus API</ulink> + for details.</para> + </listitem> + + <listitem> + <para>The update service should declare <varname>DefaultDependencies=false</varname>, + and pull in any services it requires explicitly.</para> + </listitem> + </orderedlist> + </refsect1> + + <refsect1> + <title>See also</title> + + <para> + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates/">Implementing Offline System Updates</ulink>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='mankier'><refentrytitle>dnf.plugin.system-upgrade</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> +</refentry> diff --git a/src/grp-system/systemd/systemd.path.xml b/src/grp-system/systemd/systemd.path.xml new file mode 100644 index 0000000000..7200c8fe27 --- /dev/null +++ b/src/grp-system/systemd/systemd.path.xml @@ -0,0 +1,202 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.path"> + <refentryinfo> + <title>systemd.path</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.path</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.path</refname> + <refpurpose>Path unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>path</replaceable>.path</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.path</literal> encodes information about a path + monitored by systemd, for path-based activation.</para> + + <para>This man page lists the configuration options specific to + this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic [Unit] and + [Install] sections. The path specific configuration options are + configured in the [Path] section.</para> + + <para>For each path file, a matching unit file must exist, + describing the unit to activate when the path changes. By default, + a service by the same name as the path (except for the suffix) is + activated. Example: a path file <filename>foo.path</filename> + activates a matching service <filename>foo.service</filename>. The + unit to activate may be controlled by <varname>Unit=</varname> + (see below).</para> + + <para>Internally, path units use the + <citerefentry project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> + API to monitor file systems. Due to that, it suffers by the same + limitations as inotify, and for example cannot be used to monitor + files or directories changed by other machines on remote NFS file + systems.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>If a path unit is beneath another mount unit in the file + system hierarchy, both a requirement and an ordering dependency + between both units are created automatically.</para> + + <para>An implicit <varname>Before=</varname> dependency is added + between a path unit and the unit it is supposed to activate.</para> + + <para>Unless <varname>DefaultDependencies=false</varname> in the <literal>[Unit]</literal> section is used, path + units will implicitly have dependencies of type <varname>Before=</varname> on <filename>paths.target</filename>, + dependencies of type <varname>After=</varname> and <varname>Requires=</varname> on + <filename>sysinit.target</filename>, and have dependencies of type <varname>Conflicts=</varname> and + <varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure that path units are terminated + cleanly prior to system shutdown. Only path units involved with early boot or late system shutdown should disable + this option. + </para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Path files must include a [Path] section, which carries + information about the path(s) it monitors. The options specific to + the [Path] section of path units are the following:</para> + + <variablelist class='unit-directives'> + <varlistentry> + <term><varname>PathExists=</varname></term> + <term><varname>PathExistsGlob=</varname></term> + <term><varname>PathChanged=</varname></term> + <term><varname>PathModified=</varname></term> + <term><varname>DirectoryNotEmpty=</varname></term> + + <listitem><para>Defines paths to monitor for certain changes: + <varname>PathExists=</varname> may be used to watch the mere + existence of a file or directory. If the file specified + exists, the configured unit is activated. + <varname>PathExistsGlob=</varname> works similar, but checks + for the existence of at least one file matching the globbing + pattern specified. <varname>PathChanged=</varname> may be used + to watch a file or directory and activate the configured unit + whenever it changes. It is not activated on every write to the + watched file but it is activated if the file which was open + for writing gets closed. <varname>PathModified=</varname> is + similar, but additionally it is activated also on simple + writes to the watched file. + <varname>DirectoryNotEmpty=</varname> may be used to watch a + directory and activate the configured unit whenever it + contains at least one file.</para> + + <para>The arguments of these directives must be absolute file + system paths.</para> + + <para>Multiple directives may be combined, of the same and of + different types, to watch multiple paths. If the empty string + is assigned to any of these options, the list of paths to + watch is reset, and any prior assignments of these options + will not have any effect.</para> + + <para>If a path already exists (in case of + <varname>PathExists=</varname> and + <varname>PathExistsGlob=</varname>) or a directory already is + not empty (in case of <varname>DirectoryNotEmpty=</varname>) + at the time the path unit is activated, then the configured + unit is immediately activated as well. Something similar does + not apply to <varname>PathChanged=</varname> and + <varname>PathModified=</varname>.</para> + + <para>If the path itself or any of the containing directories + are not accessible, <command>systemd</command> will watch for + permission changes and notice that conditions are satisfied + when permissions allow that. </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>Unit=</varname></term> + + <listitem><para>The unit to activate when any of the + configured paths changes. The argument is a unit name, whose + suffix is not <literal>.path</literal>. If not specified, this + value defaults to a service that has the same name as the path + unit, except for the suffix. (See above.) It is recommended + that the unit name that is activated and the unit name of the + path unit are named identical, except for the + suffix.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>MakeDirectory=</varname></term> + + <listitem><para>Takes a boolean argument. If true, the + directories to watch are created before watching. This option + is ignored for <varname>PathExists=</varname> settings. + Defaults to <option>false</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>DirectoryMode=</varname></term> + + <listitem><para>If <varname>MakeDirectory=</varname> is + enabled, use the mode specified here to create the directories + in question. Takes an access mode in octal notation. Defaults + to <option>0755</option>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.pc.in b/src/grp-system/systemd/systemd.pc.in new file mode 100644 index 0000000000..ac52b30dd3 --- /dev/null +++ b/src/grp-system/systemd/systemd.pc.in @@ -0,0 +1,34 @@ +# This file is part of systemd. +# +# systemd is free software; you can redistribute it and/or modify it +# under the terms of the GNU Lesser General Public License as published by +# the Free Software Foundation; either version 2.1 of the License, or +# (at your option) any later version. + +prefix=@prefix@ +systemdutildir=@rootlibexecdir@ +systemdsystemunitdir=@systemunitdir@ +systemdsystempresetdir=@systempresetdir@ +systemduserunitdir=@userunitdir@ +systemduserpresetdir=@userpresetdir@ +systemdsystemconfdir=@pkgsysconfdir@/system +systemduserconfdir=@pkgsysconfdir@/user +systemdsystemunitpath=${systemdsystemconfdir}:/etc/systemd/system:/run/systemd/system:/usr/local/lib/systemd/system:${systemdsystemunitdir}:/usr/lib/systemd/system:/lib/systemd/system +systemduserunitpath=${systemduserconfdir}:/etc/systemd/user:/run/systemd/user:/usr/local/lib/systemd/user:/usr/local/share/systemd/user:${systemduserunitdir}:/usr/lib/systemd/user:/usr/share/systemd/user +systemdsystemgeneratordir=@systemgeneratordir@ +systemdusergeneratordir=@usergeneratordir@ +systemdsleepdir=@systemsleepdir@ +systemdshutdowndir=@systemshutdowndir@ +tmpfilesdir=@tmpfilesdir@ +sysusersdir=@sysusersdir@ +sysctldir=@sysctldir@ +binfmtdir=@binfmtdir@ +modulesloaddir=@modulesloaddir@ +catalogdir=@catalogdir@ +systemuidmax=@systemuidmax@ +systemgidmax=@systemgidmax@ + +Name: systemd +Description: systemd System and Service Manager +URL: @PACKAGE_URL@ +Version: @PACKAGE_VERSION@ diff --git a/src/grp-system/systemd/systemd.resource-control.xml b/src/grp-system/systemd/systemd.resource-control.xml new file mode 100644 index 0000000000..02878b28a0 --- /dev/null +++ b/src/grp-system/systemd/systemd.resource-control.xml @@ -0,0 +1,767 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2013 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.resource-control"> + <refentryinfo> + <title>systemd.resource-control</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.resource-control</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.resource-control</refname> + <refpurpose>Resource control unit settings</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para> + <filename><replaceable>slice</replaceable>.slice</filename>, + <filename><replaceable>scope</replaceable>.scope</filename>, + <filename><replaceable>service</replaceable>.service</filename>, + <filename><replaceable>socket</replaceable>.socket</filename>, + <filename><replaceable>mount</replaceable>.mount</filename>, + <filename><replaceable>swap</replaceable>.swap</filename> + </para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Unit configuration files for services, slices, scopes, sockets, mount points, and swap devices share a subset + of configuration options for resource control of spawned processes. Internally, this relies on the Linux Control + Groups (cgroups) kernel concept for organizing processes in a hierarchical tree of named groups for the purpose of + resource management.</para> + + <para>This man page lists the configuration options shared by + those six unit types. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files, and + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + and + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information on the specific unit configuration files. The + resource control configuration options are configured in the + [Slice], [Scope], [Service], [Socket], [Mount], or [Swap] + sections, depending on the unit type.</para> + + <para>In addition, options which control resources available to programs + <emphasis>executed</emphasis> by systemd are listed in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Those options complement options listed here.</para> + + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New + Control Group Interfaces</ulink> for an introduction on how to make + use of resource control APIs from programs.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>Units with the <varname>Slice=</varname> setting set automatically acquire <varname>Requires=</varname> and + <varname>After=</varname> dependencies on the specified slice unit.</para> + </refsect1> + + <refsect1> + <title>Unified and Legacy Control Group Hierarchies</title> + + <para>The unified control group hierarchy is the new version of kernel control group interface, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. Depending on the resource type, + there are differences in resource control capabilities. Also, because of interface changes, some resource types + have separate set of options on the unified hierarchy.</para> + + <para> + <variablelist> + + <varlistentry> + <term><option>CPU</option></term> + <listitem> + <para>Due to the lack of consensus in the kernel community, the CPU controller support on the unified + control group hierarchy requires out-of-tree kernel patches. See <ulink + url="https://git.kernel.org/cgit/linux/kernel/git/tj/cgroup.git/tree/Documentation/cgroup-v2-cpu.txt?h=cgroup-v2-cpu">cgroup-v2-cpu.txt</ulink>.</para> + + <para><varname>CPUWeight=</varname> and <varname>StartupCPUWeight=</varname> replace + <varname>CPUShares=</varname> and <varname>StartupCPUShares=</varname>, respectively.</para> + + <para>The <literal>cpuacct</literal> controller does not exist separately on the unified hierarchy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>Memory</option></term> + <listitem> + <para><varname>MemoryMax=</varname> replaces <varname>MemoryLimit=</varname>. <varname>MemoryLow=</varname> + and <varname>MemoryHigh=</varname> are effective only on unified hierarchy.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>IO</option></term> + <listitem> + <para><varname>IO</varname> prefixed settings are superset of and replace <varname>BlockIO</varname> + prefixed ones. On unified hierarchy, IO resource control also applies to buffered writes.</para> + </listitem> + </varlistentry> + + </variablelist> + </para> + + <para>To ease the transition, there is best-effort translation between the two versions of settings. For each + controller, if any of the settings for the unified hierarchy are present, all settings for the legacy hierarchy are + ignored. If the resulting settings are for the other type of hierarchy, the configurations are translated before + application.</para> + + <para>Legacy control group hierarchy (see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>), also called cgroup-v1, + doesn't allow safe delegation of controllers to unprivileged processes. If the system uses the legacy control group + hierarchy, resource control is disabled for systemd user instance, see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Units of the types listed above can have settings + for resource control configuration:</para> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>CPUAccounting=</varname></term> + + <listitem> + <para>Turn on CPU usage accounting for this unit. Takes a + boolean argument. Note that turning on CPU accounting for + one unit will also implicitly turn it on for all units + contained in the same slice and for all its parent slices + and the units contained therein. The system default for this + setting may be controlled with + <varname>DefaultCPUAccounting=</varname> in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUWeight=<replaceable>weight</replaceable></varname></term> + <term><varname>StartupCPUWeight=<replaceable>weight</replaceable></varname></term> + + <listitem> + <para>Assign the specified CPU time weight to the processes executed, if the unified control group hierarchy + is used on the system. These options take an integer value and control the <literal>cpu.weight</literal> + control group attribute. The allowed range is 1 to 10000. Defaults to 100. For details about this control + group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink> and <ulink + url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>. + The available CPU time is split up among all units within one slice relative to their CPU time weight.</para> + + <para>While <varname>StartupCPUWeight=</varname> only applies to the startup phase of the system, + <varname>CPUWeight=</varname> applies to normal runtime of the system, and if the former is not set also to + the startup phase. Using <varname>StartupCPUWeight=</varname> allows prioritizing specific services at + boot-up differently than during normal runtime.</para> + + <para>Implies <literal>CPUAccounting=true</literal>.</para> + + <para>These settings replace <varname>CPUShares=</varname> and <varname>StartupCPUShares=</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUQuota=</varname></term> + + <listitem> + <para>Assign the specified CPU time quota to the processes executed. Takes a percentage value, suffixed with + "%". The percentage specifies how much CPU time the unit shall get at maximum, relative to the total CPU time + available on one CPU. Use values > 100% for allotting CPU time on more than one CPU. This controls the + <literal>cpu.max</literal> attribute on the unified control group hierarchy and + <literal>cpu.cfs_quota_us</literal> on legacy. For details about these control group attributes, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink> and <ulink + url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>.</para> + + <para>Example: <varname>CPUQuota=20%</varname> ensures that the executed processes will never get more than + 20% CPU time on one CPU.</para> + + <para>Implies <literal>CPUAccounting=true</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MemoryAccounting=</varname></term> + + <listitem> + <para>Turn on process and kernel memory accounting for this + unit. Takes a boolean argument. Note that turning on memory + accounting for one unit will also implicitly turn it on for + all units contained in the same slice and for all its parent + slices and the units contained therein. The system default + for this setting may be controlled with + <varname>DefaultMemoryAccounting=</varname> in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MemoryLow=<replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Specify the best-effort memory usage protection of the executed processes in this unit. If the memory + usages of this unit and all its ancestors are below their low boundaries, this unit's memory won't be + reclaimed as long as memory can be reclaimed from unprotected units.</para> + + <para>Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is + parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a + percentage value may be specified, which is taken relative to the installed physical memory on the + system. This controls the <literal>memory.low</literal> control group attribute. For details about this + control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para> + + <para>Implies <literal>MemoryAccounting=true</literal>.</para> + + <para>This setting is supported only if the unified control group hierarchy is used and disables + <varname>MemoryLimit=</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MemoryHigh=<replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Specify the high limit on memory usage of the executed processes in this unit. Memory usage may go + above the limit if unavoidable, but the processes are heavily slowed down and memory is taken away + aggressively in such cases. This is the main mechanism to control memory usage of a unit.</para> + + <para>Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is + parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a + percentage value may be specified, which is taken relative to the installed physical memory on the + system. If assigned the + special value <literal>infinity</literal>, no memory limit is applied. This controls the + <literal>memory.high</literal> control group attribute. For details about this control group attribute, see + <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para> + + <para>Implies <literal>MemoryAccounting=true</literal>.</para> + + <para>This setting is supported only if the unified control group hierarchy is used and disables + <varname>MemoryLimit=</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MemoryMax=<replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Specify the absolute limit on memory usage of the executed processes in this unit. If memory usage + cannot be contained under the limit, out-of-memory killer is invoked inside the unit. It is recommended to + use <varname>MemoryHigh=</varname> as the main control mechanism and use <varname>MemoryMax=</varname> as the + last line of defense.</para> + + <para>Takes a memory size in bytes. If the value is suffixed with K, M, G or T, the specified memory size is + parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. Alternatively, a + percentage value may be specified, which is taken relative to the installed physical memory on the system. If + assigned the special value <literal>infinity</literal>, no memory limit is applied. This controls the + <literal>memory.max</literal> control group attribute. For details about this control group attribute, see + <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para> + + <para>Implies <literal>MemoryAccounting=true</literal>.</para> + + <para>This setting replaces <varname>MemoryLimit=</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MemorySwapMax=<replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Specify the absolute limit on swap usage of the executed processes in this unit.</para> + + <para>Takes a swap size in bytes. If the value is suffixed with K, M, G or T, the specified swap size is + parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes (with the base 1024), respectively. If assigned the + special value <literal>infinity</literal>, no swap limit is applied. This controls the + <literal>memory.swap.max</literal> control group attribute. For details about this control group attribute, + see <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para> + + <para>Implies <literal>MemoryAccounting=true</literal>.</para> + + <para>This setting is supported only if the unified control group hierarchy is used and disables + <varname>MemoryLimit=</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>TasksAccounting=</varname></term> + + <listitem> + <para>Turn on task accounting for this unit. Takes a + boolean argument. If enabled, the system manager will keep + track of the number of tasks in the unit. The number of + tasks accounted this way includes both kernel threads and + userspace processes, with each thread counting + individually. Note that turning on tasks accounting for one + unit will also implicitly turn it on for all units contained + in the same slice and for all its parent slices and the + units contained therein. The system default for this setting + may be controlled with + <varname>DefaultTasksAccounting=</varname> in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>TasksMax=<replaceable>N</replaceable></varname></term> + + <listitem> + <para>Specify the maximum number of tasks that may be created in the unit. This ensures that the number of + tasks accounted for the unit (see above) stays below a specific limit. This either takes an absolute number + of tasks or a percentage value that is taken relative to the configured maximum number of tasks on the + system. If assigned the special value <literal>infinity</literal>, no tasks limit is applied. This controls + the <literal>pids.max</literal> control group attribute. For details about this control group attribute, see + <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt">pids.txt</ulink>.</para> + + <para>Implies <literal>TasksAccounting=true</literal>. The + system default for this setting may be controlled with + <varname>DefaultTasksMax=</varname> in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOAccounting=</varname></term> + + <listitem> + <para>Turn on Block I/O accounting for this unit, if the unified control group hierarchy is used on the + system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly + turn it on for all units contained in the same slice and all for its parent slices and the units contained + therein. The system default for this setting may be controlled with <varname>DefaultIOAccounting=</varname> + in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>This setting replaces <varname>BlockIOAccounting=</varname> and disables settings prefixed with + <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOWeight=<replaceable>weight</replaceable></varname></term> + <term><varname>StartupIOWeight=<replaceable>weight</replaceable></varname></term> + + <listitem> + <para>Set the default overall block I/O weight for the executed processes, if the unified control group + hierarchy is used on the system. Takes a single weight value (between 1 and 10000) to set the default block + I/O weight. This controls the <literal>io.weight</literal> control group attribute, which defaults to + 100. For details about this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. The available I/O + bandwidth is split up among all units within one slice relative to their block I/O weight.</para> + + <para>While <varname>StartupIOWeight=</varname> only applies + to the startup phase of the system, + <varname>IOWeight=</varname> applies to the later runtime of + the system, and if the former is not set also to the startup + phase. This allows prioritizing specific services at boot-up + differently than during runtime.</para> + + <para>Implies <literal>IOAccounting=true</literal>.</para> + + <para>These settings replace <varname>BlockIOWeight=</varname> and <varname>StartupBlockIOWeight=</varname> + and disable settings prefixed with <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term> + + <listitem> + <para>Set the per-device overall block I/O weight for the executed processes, if the unified control group + hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify + the device specific weight value, between 1 and 10000. (Example: "/dev/sda 1000"). The file path may be + specified as path to a block device node or as any other file, in which case the backing block device of the + file system of the file is determined. This controls the <literal>io.weight</literal> control group + attribute, which defaults to 100. Use this option multiple times to set weights for multiple devices. For + details about this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>.</para> + + <para>Implies <literal>IOAccounting=true</literal>.</para> + + <para>This setting replaces <varname>BlockIODeviceWeight=</varname> and disables settings prefixed with + <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOReadBandwidthMax=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> + <term><varname>IOWriteBandwidthMax=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Set the per-device overall block I/O bandwidth maximum limit for the executed processes, if the unified + control group hierarchy is used on the system. This limit is not work-conserving and the executed processes + are not allowed to use more even if the device has idle capacity. Takes a space-separated pair of a file + path and a bandwidth value (in bytes per second) to specify the device specific bandwidth. The file path may + be a path to a block device node, or as any other file in which case the backing block device of the file + system of the file is used. If the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is + parsed as Kilobytes, Megabytes, Gigabytes, or Terabytes, respectively, to the base of 1000. (Example: + "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the <literal>io.max</literal> control + group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For details + about this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. + </para> + + <para>Implies <literal>IOAccounting=true</literal>.</para> + + <para>These settings replace <varname>BlockIOReadBandwidth=</varname> and + <varname>BlockIOWriteBandwidth=</varname> and disable settings prefixed with <varname>BlockIO</varname> or + <varname>StartupBlockIO</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOReadIOPSMax=<replaceable>device</replaceable> <replaceable>IOPS</replaceable></varname></term> + <term><varname>IOWriteIOPSMax=<replaceable>device</replaceable> <replaceable>IOPS</replaceable></varname></term> + + <listitem> + <para>Set the per-device overall block I/O IOs-Per-Second maximum limit for the executed processes, if the + unified control group hierarchy is used on the system. This limit is not work-conserving and the executed + processes are not allowed to use more even if the device has idle capacity. Takes a space-separated pair of + a file path and an IOPS value to specify the device specific IOPS. The file path may be a path to a block + device node, or as any other file in which case the backing block device of the file system of the file is + used. If the IOPS is suffixed with K, M, G, or T, the specified IOPS is parsed as KiloIOPS, MegaIOPS, + GigaIOPS, or TeraIOPS, respectively, to the base of 1000. (Example: + "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 1K"). This controls the <literal>io.max</literal> control + group attributes. Use this option multiple times to set IOPS limits for multiple devices. For details about + this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">cgroup-v2.txt</ulink>. + </para> + + <para>Implies <literal>IOAccounting=true</literal>.</para> + + <para>These settings are supported only if the unified control group hierarchy is used and disable settings + prefixed with <varname>BlockIO</varname> or <varname>StartupBlockIO</varname>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>DeviceAllow=</varname></term> + + <listitem> + <para>Control access to specific device nodes by the + executed processes. Takes two space-separated strings: a + device node specifier followed by a combination of + <constant>r</constant>, <constant>w</constant>, + <constant>m</constant> to control + <emphasis>r</emphasis>eading, <emphasis>w</emphasis>riting, + or creation of the specific device node(s) by the unit + (<emphasis>m</emphasis>knod), respectively. This controls + the <literal>devices.allow</literal> and + <literal>devices.deny</literal> control group + attributes. For details about these control group + attributes, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt">devices.txt</ulink>.</para> + + <para>The device node specifier is either a path to a device + node in the file system, starting with + <filename>/dev/</filename>, or a string starting with either + <literal>char-</literal> or <literal>block-</literal> + followed by a device group name, as listed in + <filename>/proc/devices</filename>. The latter is useful to + whitelist all current and future devices belonging to a + specific device group at once. The device group is matched + according to file name globbing rules, you may hence use the + <literal>*</literal> and <literal>?</literal> + wildcards. Examples: <filename>/dev/sda5</filename> is a + path to a device node, referring to an ATA or SCSI block + device. <literal>char-pts</literal> and + <literal>char-alsa</literal> are specifiers for all pseudo + TTYs and all ALSA sound devices, + respectively. <literal>char-cpu/*</literal> is a specifier + matching all CPU related device groups.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>DevicePolicy=auto|closed|strict</varname></term> + + <listitem> + <para> + Control the policy for allowing device access: + </para> + <variablelist> + <varlistentry> + <term><option>strict</option></term> + <listitem> + <para>means to only allow types of access that are + explicitly specified.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>closed</option></term> + <listitem> + <para>in addition, allows access to standard pseudo + devices including + <filename>/dev/null</filename>, + <filename>/dev/zero</filename>, + <filename>/dev/full</filename>, + <filename>/dev/random</filename>, and + <filename>/dev/urandom</filename>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>auto</option></term> + <listitem> + <para> + in addition, allows access to all devices if no + explicit <varname>DeviceAllow=</varname> is present. + This is the default. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>Slice=</varname></term> + + <listitem> + <para>The name of the slice unit to place the unit + in. Defaults to <filename>system.slice</filename> for all + non-instantiated units of all unit types (except for slice + units themselves see below). Instance units are by default + placed in a subslice of <filename>system.slice</filename> + that is named after the template name.</para> + + <para>This option may be used to arrange systemd units in a + hierarchy of slices each of which might have resource + settings applied.</para> + + <para>For units of type slice, the only accepted value for + this setting is the parent slice. Since the name of a slice + unit implies the parent slice, it is hence redundant to ever + set this parameter directly for slice units.</para> + + <para>Special care should be taken when relying on the default slice assignment in templated service units + that have <varname>DefaultDependencies=no</varname> set, see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, section + "Automatic Dependencies" for details.</para> + + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>Delegate=</varname></term> + + <listitem> + <para>Turns on delegation of further resource control + partitioning to processes of the unit. For unprivileged + services (i.e. those using the <varname>User=</varname> + setting), this allows processes to create a subhierarchy + beneath its control group path. For privileged services and + scopes, this ensures the processes will have all control + group controllers enabled.</para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Deprecated Options</title> + + <para>The following options are deprecated. Use the indicated superseding options instead:</para> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>CPUShares=<replaceable>weight</replaceable></varname></term> + <term><varname>StartupCPUShares=<replaceable>weight</replaceable></varname></term> + + <listitem> + <para>Assign the specified CPU time share weight to the processes executed. These options take an integer + value and control the <literal>cpu.shares</literal> control group attribute. The allowed range is 2 to + 262144. Defaults to 1024. For details about this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt">sched-design-CFS.txt</ulink>. + The available CPU time is split up among all units within one slice relative to their CPU time share + weight.</para> + + <para>While <varname>StartupCPUShares=</varname> only applies to the startup phase of the system, + <varname>CPUShares=</varname> applies to normal runtime of the system, and if the former is not set also to + the startup phase. Using <varname>StartupCPUShares=</varname> allows prioritizing specific services at + boot-up differently than during normal runtime.</para> + + <para>Implies <literal>CPUAccounting=true</literal>.</para> + + <para>These settings are deprecated. Use <varname>CPUWeight=</varname> and + <varname>StartupCPUWeight=</varname> instead.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MemoryLimit=<replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Specify the limit on maximum memory usage of the executed processes. The limit specifies how much + process and kernel memory can be used by tasks in this unit. Takes a memory size in bytes. If the value is + suffixed with K, M, G or T, the specified memory size is parsed as Kilobytes, Megabytes, Gigabytes, or + Terabytes (with the base 1024), respectively. Alternatively, a percentage value may be specified, which is + taken relative to the installed physical memory on the system. If assigned the special value + <literal>infinity</literal>, no memory limit is applied. This controls the + <literal>memory.limit_in_bytes</literal> control group attribute. For details about this control group + attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>.</para> + + <para>Implies <literal>MemoryAccounting=true</literal>.</para> + + <para>This setting is deprecated. Use <varname>MemoryMax=</varname> instead.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>BlockIOAccounting=</varname></term> + + <listitem> + <para>Turn on Block I/O accounting for this unit, if the legacy control group hierarchy is used on the + system. Takes a boolean argument. Note that turning on block I/O accounting for one unit will also implicitly + turn it on for all units contained in the same slice and all for its parent slices and the units contained + therein. The system default for this setting may be controlled with + <varname>DefaultBlockIOAccounting=</varname> in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>This setting is deprecated. Use <varname>IOAccounting=</varname> instead.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>BlockIOWeight=<replaceable>weight</replaceable></varname></term> + <term><varname>StartupBlockIOWeight=<replaceable>weight</replaceable></varname></term> + + <listitem><para>Set the default overall block I/O weight for the executed processes, if the legacy control + group hierarchy is used on the system. Takes a single weight value (between 10 and 1000) to set the default + block I/O weight. This controls the <literal>blkio.weight</literal> control group attribute, which defaults to + 500. For details about this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>. + The available I/O bandwidth is split up among all units within one slice relative to their block I/O + weight.</para> + + <para>While <varname>StartupBlockIOWeight=</varname> only + applies to the startup phase of the system, + <varname>BlockIOWeight=</varname> applies to the later runtime + of the system, and if the former is not set also to the + startup phase. This allows prioritizing specific services at + boot-up differently than during runtime.</para> + + <para>Implies + <literal>BlockIOAccounting=true</literal>.</para> + + <para>These settings are deprecated. Use <varname>IOWeight=</varname> and <varname>StartupIOWeight=</varname> + instead.</para> + + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>BlockIODeviceWeight=<replaceable>device</replaceable> <replaceable>weight</replaceable></varname></term> + + <listitem> + <para>Set the per-device overall block I/O weight for the executed processes, if the legacy control group + hierarchy is used on the system. Takes a space-separated pair of a file path and a weight value to specify + the device specific weight value, between 10 and 1000. (Example: "/dev/sda 500"). The file path may be + specified as path to a block device node or as any other file, in which case the backing block device of the + file system of the file is determined. This controls the <literal>blkio.weight_device</literal> control group + attribute, which defaults to 1000. Use this option multiple times to set weights for multiple devices. For + details about this control group attribute, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>.</para> + + <para>Implies + <literal>BlockIOAccounting=true</literal>.</para> + + <para>This setting is deprecated. Use <varname>IODeviceWeight=</varname> instead.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>BlockIOReadBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> + <term><varname>BlockIOWriteBandwidth=<replaceable>device</replaceable> <replaceable>bytes</replaceable></varname></term> + + <listitem> + <para>Set the per-device overall block I/O bandwidth limit for the executed processes, if the legacy control + group hierarchy is used on the system. Takes a space-separated pair of a file path and a bandwidth value (in + bytes per second) to specify the device specific bandwidth. The file path may be a path to a block device + node, or as any other file in which case the backing block device of the file system of the file is used. If + the bandwidth is suffixed with K, M, G, or T, the specified bandwidth is parsed as Kilobytes, Megabytes, + Gigabytes, or Terabytes, respectively, to the base of 1000. (Example: + "/dev/disk/by-path/pci-0000:00:1f.2-scsi-0:0:0:0 5M"). This controls the + <literal>blkio.throttle.read_bps_device</literal> and <literal>blkio.throttle.write_bps_device</literal> + control group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For + details about these control group attributes, see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>. + </para> + + <para>Implies + <literal>BlockIOAccounting=true</literal>.</para> + + <para>These settings are deprecated. Use <varname>IOReadBandwidthMax=</varname> and + <varname>IOWriteBandwidthMax=</varname> instead.</para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + The documentation for control groups and specific controllers in the Linux kernel: + <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>, + <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/cpuacct.txt">cpuacct.txt</ulink>, + <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt">memory.txt</ulink>, + <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt">blkio-controller.txt</ulink>. + </para> + </refsect1> +</refentry> diff --git a/src/grp-system/systemd/systemd.scope.xml b/src/grp-system/systemd/systemd.scope.xml new file mode 100644 index 0000000000..f69b2ef635 --- /dev/null +++ b/src/grp-system/systemd/systemd.scope.xml @@ -0,0 +1,108 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2013 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.scope"> + <refentryinfo> + <title>systemd.scope</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.scope</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.scope</refname> + <refpurpose>Scope unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>scope</replaceable>.scope</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Scope units are not configured via unit configuration files, + but are only created programmatically using the bus interfaces of + systemd. They are named similar to filenames. A unit whose name + ends in <literal>.scope</literal> refers to a scope unit. Scopes + units manage a set of system processes. Unlike service units, scope + units manage externally created processes, and do not fork off + processes on its own.</para> + + <para>The main purpose of scope units is grouping worker processes + of a system service for organization and for managing resources.</para> + + <para><command>systemd-run <option>--scope</option></command> may + be used to easily launch a command in a new scope unit from the + command line.</para> + + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New + Control Group Interfaces</ulink> for an introduction on how to make + use of scope units from programs.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>Unless <varname>DefaultDependencies=false</varname> + is used, scope units will implicitly have dependencies of + type <varname>Conflicts=</varname> and + <varname>Before=</varname> on + <filename>shutdown.target</filename>. These ensure + that scope units are removed prior to system + shutdown. Only scope units involved with early boot or + late system shutdown should disable this option. + </para> + + <para>Additional implicit dependencies may be added as result of + resource control parameters as documented in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.service.xml b/src/grp-system/systemd/systemd.service.xml new file mode 100644 index 0000000000..5c65957bda --- /dev/null +++ b/src/grp-system/systemd/systemd.service.xml @@ -0,0 +1,1354 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.service"> + <refentryinfo> + <title>systemd.service</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.service</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.service</refname> + <refpurpose>Service unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>service</replaceable>.service</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <filename>.service</filename> encodes information about a process + controlled and supervised by systemd.</para> + + <para>This man page lists the configuration options specific to + this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic + <literal>[Unit]</literal> and <literal>[Install]</literal> + sections. The service specific configuration options are + configured in the <literal>[Service]</literal> section.</para> + + <para>Additional options are listed in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the execution environment the commands are executed + in, and in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the way the processes of the service are terminated, + and in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which configure resource control settings for the processes of the + service.</para> + + <para>If a service is requested under a certain name but no unit + configuration file is found, systemd looks for a SysV init script + by the same name (with the <filename>.service</filename> suffix + removed) and dynamically creates a service unit from that script. + This is useful for compatibility with SysV. Note that this + compatibility is quite comprehensive but not 100%. For details + about the incompatibilities, see the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities + with SysV</ulink> document.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>Services with <varname>Type=dbus</varname> set automatically + acquire dependencies of type <varname>Requires=</varname> and + <varname>After=</varname> on + <filename>dbus.socket</filename>.</para> + + <para>Socket activated services are automatically ordered after + their activating <filename>.socket</filename> units via an + automatic <varname>After=</varname> dependency. + Services also pull in all <filename>.socket</filename> units + listed in <varname>Sockets=</varname> via automatic + <varname>Wants=</varname> and <varname>After=</varname> dependencies.</para> + + <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> is set to + <option>false</option>, service units will implicitly have dependencies of type <varname>Requires=</varname> and + <varname>After=</varname> on <filename>sysinit.target</filename>, a dependency of type <varname>After=</varname> on + <filename>basic.target</filename> as well as dependencies of type <varname>Conflicts=</varname> and + <varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure that normal service units pull in + basic system initialization, and are terminated cleanly prior to system shutdown. Only services involved with early + boot or late system shutdown should disable this option.</para> + + <para>Instanced service units (i.e. service units with an <literal>@</literal> in their name) are assigned by + default a per-template slice unit (see + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>), named after the + template unit, containing all instances of the specific template. This slice is normally stopped at shutdown, + together with all template instances. If that is not desired, set <varname>DefaultDependencies=no</varname> in the + template unit, and either define your own per-template slice unit file that also sets + <varname>DefaultDependencies=no</varname>, or set <varname>Slice=system.slice</varname> (or another suitable slice) + in the template unit. Also see + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>Additional implicit dependencies may be added as result of + execution and resource control parameters as documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Service files must include a <literal>[Service]</literal> + section, which carries information about the service and the + process it supervises. A number of options that may be used in + this section are shared with other unit types. These options are + documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + The options specific to the <literal>[Service]</literal> section + of service units are the following:</para> + + <variablelist class='unit-directives'> + <varlistentry> + <term><varname>Type=</varname></term> + + <listitem><para>Configures the process start-up type for this + service unit. One of + <option>simple</option>, + <option>forking</option>, + <option>oneshot</option>, + <option>dbus</option>, + <option>notify</option> or + <option>idle</option>.</para> + + <para>If set to <option>simple</option> (the default if + neither <varname>Type=</varname> nor + <varname>BusName=</varname>, but <varname>ExecStart=</varname> + are specified), it is expected that the process configured + with <varname>ExecStart=</varname> is the main process of the + service. In this mode, if the process offers functionality to + other processes on the system, its communication channels + should be installed before the daemon is started up (e.g. + sockets set up by systemd, via socket activation), as systemd + will immediately proceed starting follow-up units.</para> + + <para>If set to <option>forking</option>, it is expected that + the process configured with <varname>ExecStart=</varname> will + call <function>fork()</function> as part of its start-up. The + parent process is expected to exit when start-up is complete + and all communication channels are set up. The child continues + to run as the main daemon process. This is the behavior of + traditional UNIX daemons. If this setting is used, it is + recommended to also use the <varname>PIDFile=</varname> + option, so that systemd can identify the main process of the + daemon. systemd will proceed with starting follow-up units as + soon as the parent process exits.</para> + + <para>Behavior of <option>oneshot</option> is similar to + <option>simple</option>; however, it is expected that the + process has to exit before systemd starts follow-up units. + <varname>RemainAfterExit=</varname> is particularly useful for + this type of service. This is the implied default if neither + <varname>Type=</varname> or <varname>ExecStart=</varname> are + specified.</para> + + <para>Behavior of <option>dbus</option> is similar to + <option>simple</option>; however, it is expected that the + daemon acquires a name on the D-Bus bus, as configured by + <varname>BusName=</varname>. systemd will proceed with + starting follow-up units after the D-Bus bus name has been + acquired. Service units with this option configured implicitly + gain dependencies on the <filename>dbus.socket</filename> + unit. This type is the default if <varname>BusName=</varname> + is specified.</para> + + <para>Behavior of <option>notify</option> is similar to + <option>simple</option>; however, it is expected that the + daemon sends a notification message via + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or an equivalent call when it has finished starting up. + systemd will proceed with starting follow-up units after this + notification message has been sent. If this option is used, + <varname>NotifyAccess=</varname> (see below) should be set to + open access to the notification socket provided by systemd. If + <varname>NotifyAccess=</varname> is missing or set to + <option>none</option>, it will be forcibly set to + <option>main</option>. Note that currently + <varname>Type=</varname><option>notify</option> will not work + if used in combination with + <varname>PrivateNetwork=</varname><option>yes</option>.</para> + + <para>Behavior of <option>idle</option> is very similar to <option>simple</option>; however, actual execution + of the service binary is delayed until all active jobs are dispatched. This may be used to avoid interleaving + of output of shell services with the status output on the console. Note that this type is useful only to + improve console output, it is not useful as a general unit ordering tool, and the effect of this service type + is subject to a 5s time-out, after which the service binary is invoked anyway.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>RemainAfterExit=</varname></term> + + <listitem><para>Takes a boolean value that specifies whether + the service shall be considered active even when all its + processes exited. Defaults to <option>no</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>GuessMainPID=</varname></term> + + <listitem><para>Takes a boolean value that specifies whether + systemd should try to guess the main PID of a service if it + cannot be determined reliably. This option is ignored unless + <option>Type=forking</option> is set and + <option>PIDFile=</option> is unset because for the other types + or with an explicitly configured PID file, the main PID is + always known. The guessing algorithm might come to incorrect + conclusions if a daemon consists of more than one process. If + the main PID cannot be determined, failure detection and + automatic restarting of a service will not work reliably. + Defaults to <option>yes</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>PIDFile=</varname></term> + + <listitem><para>Takes an absolute file name pointing to the + PID file of this daemon. Use of this option is recommended for + services where <varname>Type=</varname> is set to + <option>forking</option>. systemd will read the PID of the + main process of the daemon after start-up of the service. + systemd will not write to the file configured here, although + it will remove the file after the service has shut down if it + still exists. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>BusName=</varname></term> + + <listitem><para>Takes a D-Bus bus name that this service is + reachable as. This option is mandatory for services where + <varname>Type=</varname> is set to + <option>dbus</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStart=</varname></term> + <listitem><para>Commands with their arguments that are + executed when this service is started. The value is split into + zero or more command lines according to the rules described + below (see section "Command Lines" below). + </para> + + <para>Unless <varname>Type=</varname> is <option>oneshot</option>, exactly one command must be given. When + <varname>Type=oneshot</varname> is used, zero or more commands may be specified. Commands may be specified by + providing multiple command lines in the same directive, or alternatively, this directive may be specified more + than once with the same effect. If the empty string is assigned to this option, the list of commands to start + is reset, prior assignments of this option will have no effect. If no <varname>ExecStart=</varname> is + specified, then the service must have <varname>RemainAfterExit=yes</varname> set.</para> + + <para>For each of the specified commands, the first argument must be an absolute path to an + executable. Optionally, if this file name is prefixed with <literal>@</literal>, the second token will be + passed as <literal>argv[0]</literal> to the executed process, followed by the further arguments specified. If + the absolute filename is prefixed with <literal>-</literal>, an exit code of the command normally considered a + failure (i.e. non-zero exit status or abnormal exit due to signal) is ignored and considered success. If the + absolute path is prefixed with <literal>+</literal> then it is executed with full + privileges. <literal>@</literal>, <literal>-</literal>, and <literal>+</literal> may be used together and they + can appear in any order.</para> + + <para>If more than one command is specified, the commands are + invoked sequentially in the order they appear in the unit + file. If one of the commands fails (and is not prefixed with + <literal>-</literal>), other lines are not executed, and the + unit is considered failed.</para> + + <para>Unless <varname>Type=forking</varname> is set, the + process started via this command line will be considered the + main process of the daemon.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStartPre=</varname></term> + <term><varname>ExecStartPost=</varname></term> + <listitem><para>Additional commands that are executed before + or after the command in <varname>ExecStart=</varname>, + respectively. Syntax is the same as for + <varname>ExecStart=</varname>, except that multiple command + lines are allowed and the commands are executed one after the + other, serially.</para> + + <para>If any of those commands (not prefixed with + <literal>-</literal>) fail, the rest are not executed and the + unit is considered failed.</para> + + <para><varname>ExecStart=</varname> commands are only run after + all <varname>ExecStartPre=</varname> commands that were not prefixed + with a <literal>-</literal> exit successfully.</para> + + <para><varname>ExecStartPost=</varname> commands are only run after + the service has started successfully, as determined by <varname>Type=</varname> + (i.e. the process has been started for <varname>Type=simple</varname> + or <varname>Type=idle</varname>, the process exits successfully for + <varname>Type=oneshot</varname>, the initial process exits successfully + for <varname>Type=forking</varname>, <literal>READY=1</literal> is sent + for <varname>Type=notify</varname>, or the <varname>BusName=</varname> + has been taken for <varname>Type=dbus</varname>).</para> + + <para>Note that <varname>ExecStartPre=</varname> may not be + used to start long-running processes. All processes forked + off by processes invoked via <varname>ExecStartPre=</varname> will + be killed before the next service process is run.</para> + + <para>Note that if any of the commands specified in <varname>ExecStartPre=</varname>, + <varname>ExecStart=</varname>, or <varname>ExecStartPost=</varname> fail (and are not prefixed with + <literal>-</literal>, see above) or time out before the service is fully up, execution continues with commands + specified in <varname>ExecStopPost=</varname>, the commands in <varname>ExecStop=</varname> are skipped.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecReload=</varname></term> + <listitem><para>Commands to execute to trigger a configuration + reload in the service. This argument takes multiple command + lines, following the same scheme as described for + <varname>ExecStart=</varname> above. Use of this setting is + optional. Specifier and environment variable substitution is + supported here following the same scheme as for + <varname>ExecStart=</varname>.</para> + + <para>One additional, special environment variable is set: if + known, <varname>$MAINPID</varname> is set to the main process + of the daemon, and may be used for command lines like the + following:</para> + + <programlisting>/bin/kill -HUP $MAINPID</programlisting> + + <para>Note however that reloading a daemon by sending a signal + (as with the example line above) is usually not a good choice, + because this is an asynchronous operation and hence not + suitable to order reloads of multiple services against each + other. It is strongly recommended to set + <varname>ExecReload=</varname> to a command that not only + triggers a configuration reload of the daemon, but also + synchronously waits for it to complete.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStop=</varname></term> + <listitem><para>Commands to execute to stop the service + started via <varname>ExecStart=</varname>. This argument takes + multiple command lines, following the same scheme as described + for <varname>ExecStart=</varname> above. Use of this setting + is optional. After the commands configured in this option are + run, all processes remaining for a service are terminated + according to the <varname>KillMode=</varname> setting (see + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + If this option is not specified, the process is terminated by + sending the signal specified in <varname>KillSignal=</varname> + when service stop is requested. Specifier and environment + variable substitution is supported (including + <varname>$MAINPID</varname>, see above).</para> + + <para>Note that it is usually not sufficient to specify a + command for this setting that only asks the service to + terminate (for example, by queuing some form of termination + signal for it), but does not wait for it to do so. Since the + remaining processes of the services are killed using + <constant>SIGKILL</constant> immediately after the command + exited, this would not result in a clean stop. The specified + command should hence be a synchronous operation, not an + asynchronous one.</para> + + <para>Note that the commands specified in <varname>ExecStop=</varname> are only executed when the service + started successfully first. They are not invoked if the service was never started at all, or in case its + start-up failed, for example because any of the commands specified in <varname>ExecStart=</varname>, + <varname>ExecStartPre=</varname> or <varname>ExecStartPost=</varname> failed (and weren't prefixed with + <literal>-</literal>, see above) or timed out. Use <varname>ExecStopPost=</varname> to invoke commands when a + service failed to start up correctly and is shut down again.</para> + + <para>It is recommended to use this setting for commands that communicate with the service requesting clean + termination. When the commands specified with this option are executed it should be assumed that the service is + still fully up and is able to react correctly to all commands. For post-mortem clean-up steps use + <varname>ExecStopPost=</varname> instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStopPost=</varname></term> + <listitem><para>Additional commands that are executed after the service is stopped. This includes cases where + the commands configured in <varname>ExecStop=</varname> were used, where the service does not have any + <varname>ExecStop=</varname> defined, or where the service exited unexpectedly. This argument takes multiple + command lines, following the same scheme as described for <varname>ExecStart=</varname>. Use of these settings + is optional. Specifier and environment variable substitution is supported. Note that – unlike + <varname>ExecStop=</varname> – commands specified with this setting are invoked when a service failed to start + up correctly and is shut down again.</para> + + <para>It is recommended to use this setting for clean-up operations that shall be executed even when the + service failed to start up correctly. Commands configured with this setting need to be able to operate even if + the service failed starting up half-way and left incompletely initialized data around. As the service's + processes have been terminated already when the commands specified with this setting are executed they should + not attempt to communicate with them.</para> + + <para>Note that all commands that are configured with this setting are invoked with the result code of the + service, as well as the main process' exit code and status, set in the <varname>$SERVICE_RESULT</varname>, + <varname>$EXIT_CODE</varname> and <varname>$EXIT_STATUS</varname> environment variables, see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RestartSec=</varname></term> + <listitem><para>Configures the time to sleep before restarting + a service (as configured with <varname>Restart=</varname>). + Takes a unit-less value in seconds, or a time span value such + as "5min 20s". Defaults to 100ms.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutStartSec=</varname></term> + <listitem><para>Configures the time to wait for start-up. If a + daemon service does not signal start-up completion within the + configured time, the service will be considered failed and + will be shut down again. Takes a unit-less value in seconds, + or a time span value such as "5min 20s". Pass + <literal>infinity</literal> to disable the timeout logic. Defaults to + <varname>DefaultTimeoutStartSec=</varname> from the manager + configuration file, except when + <varname>Type=oneshot</varname> is used, in which case the + timeout is disabled by default (see + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutStopSec=</varname></term> + <listitem><para>Configures the time to wait for stop. If a + service is asked to stop, but does not terminate in the + specified time, it will be terminated forcibly via + <constant>SIGTERM</constant>, and after another timeout of + equal duration with <constant>SIGKILL</constant> (see + <varname>KillMode=</varname> in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + Takes a unit-less value in seconds, or a time span value such + as "5min 20s". Pass <literal>infinity</literal> to disable the + timeout logic. Defaults to + <varname>DefaultTimeoutStopSec=</varname> from the manager + configuration file (see + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutSec=</varname></term> + <listitem><para>A shorthand for configuring both + <varname>TimeoutStartSec=</varname> and + <varname>TimeoutStopSec=</varname> to the specified value. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RuntimeMaxSec=</varname></term> + + <listitem><para>Configures a maximum time for the service to run. If this is used and the service has been + active for longer than the specified time it is terminated and put into a failure state. Note that this setting + does not have any effect on <varname>Type=oneshot</varname> services, as they terminate immediately after + activation completed. Pass <literal>infinity</literal> (the default) to configure no runtime + limit.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>WatchdogSec=</varname></term> + <listitem><para>Configures the watchdog timeout for a service. + The watchdog is activated when the start-up is completed. The + service must call + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + regularly with <literal>WATCHDOG=1</literal> (i.e. the + "keep-alive ping"). If the time between two such calls is + larger than the configured time, then the service is placed in + a failed state and it will be terminated with + <constant>SIGABRT</constant>. By setting + <varname>Restart=</varname> to <option>on-failure</option>, + <option>on-watchdog</option>, <option>on-abnormal</option> or + <option>always</option>, the service will be automatically + restarted. The time configured here will be passed to the + executed service process in the + <varname>WATCHDOG_USEC=</varname> environment variable. This + allows daemons to automatically enable the keep-alive pinging + logic if watchdog support is enabled for the service. If this + option is used, <varname>NotifyAccess=</varname> (see below) + should be set to open access to the notification socket + provided by systemd. If <varname>NotifyAccess=</varname> is + not set, it will be implicitly set to <option>main</option>. + Defaults to 0, which disables this feature. The service can + check whether the service manager expects watchdog keep-alive + notifications. See + <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details. + <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + may be used to enable automatic watchdog notification support. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Restart=</varname></term> + <listitem><para>Configures whether the service shall be + restarted when the service process exits, is killed, or a + timeout is reached. The service process may be the main + service process, but it may also be one of the processes + specified with <varname>ExecStartPre=</varname>, + <varname>ExecStartPost=</varname>, + <varname>ExecStop=</varname>, + <varname>ExecStopPost=</varname>, or + <varname>ExecReload=</varname>. When the death of the process + is a result of systemd operation (e.g. service stop or + restart), the service will not be restarted. Timeouts include + missing the watchdog "keep-alive ping" deadline and a service + start, reload, and stop operation timeouts.</para> + + <para>Takes one of + <option>no</option>, + <option>on-success</option>, + <option>on-failure</option>, + <option>on-abnormal</option>, + <option>on-watchdog</option>, + <option>on-abort</option>, or + <option>always</option>. + If set to <option>no</option> (the default), the service will + not be restarted. If set to <option>on-success</option>, it + will be restarted only when the service process exits cleanly. + In this context, a clean exit means an exit code of 0, or one + of the signals + <constant>SIGHUP</constant>, + <constant>SIGINT</constant>, + <constant>SIGTERM</constant> or + <constant>SIGPIPE</constant>, and + additionally, exit statuses and signals specified in + <varname>SuccessExitStatus=</varname>. If set to + <option>on-failure</option>, the service will be restarted + when the process exits with a non-zero exit code, is + terminated by a signal (including on core dump, but excluding + the aforementioned four signals), when an operation (such as + service reload) times out, and when the configured watchdog + timeout is triggered. If set to <option>on-abnormal</option>, + the service will be restarted when the process is terminated + by a signal (including on core dump, excluding the + aforementioned four signals), when an operation times out, or + when the watchdog timeout is triggered. If set to + <option>on-abort</option>, the service will be restarted only + if the service process exits due to an uncaught signal not + specified as a clean exit status. If set to + <option>on-watchdog</option>, the service will be restarted + only if the watchdog timeout for the service expires. If set + to <option>always</option>, the service will be restarted + regardless of whether it exited cleanly or not, got terminated + abnormally by a signal, or hit a timeout.</para> + + <table> + <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title> + + <tgroup cols='2'> + <colspec colname='path' /> + <colspec colname='expl' /> + <thead> + <row> + <entry>Restart settings/Exit causes</entry> + <entry><option>no</option></entry> + <entry><option>always</option></entry> + <entry><option>on-success</option></entry> + <entry><option>on-failure</option></entry> + <entry><option>on-abnormal</option></entry> + <entry><option>on-abort</option></entry> + <entry><option>on-watchdog</option></entry> + </row> + </thead> + <tbody> + <row> + <entry>Clean exit code or signal</entry> + <entry/> + <entry>X</entry> + <entry>X</entry> + <entry/> + <entry/> + <entry/> + <entry/> + </row> + <row> + <entry>Unclean exit code</entry> + <entry/> + <entry>X</entry> + <entry/> + <entry>X</entry> + <entry/> + <entry/> + <entry/> + </row> + <row> + <entry>Unclean signal</entry> + <entry/> + <entry>X</entry> + <entry/> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry/> + </row> + <row> + <entry>Timeout</entry> + <entry/> + <entry>X</entry> + <entry/> + <entry>X</entry> + <entry>X</entry> + <entry/> + <entry/> + </row> + <row> + <entry>Watchdog</entry> + <entry/> + <entry>X</entry> + <entry/> + <entry>X</entry> + <entry>X</entry> + <entry/> + <entry>X</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>As exceptions to the setting above, the service will not + be restarted if the exit code or signal is specified in + <varname>RestartPreventExitStatus=</varname> (see below). + Also, the services will always be restarted if the exit code + or signal is specified in + <varname>RestartForceExitStatus=</varname> (see below).</para> + + <para>Setting this to <option>on-failure</option> is the + recommended choice for long-running services, in order to + increase reliability by attempting automatic recovery from + errors. For services that shall be able to terminate on their + own choice (and avoid immediate restarting), + <option>on-abnormal</option> is an alternative choice.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>SuccessExitStatus=</varname></term> + <listitem><para>Takes a list of exit status definitions that, + when returned by the main service process, will be considered + successful termination, in addition to the normal successful + exit code 0 and the signals <constant>SIGHUP</constant>, + <constant>SIGINT</constant>, <constant>SIGTERM</constant>, and + <constant>SIGPIPE</constant>. Exit status definitions can + either be numeric exit codes or termination signal names, + separated by spaces. For example: + + <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting> + + ensures that exit codes 1, 2, 8 and + the termination signal <constant>SIGKILL</constant> are + considered clean service terminations. + </para> + + <para>Note that if a process has a signal handler installed + and exits by calling + <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry> + in response to a signal, the information about the signal is + lost. Programs should instead perform cleanup and kill + themselves with the same signal instead. See + <ulink url="http://www.cons.org/cracauer/sigint.html">Proper + handling of SIGINT/SIGQUIT — How to be a proper + program</ulink>.</para> + + <para>This option may appear more than once, in which case the + list of successful exit statuses is merged. If the empty + string is assigned to this option, the list is reset, all + prior assignments of this option will have no + effect.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RestartPreventExitStatus=</varname></term> + <listitem><para>Takes a list of exit status definitions that, + when returned by the main service process, will prevent + automatic service restarts, regardless of the restart setting + configured with <varname>Restart=</varname>. Exit status + definitions can either be numeric exit codes or termination + signal names, and are separated by spaces. Defaults to the + empty list, so that, by default, no exit status is excluded + from the configured restart logic. For example: + + <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> + + ensures that exit codes 1 and 6 and the termination signal + <constant>SIGABRT</constant> will not result in automatic + service restarting. This option may appear more than once, in + which case the list of restart-preventing statuses is + merged. If the empty string is assigned to this option, the + list is reset and all prior assignments of this option will + have no effect.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RestartForceExitStatus=</varname></term> + <listitem><para>Takes a list of exit status definitions that, + when returned by the main service process, will force automatic + service restarts, regardless of the restart setting configured + with <varname>Restart=</varname>. The argument format is + similar to + <varname>RestartPreventExitStatus=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PermissionsStartOnly=</varname></term> + <listitem><para>Takes a boolean argument. If true, the + permission-related execution options, as configured with + <varname>User=</varname> and similar options (see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information), are only applied to the process started + with + <varname>ExecStart=</varname>, and not to the various other + <varname>ExecStartPre=</varname>, + <varname>ExecStartPost=</varname>, + <varname>ExecReload=</varname>, + <varname>ExecStop=</varname>, and + <varname>ExecStopPost=</varname> + commands. If false, the setting is applied to all configured + commands the same way. Defaults to false.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RootDirectoryStartOnly=</varname></term> + <listitem><para>Takes a boolean argument. If true, the root + directory, as configured with the + <varname>RootDirectory=</varname> option (see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information), is only applied to the process started + with <varname>ExecStart=</varname>, and not to the various + other <varname>ExecStartPre=</varname>, + <varname>ExecStartPost=</varname>, + <varname>ExecReload=</varname>, <varname>ExecStop=</varname>, + and <varname>ExecStopPost=</varname> commands. If false, the + setting is applied to all configured commands the same way. + Defaults to false.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>NonBlocking=</varname></term> + <listitem><para>Set the <constant>O_NONBLOCK</constant> flag + for all file descriptors passed via socket-based activation. + If true, all file descriptors >= 3 (i.e. all except stdin, + stdout, and stderr) will have the + <constant>O_NONBLOCK</constant> flag set and hence are in + non-blocking mode. This option is only useful in conjunction + with a socket unit, as described in + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Defaults to false.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>NotifyAccess=</varname></term> + <listitem><para>Controls access to the service status + notification socket, as accessible via the + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call. Takes one of <option>none</option> (the default), + <option>main</option> or <option>all</option>. If + <option>none</option>, no daemon status updates are accepted + from the service processes, all status update messages are + ignored. If <option>main</option>, only service updates sent + from the main process of the service are accepted. If + <option>all</option>, all services updates from all members of + the service's control group are accepted. This option should + be set to open access to the notification socket when using + <varname>Type=notify</varname> or + <varname>WatchdogSec=</varname> (see above). If those options + are used but <varname>NotifyAccess=</varname> is not + configured, it will be implicitly set to + <option>main</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Sockets=</varname></term> + <listitem><para>Specifies the name of the socket units this + service shall inherit socket file descriptors from when the + service is started. Normally, it should not be necessary to use + this setting, as all socket file descriptors whose unit shares + the same name as the service (subject to the different unit + name suffix of course) are passed to the spawned + process.</para> + + <para>Note that the same socket file descriptors may be passed + to multiple processes simultaneously. Also note that a + different service may be activated on incoming socket traffic + than the one which is ultimately configured to inherit the + socket file descriptors. Or, in other words: the + <varname>Service=</varname> setting of + <filename>.socket</filename> units does not have to match the + inverse of the <varname>Sockets=</varname> setting of the + <filename>.service</filename> it refers to.</para> + + <para>This option may appear more than once, in which case the + list of socket units is merged. If the empty string is + assigned to this option, the list of sockets is reset, and all + prior uses of this setting will have no + effect.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FailureAction=</varname></term> + <listitem><para>Configure the action to take when the service enters a failed state. Takes the same values as + the unit setting <varname>StartLimitAction=</varname> and executes the same actions (see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Defaults to + <option>none</option>. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FileDescriptorStoreMax=</varname></term> + <listitem><para>Configure how many file descriptors may be + stored in the service manager for the service using + <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s + <literal>FDSTORE=1</literal> messages. This is useful for + implementing service restart schemes where the state is + serialized to <filename>/run</filename> and the file + descriptors passed to the service manager, to allow restarts + without losing state. Defaults to 0, i.e. no file descriptors + may be stored in the service manager. All file + descriptors passed to the service manager from a specific + service are passed back to the service's main process on the + next service restart. Any file descriptors passed to the + service manager are automatically closed when POLLHUP or + POLLERR is seen on them, or when the service is fully stopped + and no job is queued or being executed for it.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>USBFunctionDescriptors=</varname></term> + <listitem><para>Configure the location of a file containing + <ulink + url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB + FunctionFS</ulink> descriptors, for implementation of USB + gadget functions. This is used only in conjunction with a + socket unit with <varname>ListenUSBFunction=</varname> + configured. The contents of this file are written to the + <filename>ep0</filename> file after it is + opened.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>USBFunctionStrings=</varname></term> + <listitem><para>Configure the location of a file containing + USB FunctionFS strings. Behavior is similar to + <varname>USBFunctionDescriptors=</varname> + above.</para></listitem> + </varlistentry> + + </variablelist> + + <para>Check + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more settings.</para> + + </refsect1> + + <refsect1> + <title>Command lines</title> + + <para>This section describes command line parsing and + variable and specifier substitutions for + <varname>ExecStart=</varname>, + <varname>ExecStartPre=</varname>, + <varname>ExecStartPost=</varname>, + <varname>ExecReload=</varname>, + <varname>ExecStop=</varname>, and + <varname>ExecStopPost=</varname> options.</para> + + <para>Multiple command lines may be concatenated in a single + directive by separating them with semicolons (these semicolons + must be passed as separate words). Lone semicolons may be escaped + as <literal>\;</literal>.</para> + + <para>Each command line is split on whitespace, with the first + item being the command to execute, and the subsequent items being + the arguments. Double quotes ("...") and single quotes ('...') may + be used, in which case everything until the next matching quote + becomes part of the same argument. C-style escapes are also + supported. The table below contains the list of allowed escape + patterns. Only patterns which match the syntax in the table are + allowed; others will result in an error, and must be escaped by + doubling the backslash. Quotes themselves are removed after + parsing and escape sequences substituted. In addition, a trailing + backslash (<literal>\</literal>) may be used to merge lines. + </para> + + <para>This syntax is intended to be very similar to shell syntax, + but only the meta-characters and expansions described in the + following paragraphs are understood. Specifically, redirection + using + <literal><</literal>, + <literal><<</literal>, + <literal>></literal>, and + <literal>>></literal>, pipes using + <literal>|</literal>, running programs in the background using + <literal>&</literal>, and <emphasis>other elements of shell + syntax are not supported</emphasis>.</para> + + <para>The command to execute must be an absolute path name. It may + contain spaces, but control characters are not allowed.</para> + + <para>The command line accepts <literal>%</literal> specifiers as + described in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Note that the first argument of the command line (i.e. the program + to execute) may not include specifiers.</para> + + <para>Basic environment variable substitution is supported. Use + <literal>${FOO}</literal> as part of a word, or as a word of its + own, on the command line, in which case it will be replaced by the + value of the environment variable including all whitespace it + contains, resulting in a single argument. Use + <literal>$FOO</literal> as a separate word on the command line, in + which case it will be replaced by the value of the environment + variable split at whitespace, resulting in zero or more arguments. + For this type of expansion, quotes are respected when splitting + into words, and afterwards removed.</para> + + <para>Example:</para> + + <programlisting>Environment="ONE=one" 'TWO=two two' +ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> + + <para>This will execute <command>/bin/echo</command> with four + arguments: <literal>one</literal>, <literal>two</literal>, + <literal>two</literal>, and <literal>two two</literal>.</para> + + <para>Example:</para> + <programlisting>Environment=ONE='one' "TWO='two two' too" THREE= +ExecStart=/bin/echo ${ONE} ${TWO} ${THREE} +ExecStart=/bin/echo $ONE $TWO $THREE</programlisting> + <para>This results in <filename>echo</filename> being + called twice, the first time with arguments + <literal>'one'</literal>, + <literal>'two two' too</literal>, <literal></literal>, + and the second time with arguments + <literal>one</literal>, <literal>two two</literal>, + <literal>too</literal>. + </para> + + <para>To pass a literal dollar sign, use <literal>$$</literal>. + Variables whose value is not known at expansion time are treated + as empty strings. Note that the first argument (i.e. the program + to execute) may not be a variable.</para> + + <para>Variables to be used in this fashion may be defined through + <varname>Environment=</varname> and + <varname>EnvironmentFile=</varname>. In addition, variables listed + in the section "Environment variables in spawned processes" in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which are considered "static configuration", may be used (this + includes e.g. <varname>$USER</varname>, but not + <varname>$TERM</varname>).</para> + + <para>Note that shell command lines are not directly supported. If + shell command lines are to be used, they need to be passed + explicitly to a shell implementation of some kind. Example:</para> + <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting> + + <para>Example:</para> + + <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting> + + <para>This will execute <command>/bin/echo</command> two times, + each time with one argument: <literal>one</literal> and + <literal>two two</literal>, respectively. Because two commands are + specified, <varname>Type=oneshot</varname> must be used.</para> + + <para>Example:</para> + + <programlisting>ExecStart=/bin/echo / >/dev/null & \; \ +/bin/ls</programlisting> + + <para>This will execute <command>/bin/echo</command> + with five arguments: <literal>/</literal>, + <literal>>/dev/null</literal>, + <literal>&</literal>, <literal>;</literal>, and + <literal>/bin/ls</literal>.</para> + + <table> + <title>C escapes supported in command lines and environment variables</title> + <tgroup cols='2'> + <colspec colname='escape' /> + <colspec colname='meaning' /> + <thead> + <row> + <entry>Literal</entry> + <entry>Actual value</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>\a</literal></entry> + <entry>bell</entry> + </row> + <row> + <entry><literal>\b</literal></entry> + <entry>backspace</entry> + </row> + <row> + <entry><literal>\f</literal></entry> + <entry>form feed</entry> + </row> + <row> + <entry><literal>\n</literal></entry> + <entry>newline</entry> + </row> + <row> + <entry><literal>\r</literal></entry> + <entry>carriage return</entry> + </row> + <row> + <entry><literal>\t</literal></entry> + <entry>tab</entry> + </row> + <row> + <entry><literal>\v</literal></entry> + <entry>vertical tab</entry> + </row> + <row> + <entry><literal>\\</literal></entry> + <entry>backslash</entry> + </row> + <row> + <entry><literal>\"</literal></entry> + <entry>double quotation mark</entry> + </row> + <row> + <entry><literal>\'</literal></entry> + <entry>single quotation mark</entry> + </row> + <row> + <entry><literal>\s</literal></entry> + <entry>space</entry> + </row> + <row> + <entry><literal>\x<replaceable>xx</replaceable></literal></entry> + <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry> + </row> + <row> + <entry><literal>\<replaceable>nnn</replaceable></literal></entry> + <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Simple service</title> + + <para>The following unit file creates a service that will + execute <filename>/usr/sbin/foo-daemon</filename>. Since no + <varname>Type=</varname> is specified, the default + <varname>Type=</varname><option>simple</option> will be assumed. + systemd will assume the unit to be started immediately after the + program has begun executing.</para> + + <programlisting>[Unit] +Description=Foo + +[Service] +ExecStart=/usr/sbin/foo-daemon + +[Install] +WantedBy=multi-user.target</programlisting> + + <para>Note that systemd assumes here that the process started by + systemd will continue running until the service terminates. If + the program daemonizes itself (i.e. forks), please use + <varname>Type=</varname><option>forking</option> instead.</para> + + <para>Since no <varname>ExecStop=</varname> was specified, + systemd will send SIGTERM to all processes started from this + service, and after a timeout also SIGKILL. This behavior can be + modified, see + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + + <para>Note that this unit type does not include any type of + notification when a service has completed initialization. For + this, you should use other unit types, such as + <varname>Type=</varname><option>notify</option> if the service + understands systemd's notification protocol, + <varname>Type=</varname><option>forking</option> if the service + can background itself or + <varname>Type=</varname><option>dbus</option> if the unit + acquires a DBus name once initialization is complete. See + below.</para> + </example> + + <example> + <title>Oneshot service</title> + + <para>Sometimes, units should just execute an action without + keeping active processes, such as a filesystem check or a + cleanup action on boot. For this, + <varname>Type=</varname><option>oneshot</option> exists. Units + of this type will wait until the process specified terminates + and then fall back to being inactive. The following unit will + perform a cleanup action:</para> + + <programlisting>[Unit] +Description=Cleanup old Foo data + +[Service] +Type=oneshot +ExecStart=/usr/sbin/foo-cleanup + +[Install] +WantedBy=multi-user.target</programlisting> + + <para>Note that systemd will consider the unit to be in the + state "starting" until the program has terminated, so ordered + dependencies will wait for the program to finish before starting + themselves. The unit will revert to the "inactive" state after + the execution is done, never reaching the "active" state. That + means another request to start the unit will perform the action + again.</para> + + <para><varname>Type=</varname><option>oneshot</option> are the + only service units that may have more than one + <varname>ExecStart=</varname> specified. They will be executed + in order until either they are all successful or one of them + fails.</para> + </example> + + <example> + <title>Stoppable oneshot service</title> + + <para>Similarly to the oneshot services, there are sometimes + units that need to execute a program to set up something and + then execute another to shut it down, but no process remains + active while they are considered "started". Network + configuration can sometimes fall into this category. Another use + case is if a oneshot service shall not be executed each time + when they are pulled in as a dependency, but only the first + time.</para> + + <para>For this, systemd knows the setting + <varname>RemainAfterExit=</varname><option>yes</option>, which + causes systemd to consider the unit to be active if the start + action exited successfully. This directive can be used with all + types, but is most useful with + <varname>Type=</varname><option>oneshot</option> and + <varname>Type=</varname><option>simple</option>. With + <varname>Type=</varname><option>oneshot</option>, systemd waits + until the start action has completed before it considers the + unit to be active, so dependencies start only after the start + action has succeeded. With + <varname>Type=</varname><option>simple</option>, dependencies + will start immediately after the start action has been + dispatched. The following unit provides an example for a simple + static firewall.</para> + + <programlisting>[Unit] +Description=Simple firewall + +[Service] +Type=oneshot +RemainAfterExit=yes +ExecStart=/usr/local/sbin/simple-firewall-start +ExecStop=/usr/local/sbin/simple-firewall-stop + +[Install] +WantedBy=multi-user.target</programlisting> + + <para>Since the unit is considered to be running after the start + action has exited, invoking <command>systemctl start</command> + on that unit again will cause no action to be taken.</para> + </example> + + <example> + <title>Traditional forking services</title> + + <para>Many traditional daemons/services background (i.e. fork, + daemonize) themselves when starting. Set + <varname>Type=</varname><option>forking</option> in the + service's unit file to support this mode of operation. systemd + will consider the service to be in the process of initialization + while the original program is still running. Once it exits + successfully and at least a process remains (and + <varname>RemainAfterExit=</varname><option>no</option>), the + service is considered started.</para> + + <para>Often, a traditional daemon only consists of one process. + Therefore, if only one process is left after the original + process terminates, systemd will consider that process the main + process of the service. In that case, the + <varname>$MAINPID</varname> variable will be available in + <varname>ExecReload=</varname>, <varname>ExecStop=</varname>, + etc.</para> + + <para>In case more than one process remains, systemd will be + unable to determine the main process, so it will not assume + there is one. In that case, <varname>$MAINPID</varname> will not + expand to anything. However, if the process decides to write a + traditional PID file, systemd will be able to read the main PID + from there. Please set <varname>PIDFile=</varname> accordingly. + Note that the daemon should write that file before finishing + with its initialization. Otherwise, systemd might try to read the + file before it exists.</para> + + <para>The following example shows a simple daemon that forks and + just starts one process in the background:</para> + + <programlisting>[Unit] +Description=Some simple daemon + +[Service] +Type=forking +ExecStart=/usr/sbin/my-simple-daemon -d + +[Install] +WantedBy=multi-user.target</programlisting> + + <para>Please see + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on how you can influence the way systemd terminates + the service.</para> + </example> + + <example> + <title>DBus services</title> + + <para>For services that acquire a name on the DBus system bus, + use <varname>Type=</varname><option>dbus</option> and set + <varname>BusName=</varname> accordingly. The service should not + fork (daemonize). systemd will consider the service to be + initialized once the name has been acquired on the system bus. + The following example shows a typical DBus service:</para> + + <programlisting>[Unit] +Description=Simple DBus service + +[Service] +Type=dbus +BusName=org.example.simple-dbus-service +ExecStart=/usr/sbin/simple-dbus-service + +[Install] +WantedBy=multi-user.target</programlisting> + + <para>For <emphasis>bus-activatable</emphasis> services, do not + include a <literal>[Install]</literal> section in the systemd + service file, but use the <varname>SystemdService=</varname> + option in the corresponding DBus service file, for example + (<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para> + + <programlisting>[D-BUS Service] +Name=org.example.simple-dbus-service +Exec=/usr/sbin/simple-dbus-service +User=root +SystemdService=simple-dbus-service.service</programlisting> + + <para>Please see + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on how you can influence the way systemd terminates + the service.</para> + </example> + + <example> + <title>Services that notify systemd about their initialization</title> + + <para><varname>Type=</varname><option>simple</option> services + are really easy to write, but have the major disadvantage of + systemd not being able to tell when initialization of the given + service is complete. For this reason, systemd supports a simple + notification protocol that allows daemons to make systemd aware + that they are done initializing. Use + <varname>Type=</varname><option>notify</option> for this. A + typical service file for such a daemon would look like + this:</para> + + <programlisting>[Unit] +Description=Simple notifying service + +[Service] +Type=notify +ExecStart=/usr/sbin/simple-notifying-service + +[Install] +WantedBy=multi-user.target</programlisting> + + <para>Note that the daemon has to support systemd's notification + protocol, else systemd will think the service has not started yet + and kill it after a timeout. For an example of how to update + daemons to support this protocol transparently, take a look at + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + systemd will consider the unit to be in the 'starting' state + until a readiness notification has arrived.</para> + + <para>Please see + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on how you can influence the way systemd terminates + the service.</para> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.slice.xml b/src/grp-system/systemd/systemd.slice.xml new file mode 100644 index 0000000000..eee98d99ee --- /dev/null +++ b/src/grp-system/systemd/systemd.slice.xml @@ -0,0 +1,132 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2013 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.slice"> + <refentryinfo> + <title>systemd.slice</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.slice</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.slice</refname> + <refpurpose>Slice unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>slice</replaceable>.slice</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.slice</literal> encodes information about a slice which + is a concept for hierarchically managing resources of a group of + processes. This management is performed by creating a node in the + Linux Control Group (cgroup) tree. Units that manage processes + (primarily scope and service units) may be assigned to a specific + slice. For each slice, certain resource limits may be set that + apply to all processes of all units contained in that + slice. Slices are organized hierarchically in a tree. The name of + the slice encodes the location in the tree. The name consists of a + dash-separated series of names, which describes the path to the + slice from the root slice. The root slice is named, + <filename>-.slice</filename>. Example: + <filename>foo-bar.slice</filename> is a slice that is located + within <filename>foo.slice</filename>, which in turn is located in + the root slice <filename>-.slice</filename>. + </para> + + <para>Note that slice units cannot be templated, nor is possible to add multiple names to a slice unit by creating + additional symlinks to it.</para> + + <para>By default, service and scope units are placed in + <filename>system.slice</filename>, virtual machines and containers + registered with + <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>1</manvolnum></citerefentry> + are found in <filename>machine.slice</filename>, and user sessions + handled by + <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>1</manvolnum></citerefentry> + in <filename>user.slice</filename>. See + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information.</para> + + <para>See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration + files. The common configuration items are configured + in the generic [Unit] and [Install] sections. The + slice specific configuration options are configured in + the [Slice] section. Currently, only generic resource control settings + as described in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> are allowed. + </para> + + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New + Control Group Interfaces</ulink> for an introduction on how to make + use of slice units from programs.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>Slice units automatically gain dependencies of type + <varname>After=</varname> and <varname>Requires=</varname> on + their immediate parent slice unit.</para> + + <para>Unless <varname>DefaultDependencies=false</varname> is used in the <literal>[Unit]</literal> section, slice + units will implicitly have dependencies of type <varname>Conflicts=</varname> and <varname>Before=</varname> on + <filename>shutdown.target</filename>. These ensure that slice units are removed prior to system shutdown. Only + slice units involved with early boot or late system shutdown should disable this option. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.socket.xml b/src/grp-system/systemd/systemd.socket.xml new file mode 100644 index 0000000000..0ce1203cfb --- /dev/null +++ b/src/grp-system/systemd/systemd.socket.xml @@ -0,0 +1,868 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.socket"> + <refentryinfo> + <title>systemd.socket</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.socket</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.socket</refname> + <refpurpose>Socket unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>socket</replaceable>.socket</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.socket</literal> encodes information about an IPC or + network socket or a file system FIFO controlled and supervised by + systemd, for socket-based activation.</para> + + <para>This man page lists the configuration options specific to + this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic [Unit] and + [Install] sections. The socket specific configuration options are + configured in the [Socket] section.</para> + + <para>Additional options are listed in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the execution environment the + <option>ExecStartPre=</option>, <option>ExecStartPost=</option>, + <option>ExecStopPre=</option> and <option>ExecStopPost=</option> + commands are executed in, and in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the way the processes are terminated, and in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which configure resource control settings for the processes of the + socket.</para> + + <para>For each socket file, a matching service file must exist, + describing the service to start on incoming traffic on the socket + (see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information about .service files). The name of the + .service unit is by default the same as the name of the .socket + unit, but can be altered with the <option>Service=</option> option + described below. Depending on the setting of the + <option>Accept=</option> option described below, this .service + unit must either be named like the .socket unit, but with the + suffix replaced, unless overridden with <option>Service=</option>; + or it must be a template unit named the same way. Example: a + socket file <filename>foo.socket</filename> needs a matching + service <filename>foo.service</filename> if + <option>Accept=false</option> is set. If + <option>Accept=true</option> is set, a service template file + <filename>foo@.service</filename> must exist from which services + are instantiated for each incoming connection.</para> + + <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section is set to + <option>false</option>, socket units will implicitly have dependencies of type <varname>Requires=</varname> and + <varname>After=</varname> on <filename>sysinit.target</filename> as well as dependencies of type + <varname>Conflicts=</varname> and <varname>Before=</varname> on <filename>shutdown.target</filename>. These ensure + that socket units pull in basic system initialization, and are terminated cleanly prior to system shutdown. Only + sockets involved with early boot or late system shutdown should disable this option.</para> + + <para>Socket units will have a <varname>Before=</varname> + dependency on the service which they trigger added implicitly. No + implicit <varname>WantedBy=</varname> or + <varname>RequiredBy=</varname> dependency from the socket to the + service is added. This means that the service may be started + without the socket, in which case it must be able to open sockets + by itself. To prevent this, an explicit + <varname>Requires=</varname> dependency may be added.</para> + + <para>Socket units may be used to implement on-demand starting of + services, as well as parallelized starting of services. See the + blog stories linked at the end for an introduction.</para> + + <para>Note that the daemon software configured for socket + activation with socket units needs to be able to accept sockets + from systemd, either via systemd's native socket passing interface + (see + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details) or via the traditional + <citerefentry project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style + socket passing (i.e. sockets passed in via standard input and + output, using <varname>StandardInput=socket</varname> in the + service file).</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>Socket units automatically gain a <varname>Before=</varname> + dependency on the service units they activate.</para> + + <para>Socket units referring to file system paths (such as AF_UNIX + sockets or FIFOs) implicitly gain <varname>Requires=</varname> and + <varname>After=</varname> dependencies on all mount units + necessary to access those paths.</para> + + <para>Socket units using the <varname>BindToDevice=</varname> + setting automatically gain a <varname>BindsTo=</varname> and + <varname>After=</varname> dependency on the device unit + encapsulating the specified network interface.</para> + + <para>If <varname>DefaultDependencies=yes</varname> is set (the + default), socket units automatically gain a + <varname>Before=</varname> dependency on + <filename>sockets.target</filename>. They also gain a pair of + <varname>After=</varname> and <varname>Requires=</varname> + dependency on <filename>sysinit.target</filename>, and a pair of + <varname>Before=</varname> and <varname>Conflicts=</varname> + dependencies on <filename>shutdown.target</filename>. These + dependencies ensure that the socket unit is started before normal + services at boot, and is stopped on shutdown.</para> + + <para>Additional implicit dependencies may be added as result of + execution and resource control parameters as documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Socket files must include a [Socket] section, which carries + information about the socket or FIFO it supervises. A number of + options that may be used in this section are shared with other + unit types. These options are documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + The options specific to the [Socket] section of socket units are + the following:</para> + + <variablelist class='unit-directives'> + <varlistentry> + <term><varname>ListenStream=</varname></term> + <term><varname>ListenDatagram=</varname></term> + <term><varname>ListenSequentialPacket=</varname></term> + <listitem><para>Specifies an address to listen on for a stream + (<constant>SOCK_STREAM</constant>), datagram + (<constant>SOCK_DGRAM</constant>), or sequential packet + (<constant>SOCK_SEQPACKET</constant>) socket, respectively. + The address can be written in various formats:</para> + + <para>If the address starts with a slash + (<literal>/</literal>), it is read as file system socket in + the <constant>AF_UNIX</constant> socket family.</para> + + <para>If the address starts with an at symbol + (<literal>@</literal>), it is read as abstract namespace + socket in the <constant>AF_UNIX</constant> family. The + <literal>@</literal> is replaced with a + <constant>NUL</constant> character before binding. For + details, see + <citerefentry project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>If the address string is a single number, it is read as + port number to listen on via IPv6. Depending on the value of + <varname>BindIPv6Only=</varname> (see below) this might result + in the service being available via both IPv6 and IPv4 + (default) or just via IPv6. + </para> + + <para>If the address string is a string in the format + v.w.x.y:z, it is read as IPv4 specifier for listening on an + address v.w.x.y on a port z.</para> + + <para>If the address string is a string in the format [x]:y, + it is read as IPv6 address x on a port y. Note that this might + make the service available via IPv4, too, depending on the + <varname>BindIPv6Only=</varname> setting (see below). + </para> + + <para>Note that <constant>SOCK_SEQPACKET</constant> (i.e. + <varname>ListenSequentialPacket=</varname>) is only available + for <constant>AF_UNIX</constant> sockets. + <constant>SOCK_STREAM</constant> (i.e. + <varname>ListenStream=</varname>) when used for IP sockets + refers to TCP sockets, <constant>SOCK_DGRAM</constant> (i.e. + <varname>ListenDatagram=</varname>) to UDP.</para> + + <para>These options may be specified more than once, in which + case incoming traffic on any of the sockets will trigger + service activation, and all listed sockets will be passed to + the service, regardless of whether there is incoming traffic + on them or not. If the empty string is assigned to any of + these options, the list of addresses to listen on is reset, + all prior uses of any of these options will have no + effect.</para> + + <para>It is also possible to have more than one socket unit + for the same service when using <varname>Service=</varname>, + and the service will receive all the sockets configured in all + the socket units. Sockets configured in one unit are passed in + the order of configuration, but no ordering between socket + units is specified.</para> + + <para>If an IP address is used here, it is often desirable to + listen on it before the interface it is configured on is up + and running, and even regardless of whether it will be up and + running at any point. To deal with this, it is recommended to + set the <varname>FreeBind=</varname> option described + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ListenFIFO=</varname></term> + <listitem><para>Specifies a file system FIFO to listen on. + This expects an absolute file system path as argument. + Behavior otherwise is very similar to the + <varname>ListenDatagram=</varname> directive + above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ListenSpecial=</varname></term> + <listitem><para>Specifies a special file in the file system to + listen on. This expects an absolute file system path as + argument. Behavior otherwise is very similar to the + <varname>ListenFIFO=</varname> directive above. Use this to + open character device nodes as well as special files in + <filename>/proc</filename> and + <filename>/sys</filename>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ListenNetlink=</varname></term> + <listitem><para>Specifies a Netlink family to create a socket + for to listen on. This expects a short string referring to the + <constant>AF_NETLINK</constant> family name (such as + <varname>audit</varname> or <varname>kobject-uevent</varname>) + as argument, optionally suffixed by a whitespace followed by a + multicast group integer. Behavior otherwise is very similar to + the <varname>ListenDatagram=</varname> directive + above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ListenMessageQueue=</varname></term> + <listitem><para>Specifies a POSIX message queue name to listen + on. This expects a valid message queue name (i.e. beginning + with /). Behavior otherwise is very similar to the + <varname>ListenFIFO=</varname> directive above. On Linux + message queue descriptors are actually file descriptors and + can be inherited between processes.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ListenUSBFunction=</varname></term> + <listitem><para>Specifies a <ulink + url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB + FunctionFS</ulink> endpoints location to listen on, for + implementation of USB gadget functions. This expects an + absolute file system path of functionfs mount point as the argument. + Behavior otherwise is very similar to the <varname>ListenFIFO=</varname> + directive above. Use this to open the FunctionFS endpoint + <filename>ep0</filename>. When using this option, the + activated service has to have the + <varname>USBFunctionDescriptors=</varname> and + <varname>USBFunctionStrings=</varname> options set. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SocketProtocol=</varname></term> + <listitem><para>Takes a one of <option>udplite</option> + or <option>sctp</option>. Specifies a socket protocol + (<constant>IPPROTO_UDPLITE</constant>) UDP-Lite + (<constant>IPPROTO_SCTP</constant>) SCTP socket respectively. </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>BindIPv6Only=</varname></term> + <listitem><para>Takes a one of <option>default</option>, + <option>both</option> or <option>ipv6-only</option>. Controls + the IPV6_V6ONLY socket option (see + <citerefentry project='die-net'><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). If <option>both</option>, IPv6 sockets bound + will be accessible via both IPv4 and IPv6. If + <option>ipv6-only</option>, they will be accessible via IPv6 + only. If <option>default</option> (which is the default, + surprise!), the system wide default setting is used, as + controlled by + <filename>/proc/sys/net/ipv6/bindv6only</filename>, which in + turn defaults to the equivalent of + <option>both</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>Backlog=</varname></term> + <listitem><para>Takes an unsigned integer argument. Specifies + the number of connections to queue that have not been accepted + yet. This setting matters only for stream and sequential + packet sockets. See + <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. Defaults to SOMAXCONN (128).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>BindToDevice=</varname></term> + <listitem><para>Specifies a network interface name to bind + this socket to. If set, traffic will only be accepted from the + specified network interfaces. This controls the + SO_BINDTODEVICE socket option (see <citerefentry + project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). If this option is used, an automatic dependency + from this socket unit on the network interface device unit + (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> + is created. Note that setting this parameter might result in + additional dependencies to be added to the unit (see + above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SocketUser=</varname></term> + <term><varname>SocketGroup=</varname></term> + + <listitem><para>Takes a UNIX user/group name. When specified, + all AF_UNIX sockets and FIFO nodes in the file system are + owned by the specified user and group. If unset (the default), + the nodes are owned by the root user/group (if run in system + context) or the invoking user/group (if run in user context). + If only a user is specified but no group, then the group is + derived from the user's default group.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SocketMode=</varname></term> + <listitem><para>If listening on a file system socket or FIFO, + this option specifies the file system access mode used when + creating the file node. Takes an access mode in octal + notation. Defaults to 0666.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DirectoryMode=</varname></term> + <listitem><para>If listening on a file system socket or FIFO, + the parent directories are automatically created if needed. + This option specifies the file system access mode used when + creating these directories. Takes an access mode in octal + notation. Defaults to 0755.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Accept=</varname></term> + <listitem><para>Takes a boolean argument. If true, a service + instance is spawned for each incoming connection and only the + connection socket is passed to it. If false, all listening + sockets themselves are passed to the started service unit, and + only one service unit is spawned for all connections (also see + above). This value is ignored for datagram sockets and FIFOs + where a single service unit unconditionally handles all + incoming traffic. Defaults to <option>false</option>. For + performance reasons, it is recommended to write new daemons + only in a way that is suitable for + <option>Accept=false</option>. A daemon listening on an + <constant>AF_UNIX</constant> socket may, but does not need to, + call + <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry> + on the received socket before exiting. However, it must not + unlink the socket from a file system. It should not invoke + <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry> + on sockets it got with <varname>Accept=false</varname>, but it + may do so for sockets it got with + <varname>Accept=true</varname> set. Setting + <varname>Accept=true</varname> is mostly useful to allow + daemons designed for usage with + <citerefentry project='freebsd'><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + to work unmodified with systemd socket + activation.</para> + + <para>For IPv4 and IPv6 connections, the <varname>REMOTE_ADDR</varname> + environment variable will contain the remote IP address, and <varname>REMOTE_PORT</varname> + will contain the remote port. This is the same as the format used by CGI. + For SOCK_RAW, the port is the IP protocol.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Writable=</varname></term> + <listitem><para>Takes a boolean argument. May only be used in + conjunction with <varname>ListenSpecial=</varname>. If true, + the specified special file is opened in read-write mode, if + false, in read-only mode. Defaults to false.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MaxConnections=</varname></term> + <listitem><para>The maximum number of connections to + simultaneously run services instances for, when + <option>Accept=true</option> is set. If more concurrent + connections are coming in, they will be refused until at least + one existing connection is terminated. This setting has no + effect on sockets configured with + <option>Accept=false</option> or datagram sockets. Defaults to + 64.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MaxConnectionsPerSource=</varname></term> + <listitem><para>The maximum number of connections for a service per source IP address. + This is very similar to the <varname>MaxConnections=</varname> directive + above. Disabled by default.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>KeepAlive=</varname></term> + <listitem><para>Takes a boolean argument. If true, the TCP/IP + stack will send a keep alive message after 2h (depending on + the configuration of + <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>) + for all TCP streams accepted on this socket. This controls the + SO_KEEPALIVE socket option (see + <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and the <ulink + url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP + Keepalive HOWTO</ulink> for details.) Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KeepAliveTimeSec=</varname></term> + <listitem><para>Takes time (in seconds) as argument. The connection needs to remain + idle before TCP starts sending keepalive probes. This controls the TCP_KEEPIDLE + socket option (see + <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and the <ulink + url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP + Keepalive HOWTO</ulink> for details.) + Defaults value is 7200 seconds (2 hours).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KeepAliveIntervalSec=</varname></term> + <listitem><para>Takes time (in seconds) as argument between + individual keepalive probes, if the socket option SO_KEEPALIVE + has been set on this socket. This controls + the TCP_KEEPINTVL socket option (see + <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and the <ulink + url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP + Keepalive HOWTO</ulink> for details.) Defaults value is 75 + seconds.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KeepAliveProbes=</varname></term> + <listitem><para>Takes an integer as argument. It is the number of + unacknowledged probes to send before considering the + connection dead and notifying the application layer. This + controls the TCP_KEEPCNT socket option (see + <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and the <ulink + url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP + Keepalive HOWTO</ulink> for details.) Defaults value is + 9.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>NoDelay=</varname></term> + <listitem><para>Takes a boolean argument. TCP Nagle's + algorithm works by combining a number of small outgoing + messages, and sending them all at once. This controls the + TCP_NODELAY socket option (see + <citerefentry project='die-net'><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry> + Defaults to <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Priority=</varname></term> + <listitem><para>Takes an integer argument controlling the + priority for all traffic sent from this socket. This controls + the SO_PRIORITY socket option (see + <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DeferAcceptSec=</varname></term> + + <listitem><para>Takes time (in seconds) as argument. If set, + the listening process will be awakened only when data arrives + on the socket, and not immediately when connection is + established. When this option is set, the + <constant>TCP_DEFER_ACCEPT</constant> socket option will be + used (see + <citerefentry project='die-net'><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry>), + and the kernel will ignore initial ACK packets without any + data. The argument specifies the approximate amount of time + the kernel should wait for incoming data before falling back + to the normal behavior of honoring empty ACK packets. This + option is beneficial for protocols where the client sends the + data first (e.g. HTTP, in contrast to SMTP), because the + server process will not be woken up unnecessarily before it + can take any action. + </para> + + <para>If the client also uses the + <constant>TCP_DEFER_ACCEPT</constant> option, the latency of + the initial connection may be reduced, because the kernel will + send data in the final packet establishing the connection (the + third packet in the "three-way handshake").</para> + + <para>Disabled by default.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ReceiveBuffer=</varname></term> + <term><varname>SendBuffer=</varname></term> + <listitem><para>Takes an integer argument controlling the + receive or send buffer sizes of this socket, respectively. + This controls the SO_RCVBUF and SO_SNDBUF socket options (see + <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.). The usual suffixes K, M, G are supported and + are understood to the base of 1024.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IPTOS=</varname></term> + <listitem><para>Takes an integer argument controlling the IP + Type-Of-Service field for packets generated from this socket. + This controls the IP_TOS socket option (see + <citerefentry project='die-net'><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.). Either a numeric string or one of + <option>low-delay</option>, <option>throughput</option>, + <option>reliability</option> or <option>low-cost</option> may + be specified.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IPTTL=</varname></term> + <listitem><para>Takes an integer argument controlling the IPv4 + Time-To-Live/IPv6 Hop-Count field for packets generated from + this socket. This sets the IP_TTL/IPV6_UNICAST_HOPS socket + options (see + <citerefentry project='die-net'><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and + <citerefentry project='die-net'><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.)</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Mark=</varname></term> + <listitem><para>Takes an integer value. Controls the firewall + mark of packets generated by this socket. This can be used in + the firewall logic to filter packets from this socket. This + sets the SO_MARK socket option. See + <citerefentry project='die-net'><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ReusePort=</varname></term> + <listitem><para>Takes a boolean value. If true, allows + multiple + <citerefentry><refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum></citerefentry>s + to this TCP or UDP port. This controls the SO_REUSEPORT socket + option. See + <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SmackLabel=</varname></term> + <term><varname>SmackLabelIPIn=</varname></term> + <term><varname>SmackLabelIPOut=</varname></term> + <listitem><para>Takes a string value. Controls the extended + attributes <literal>security.SMACK64</literal>, + <literal>security.SMACK64IPIN</literal> and + <literal>security.SMACK64IPOUT</literal>, respectively, i.e. + the security label of the FIFO, or the security label for the + incoming or outgoing connections of the socket, respectively. + See <ulink + url="https://www.kernel.org/doc/Documentation/security/Smack.txt">Smack.txt</ulink> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SELinuxContextFromNet=</varname></term> + <listitem><para>Takes a boolean argument. When true, systemd + will attempt to figure out the SELinux label used for the + instantiated service from the information handed by the peer + over the network. Note that only the security level is used + from the information provided by the peer. Other parts of the + resulting SELinux context originate from either the target + binary that is effectively triggered by socket unit or from + the value of the <varname>SELinuxContext=</varname> option. + This configuration option only affects sockets with + <varname>Accept=</varname> mode set to + <literal>true</literal>. Also note that this option is useful + only when MLS/MCS SELinux policy is deployed. Defaults to + <literal>false</literal>. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PipeSize=</varname></term> + <listitem><para>Takes a size in bytes. Controls the pipe + buffer size of FIFOs configured in this socket unit. See + <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. The usual suffixes K, M, G are supported and are + understood to the base of 1024.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MessageQueueMaxMessages=</varname>, + <varname>MessageQueueMessageSize=</varname></term> + <listitem><para>These two settings take integer values and + control the mq_maxmsg field or the mq_msgsize field, + respectively, when creating the message queue. Note that + either none or both of these variables need to be set. See + <citerefentry project='die-net'><refentrytitle>mq_setattr</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FreeBind=</varname></term> + <listitem><para>Takes a boolean value. Controls whether the + socket can be bound to non-local IP addresses. This is useful + to configure sockets listening on specific IP addresses before + those IP addresses are successfully configured on a network + interface. This sets the IP_FREEBIND socket option. For + robustness reasons it is recommended to use this option + whenever you bind a socket to a specific IP address. Defaults + to <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Transparent=</varname></term> + <listitem><para>Takes a boolean value. Controls the + IP_TRANSPARENT socket option. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Broadcast=</varname></term> + <listitem><para>Takes a boolean value. This controls the + SO_BROADCAST socket option, which allows broadcast datagrams + to be sent from this socket. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PassCredentials=</varname></term> + <listitem><para>Takes a boolean value. This controls the + SO_PASSCRED socket option, which allows + <constant>AF_UNIX</constant> sockets to receive the + credentials of the sending process in an ancillary message. + Defaults to <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PassSecurity=</varname></term> + <listitem><para>Takes a boolean value. This controls the + SO_PASSSEC socket option, which allows + <constant>AF_UNIX</constant> sockets to receive the security + context of the sending process in an ancillary message. + Defaults to <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TCPCongestion=</varname></term> + <listitem><para>Takes a string value. Controls the TCP + congestion algorithm used by this socket. Should be one of + "westwood", "veno", "cubic", "lp" or any other available + algorithm supported by the IP stack. This setting applies only + to stream sockets.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStartPre=</varname></term> + <term><varname>ExecStartPost=</varname></term> + <listitem><para>Takes one or more command lines, which are + executed before or after the listening sockets/FIFOs are + created and bound, respectively. The first token of the + command line must be an absolute filename, then followed by + arguments for the process. Multiple command lines may be + specified following the same scheme as used for + <varname>ExecStartPre=</varname> of service unit + files.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStopPre=</varname></term> + <term><varname>ExecStopPost=</varname></term> + <listitem><para>Additional commands that are executed before + or after the listening sockets/FIFOs are closed and removed, + respectively. Multiple command lines may be specified + following the same scheme as used for + <varname>ExecStartPre=</varname> of service unit + files.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutSec=</varname></term> + <listitem><para>Configures the time to wait for the commands + specified in <varname>ExecStartPre=</varname>, + <varname>ExecStartPost=</varname>, + <varname>ExecStopPre=</varname> and + <varname>ExecStopPost=</varname> to finish. If a command does + not exit within the configured time, the socket will be + considered failed and be shut down again. All commands still + running will be terminated forcibly via + <constant>SIGTERM</constant>, and after another delay of this + time with <constant>SIGKILL</constant>. (See + <option>KillMode=</option> in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.) + Takes a unit-less value in seconds, or a time span value such + as "5min 20s". Pass <literal>0</literal> to disable the + timeout logic. Defaults to + <varname>DefaultTimeoutStartSec=</varname> from the manager + configuration file (see + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Service=</varname></term> + <listitem><para>Specifies the service unit name to activate on + incoming traffic. This setting is only allowed for sockets + with <varname>Accept=no</varname>. It defaults to the service + that bears the same name as the socket (with the suffix + replaced). In most cases, it should not be necessary to use + this option. Note that setting this parameter might result in + additional dependencies to be added to the unit (see + above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RemoveOnStop=</varname></term> + <listitem><para>Takes a boolean argument. If enabled, any file + nodes created by this socket unit are removed when it is + stopped. This applies to AF_UNIX sockets in the file system, + POSIX message queues, FIFOs, as well as any symlinks to them + configured with <varname>Symlinks=</varname>. Normally, it + should not be necessary to use this option, and is not + recommended as services might continue to run after the socket + unit has been terminated and it should still be possible to + communicate with them via their file system node. Defaults to + off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Symlinks=</varname></term> + <listitem><para>Takes a list of file system paths. The + specified paths will be created as symlinks to the AF_UNIX + socket path or FIFO path of this socket unit. If this setting + is used, only one AF_UNIX socket in the file system or one + FIFO may be configured for the socket unit. Use this option to + manage one or more symlinked alias names for a socket, binding + their lifecycle together. Defaults to the empty + list.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FileDescriptorName=</varname></term> + <listitem><para>Assigns a name to all file descriptors this + socket unit encapsulates. This is useful to help activated + services identify specific file descriptors, if multiple fds + are passed. Services may use the + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call to acquire the names configured for the received file + descriptors. Names may contain any ASCII character, but must + exclude control characters and <literal>:</literal>, and must + be at most 255 characters in length. If this setting is not + used, the file descriptor name defaults to the name of the + socket unit, including its <filename>.socket</filename> + suffix.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TriggerLimitIntervalSec=</varname></term> + <term><varname>TriggerLimitBurst=</varname></term> + + <listitem><para>Configures a limit on how often this socket unit my be activated within a specific time + interval. The <varname>TriggerLimitIntervalSec=</varname> may be used to configure the length of the time + interval in the usual time units <literal>us</literal>, <literal>ms</literal>, <literal>s</literal>, + <literal>min</literal>, <literal>h</literal>, … and defaults to 2s (See + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details on + the various time units understood). The <varname>TriggerLimitBurst=</varname> setting takes a positive integer + value and specifies the number of permitted activations per time interval, and defaults to 200 for + <varname>Accept=yes</varname> sockets (thus by default permitting 200 activations per 2s), and 20 otherwise (20 + activations per 2s). Set either to 0 to disable any form of trigger rate limiting. If the limit is hit, the + socket unit is placed into a failure mode, and will not be connectible anymore until restarted. Note that this + limit is enforced before the service activation is enqueued.</para></listitem> + </varlistentry> + + </variablelist> + + <para>Check + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more settings.</para> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + <para> + For more extensive descriptions see the "systemd for Developers" series: + <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>, + <ulink url="http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink>, + <ulink url="http://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink>, + <ulink url="http://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers</ulink>. + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.special.xml b/src/grp-system/systemd/systemd.special.xml new file mode 100644 index 0000000000..d977298cd8 --- /dev/null +++ b/src/grp-system/systemd/systemd.special.xml @@ -0,0 +1,1005 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.special"> + + <refentryinfo> + <title>systemd.special</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.special</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.special</refname> + <refpurpose>Special systemd units</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>basic.target</filename>, + <filename>bluetooth.target</filename>, + <filename>ctrl-alt-del.target</filename>, + <filename>cryptsetup.target</filename>, + <filename>cryptsetup-pre.target</filename>, + <filename>dbus.service</filename>, + <filename>dbus.socket</filename>, + <filename>default.target</filename>, + <filename>display-manager.service</filename>, + <filename>emergency.target</filename>, + <filename>exit.target</filename>, + <filename>final.target</filename>, + <filename>getty.target</filename>, + <filename>graphical.target</filename>, + <filename>halt.target</filename>, + <filename>hibernate.target</filename>, + <filename>hybrid-sleep.target</filename>, + <filename>initrd-fs.target</filename>, + <filename>kbrequest.target</filename>, + <filename>kexec.target</filename>, + <filename>local-fs.target</filename>, + <filename>local-fs-pre.target</filename>, + <filename>multi-user.target</filename>, + <filename>network.target</filename>, + <filename>network-online.target</filename>, + <filename>network-pre.target</filename>, + <filename>nss-lookup.target</filename>, + <filename>nss-user-lookup.target</filename>, + <filename>paths.target</filename>, + <filename>poweroff.target</filename>, + <filename>printer.target</filename>, + <filename>reboot.target</filename>, + <filename>remote-fs.target</filename>, + <filename>remote-fs-pre.target</filename>, + <filename>rescue.target</filename>, + <filename>initrd-root-device.target</filename>, + <filename>initrd-root-fs.target</filename>, + <filename>rpcbind.target</filename>, + <filename>runlevel2.target</filename>, + <filename>runlevel3.target</filename>, + <filename>runlevel4.target</filename>, + <filename>runlevel5.target</filename>, + <filename>shutdown.target</filename>, + <filename>sigpwr.target</filename>, + <filename>sleep.target</filename>, + <filename>slices.target</filename>, + <filename>smartcard.target</filename>, + <filename>sockets.target</filename>, + <filename>sound.target</filename>, + <filename>suspend.target</filename>, + <filename>swap.target</filename>, + <filename>sysinit.target</filename>, + <filename>syslog.socket</filename>, + <filename>system-update.target</filename>, + <filename>time-sync.target</filename>, + <filename>timers.target</filename>, + <filename>umount.target</filename>, + <filename>-.slice</filename>, + <filename>system.slice</filename>, + <filename>user.slice</filename>, + <filename>machine.slice</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A few units are treated specially by systemd. They have + special internal semantics and cannot be renamed.</para> + </refsect1> + + <refsect1> + <title>Special System Units</title> + + <variablelist> + <varlistentry> + <term><filename>basic.target</filename></term> + <listitem> + <para>A special target unit covering basic boot-up.</para> + + <para>systemd automatically adds dependency of the type + <varname>After=</varname> for this target unit to all + services (except for those with + <varname>DefaultDependencies=no</varname>).</para> + + <para>Usually, this should pull-in all local mount points plus + <filename>/var</filename>, <filename>/tmp</filename> and + <filename>/var/tmp</filename>, swap devices, sockets, timers, + path units and other basic initialization necessary for general + purpose daemons. The mentioned mount points are special cased + to allow them to be remote. + </para> + + <para>This target usually does not pull in any non-target units + directly, but rather does so indirectly via other early boot targets. + It is instead meant as a synchronization point for late boot + services. Refer to + <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details on the targets involved. + </para> + + </listitem> + </varlistentry> + <varlistentry> + <term><filename>ctrl-alt-del.target</filename></term> + <listitem> + <para>systemd starts this target whenever Control+Alt+Del is + pressed on the console. Usually, this should be aliased + (symlinked) to <filename>reboot.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>cryptsetup.target</filename></term> + <listitem> + <para>A target that pulls in setup services for all + encrypted block devices.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>dbus.service</filename></term> + <listitem> + <para>A special unit for the D-Bus bus daemon. As soon as + this service is fully started up systemd will connect to it + and register its service.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>dbus.socket</filename></term> + <listitem> + <para>A special unit for the D-Bus system bus socket. All + units with <varname>Type=dbus</varname> automatically gain a + dependency on this unit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>default.target</filename></term> + <listitem> + <para>The default unit systemd starts at bootup. Usually, + this should be aliased (symlinked) to + <filename>multi-user.target</filename> or + <filename>graphical.target</filename>.</para> + + <para>The default unit systemd starts at bootup can be + overridden with the <varname>systemd.unit=</varname> kernel + command line option.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>display-manager.service</filename></term> + <listitem> + <para>The display manager service. Usually, this should be + aliased (symlinked) to <filename>gdm.service</filename> or a + similar display manager service.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>emergency.target</filename></term> + <listitem> + <para>A special target unit that starts an emergency shell on the main console. This target does not pull in + any services or mounts. It is the most minimal version of starting the system in order to acquire an + interactive shell; the only processes running are usually just the system manager (PID 1) and the shell + process. This unit is supposed to be used with the kernel command line option + <varname>systemd.unit=</varname>; it is also used when a file system check on a required file system fails, + and boot-up cannot continue. Compare with <filename>rescue.target</filename>, which serves a similar purpose, + but also starts the most basic services and mounts all file systems.</para> + + <para>Use the <literal>systemd.unit=emergency.target</literal> kernel command line option to boot into this + mode. A short alias for this kernel command line option is <literal>emergency</literal>, for compatibility + with SysV.</para> + + <para>In many ways booting into <filename>emergency.target</filename> is similar to the effect of booting + with <literal>init=/bin/sh</literal> on the kernel command line, except that emergency mode provides you with + the full system and service manager, and allows starting individual units in order to continue the boot + process in steps.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>exit.target</filename></term> + <listitem> + <para>A special service unit for shutting down the system or + user service manager. It is equivalent to + <filename>poweroff.target</filename> on non-container + systems, and also works in containers.</para> + + <para>systemd will start this unit when it receives a + request to shut down over D-Bus or a + <constant>SIGTERM</constant> or <constant>SIGINT</constant> + signal when running as user service daemon.</para> + + <para>Normally, this (indirectly) pulls in + <filename>shutdown.target</filename>, which in turn should be + conflicted by all units that want to be scheduled for + shutdown when the service manager starts to exit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>final.target</filename></term> + <listitem> + <para>A special target unit that is used during the shutdown + logic and may be used to pull in late services after all + normal services are already terminated and all mounts + unmounted. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>getty.target</filename></term> + <listitem> + <para>A special target unit that pulls in statically + configured local TTY <filename>getty</filename> instances. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>graphical.target</filename></term> + <listitem> + <para>A special target unit for setting up a graphical login + screen. This pulls in + <filename>multi-user.target</filename>.</para> + + <para>Units that are needed for graphical logins shall add + <varname>Wants=</varname> dependencies for their unit to + this unit (or <filename>multi-user.target</filename>) during + installation. This is best configured via + <varname>WantedBy=graphical.target</varname> in the unit's + <literal>[Install]</literal> section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>hibernate.target</filename></term> + <listitem> + <para>A special target unit for hibernating the system. This + pulls in <filename>sleep.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>hybrid-sleep.target</filename></term> + <listitem> + <para>A special target unit for hibernating and suspending + the system at the same time. This pulls in + <filename>sleep.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>halt.target</filename></term> + <listitem> + <para>A special target unit for shutting down and halting + the system. Note that this target is distinct from + <filename>poweroff.target</filename> in that it generally + really just halts the system rather than powering it + down.</para> + + <para>Applications wanting to halt the system should start + this unit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>initrd-fs.target</filename></term> + <listitem> + <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> + automatically adds dependencies of type + <varname>Before=</varname> to + <filename>sysroot-usr.mount</filename> and all mount points + found in <filename>/etc/fstab</filename> that have + <option>x-initrd.mount</option> and not have + <option>noauto</option> mount options set.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>kbrequest.target</filename></term> + <listitem> + <para>systemd starts this target whenever Alt+ArrowUp is + pressed on the console. This is a good candidate to be + aliased (symlinked) to + <filename>rescue.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>kexec.target</filename></term> + <listitem> + <para>A special target unit for shutting down and rebooting + the system via kexec.</para> + + <para>Applications wanting to reboot the system with kexec + should start this unit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>local-fs.target</filename></term> + <listitem> + <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> + automatically adds dependencies of type + <varname>Before=</varname> to all mount units that refer to + local mount points for this target unit. In addition, it + adds dependencies of type <varname>Wants=</varname> to this + target unit for those mounts listed in + <filename>/etc/fstab</filename> that have the + <option>auto</option> mount option set.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>multi-user.target</filename></term> + <listitem> + <para>A special target unit for setting up a multi-user + system (non-graphical). This is pulled in by + <filename>graphical.target</filename>.</para> + + <para>Units that are needed for a multi-user system shall + add <varname>Wants=</varname> dependencies for their unit to + this unit during installation. This is best configured via + <varname>WantedBy=multi-user.target</varname> in the unit's + <literal>[Install]</literal> section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>network-online.target</filename></term> + <listitem> + <para>Units that strictly require a configured network + connection should pull in + <filename>network-online.target</filename> (via a + <varname>Wants=</varname> type dependency) and order + themselves after it. This target unit is intended to pull in + a service that delays further execution until the network is + sufficiently set up. What precisely this requires is left to + the implementation of the network managing service.</para> + + <para>Note the distinction between this unit and + <filename>network.target</filename>. This unit is an active + unit (i.e. pulled in by the consumer rather than the + provider of this functionality) and pulls in a service which + possibly adds substantial delays to further execution. In + contrast, <filename>network.target</filename> is a passive + unit (i.e. pulled in by the provider of the functionality, + rather than the consumer) that usually does not delay + execution much. Usually, <filename>network.target</filename> + is part of the boot of most systems, while + <filename>network-online.target</filename> is not, except + when at least one unit requires it. Also see <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running + Services After the Network is up</ulink> for more + information.</para> + + <para>All mount units for remote network file systems + automatically pull in this unit, and order themselves after + it. Note that networking daemons that simply provide + functionality to other hosts generally do not need to pull + this in.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>paths.target</filename></term> + <listitem> + <para>A special target unit that sets up all path units (see + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) that shall be active after boot.</para> + + <para>It is recommended that path units installed by + applications get pulled in via <varname>Wants=</varname> + dependencies from this unit. This is best configured via a + <varname>WantedBy=paths.target</varname> in the path unit's + <literal>[Install]</literal> section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>poweroff.target</filename></term> + <listitem> + <para>A special target unit for shutting down and powering + off the system.</para> + + <para>Applications wanting to power off the system should + start this unit.</para> + + <para><filename>runlevel0.target</filename> is an alias for + this target unit, for compatibility with SysV.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>reboot.target</filename></term> + <listitem> + <para>A special target unit for shutting down and rebooting + the system.</para> + + <para>Applications wanting to reboot the system should start + this unit.</para> + + <para><filename>runlevel6.target</filename> is an alias for + this target unit, for compatibility with SysV.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>remote-fs.target</filename></term> + <listitem> + <para>Similar to <filename>local-fs.target</filename>, but + for remote mount points.</para> + + <para>systemd automatically adds dependencies of type + <varname>After=</varname> for this target unit to all SysV + init script service units with an LSB header referring to + the <literal>$remote_fs</literal> facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>rescue.target</filename></term> + <listitem> + <para>A special target unit that pulls in the base system (including system mounts) and spawns a rescue + shell. Isolate to this target in order to administer the system in single-user mode with all file systems + mounted but with no services running, except for the most basic. Compare with + <filename>emergency.target</filename>, which is much more reduced and does not provide the file systems or + most basic services.</para> + + <para><filename>runlevel1.target</filename> is an alias for this target unit, for compatibility with + SysV.</para> + + <para>Use the <literal>systemd.unit=rescue.target</literal> kernel command line option to boot into this + mode. A short alias for this kernel command line option is <literal>1</literal>, for compatibility with + SysV.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>initrd-root-device.target</filename></term> + <listitem> + <para>A special initrd target unit that is reached when the root filesystem device is available, but before + it has been mounted. + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> + automatically setup the appropriate dependencies to make this happen. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>initrd-root-fs.target</filename></term> + <listitem> + <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> + automatically adds dependencies of type + <varname>Before=</varname> to the + <filename>sysroot.mount</filename> unit, which is generated + from the kernel command line. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>runlevel2.target</filename></term> + <term><filename>runlevel3.target</filename></term> + <term><filename>runlevel4.target</filename></term> + <term><filename>runlevel5.target</filename></term> + <listitem> + <para>These are targets that are called whenever the SysV + compatibility code asks for runlevel 2, 3, 4, 5, + respectively. It is a good idea to make this an alias for + (i.e. symlink to) <filename>graphical.target</filename> + (for runlevel 5) or <filename>multi-user.target</filename> + (the others).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>shutdown.target</filename></term> + <listitem> + <para>A special target unit that terminates the services on + system shutdown.</para> + + <para>Services that shall be terminated on system shutdown + shall add <varname>Conflicts=</varname> and + <varname>Before=</varname> dependencies to this unit for + their service unit, which is implicitly done when + <varname>DefaultDependencies=yes</varname> is set (the + default).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sigpwr.target</filename></term> + <listitem> + <para>A special target that is started when systemd receives + the SIGPWR process signal, which is normally sent by the + kernel or UPS daemons when power fails.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sleep.target</filename></term> + <listitem> + <para>A special target unit that is pulled in by + <filename>suspend.target</filename>, + <filename>hibernate.target</filename> and + <filename>hybrid-sleep.target</filename> and may be used to + hook units into the sleep state logic.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>slices.target</filename></term> + <listitem> + <para>A special target unit that sets up all slice units (see + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + details) that shall be active after boot. By default the generic <filename>user.slice</filename>, + <filename>system.slice</filename>, <filename>machines.slice</filename> slice units, as well as the root + slice unit <filename>-.slice</filename> are pulled in and ordered before this unit (see below).</para> + + <para>It's a good idea to add <varname>WantedBy=slices.target</varname> lines to the <literal>[Install]</literal> + section of all slices units that may be installed dynamically.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sockets.target</filename></term> + <listitem> + <para>A special target unit that sets up all socket + units (see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) that shall be active after boot.</para> + + <para>Services that can be socket-activated shall add + <varname>Wants=</varname> dependencies to this unit for + their socket unit during installation. This is best + configured via a <varname>WantedBy=sockets.target</varname> + in the socket unit's <literal>[Install]</literal> + section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>suspend.target</filename></term> + <listitem> + <para>A special target unit for suspending the system. This + pulls in <filename>sleep.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>swap.target</filename></term> + <listitem> + <para>Similar to <filename>local-fs.target</filename>, but + for swap partitions and swap files.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sysinit.target</filename></term> + <listitem> + <para>systemd automatically adds dependencies of the types + <varname>Requires=</varname> and <varname>After=</varname> + for this target unit to all services (except for those with + <varname>DefaultDependencies=no</varname>).</para> + + <para>This target pulls in the services required for system + initialization. System services pulled in by this target should + declare <varname>DefaultDependencies=no</varname> and specify + all their dependencies manually, including access to anything + more than a read only root filesystem. For details on the + dependencies of this target, refer to + <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>syslog.socket</filename></term> + <listitem> + <para>The socket unit syslog implementations should listen + on. All userspace log messages will be made available on + this socket. For more information about syslog integration, + please consult the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/syslog">Syslog + Interface</ulink> document.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>system-update.target</filename></term> + <listitem> + <para>A special target unit that is used for off-line system + updates. + <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + will redirect the boot process to this target if + <filename>/system-update</filename> exists. For more + information see the <ulink + url="http://freedesktop.org/wiki/Software/systemd/SystemUpdates">System + Updates Specification</ulink>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>timers.target</filename></term> + <listitem> + <para>A special target unit that sets up all timer units + (see + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) that shall be active after boot.</para> + + <para>It is recommended that timer units installed by + applications get pulled in via <varname>Wants=</varname> + dependencies from this unit. This is best configured via + <varname>WantedBy=timers.target</varname> in the timer + unit's <literal>[Install]</literal> section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>umount.target</filename></term> + <listitem> + <para>A special target unit that unmounts all mount and + automount points on system shutdown.</para> + + <para>Mounts that shall be unmounted on system shutdown + shall add Conflicts dependencies to this unit for their + mount unit, which is implicitly done when + <varname>DefaultDependencies=yes</varname> is set (the + default).</para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Special System Units for Devices</title> + + <para>Some target units are automatically pulled in as devices of + certain kinds show up in the system. These may be used to + automatically activate various services based on the specific type + of the available hardware.</para> + + <variablelist> + <varlistentry> + <term><filename>bluetooth.target</filename></term> + <listitem> + <para>This target is started automatically as soon as a + Bluetooth controller is plugged in or becomes available at + boot.</para> + + <para>This may be used to pull in Bluetooth management + daemons dynamically when Bluetooth hardware is found.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>printer.target</filename></term> + <listitem> + <para>This target is started automatically as soon as a + printer is plugged in or becomes available at boot.</para> + + <para>This may be used to pull in printer management daemons + dynamically when printer hardware is found.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>smartcard.target</filename></term> + <listitem> + <para>This target is started automatically as soon as a + smartcard controller is plugged in or becomes available at + boot.</para> + + <para>This may be used to pull in smartcard management + daemons dynamically when smartcard hardware is found.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sound.target</filename></term> + <listitem> + <para>This target is started automatically as soon as a + sound card is plugged in or becomes available at + boot.</para> + + <para>This may be used to pull in audio management daemons + dynamically when audio hardware is found.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Special Passive System Units </title> + + <para>A number of special system targets are defined that can be + used to properly order boot-up of optional services. These targets + are generally not part of the initial boot transaction, unless + they are explicitly pulled in by one of the implementing services. + Note specifically that these <emphasis>passive</emphasis> target + units are generally not pulled in by the consumer of a service, + but by the provider of the service. This means: a consuming + service should order itself after these targets (as appropriate), + but not pull it in. A providing service should order itself before + these targets (as appropriate) and pull it in (via a + <varname>Wants=</varname> type dependency).</para> + + <para>Note that these passive units cannot be started manually, + i.e. <literal>systemctl start time-sync.target</literal> will fail + with an error. They can only be pulled in by dependency. This is + enforced since they exist for ordering purposes only and thus are + not useful as only unit within a transaction.</para> + + <variablelist> + <varlistentry> + <term><filename>cryptsetup-pre.target</filename></term> + <listitem> + <para>This passive target unit may be pulled in by services + that want to run before any encrypted block device is set + up. All encrypted block devices are set up after this target + has been reached. Since the shutdown order is implicitly the + reverse start-up order between units, this target is + particularly useful to ensure that a service is shut down + only after all encrypted block devices are fully + stopped.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>local-fs-pre.target</filename></term> + <listitem> + <para>This target unit is + automatically ordered before + all local mount points marked + with <option>auto</option> + (see above). It can be used to + execute certain units before + all local mounts.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>network.target</filename></term> + <listitem> + <para>This unit is supposed to indicate when network + functionality is available, but it is only very weakly + defined what that is supposed to mean, with one exception: + at shutdown, a unit that is ordered after + <filename>network.target</filename> will be stopped before + the network — to whatever level it might be set up then — + is shut down. It is hence useful when writing service files + that require network access on shutdown, which should order + themselves after this target, but not pull it in. Also see + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running + Services After the Network is up</ulink> for more + information. Also see + <filename>network-online.target</filename> described + above.</para> + + <para>systemd automatically adds dependencies of type + <varname>After=</varname> for this target unit to all SysV + init script service units with an LSB header referring to + the <literal>$network</literal> facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>network-pre.target</filename></term> + <listitem> + <para>This passive target unit may be pulled in by services + that want to run before any network is set up, for example + for the purpose of setting up a firewall. All network + management software orders itself after this target, but + does not pull it in.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>nss-lookup.target</filename></term> + <listitem> + <para>A target that should be used as synchronization point + for all host/network name service lookups. Note that this is + independent of user/group name lookups for which + <filename>nss-user-lookup.target</filename> should be used. + All services for which the availability of full host/network + name resolution is essential should be ordered after this + target, but not pull it in. systemd automatically adds + dependencies of type <varname>After=</varname> for this + target unit to all SysV init script service units with an + LSB header referring to the <literal>$named</literal> + facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>nss-user-lookup.target</filename></term> + <listitem> + <para>A target that should be used as synchronization point + for all user/group name service lookups. Note that this is + independent of host/network name lookups for which + <filename>nss-lookup.target</filename> should be used. All + services for which the availability of the full user/group + database is essential should be ordered after this target, + but not pull it in. Note that system users are always + resolvable, and hence do not require any special ordering + against this target.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>remote-fs-pre.target</filename></term> + <listitem> + <para>This target unit is automatically ordered before all + remote mount point units (see above). It can be used to run + certain units before the remote mounts are established. Note + that this unit is generally not part of the initial + transaction, unless the unit that wants to be ordered before + all remote mounts pulls it in via a + <varname>Wants=</varname> type dependency. If the unit wants + to be pulled in by the first remote mount showing up, it + should use <filename>network-online.target</filename> (see + above).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>rpcbind.target</filename></term> + <listitem> + <para>The portmapper/rpcbind pulls in this target and orders + itself before it, to indicate its availability. systemd + automatically adds dependencies of type + <varname>After=</varname> for this target unit to all SysV + init script service units with an LSB header referring to + the <literal>$portmap</literal> facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>time-sync.target</filename></term> + <listitem> + <para>Services responsible for synchronizing the system + clock from a remote source (such as NTP client + implementations) should pull in this target and order + themselves before it. All services where correct time is + essential should be ordered after this unit, but not pull it + in. systemd automatically adds dependencies of type + <varname>After=</varname> for this target unit to all SysV + init script service units with an LSB header referring to + the <literal>$time</literal> facility. </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Special User Units</title> + + <para>When systemd runs as a user instance, the following special + units are available, which have similar definitions as their + system counterparts: + <filename>exit.target</filename>, + <filename>default.target</filename>, + <filename>shutdown.target</filename>, + <filename>sockets.target</filename>, + <filename>timers.target</filename>, + <filename>paths.target</filename>, + <filename>bluetooth.target</filename>, + <filename>printer.target</filename>, + <filename>smartcard.target</filename>, + <filename>sound.target</filename>.</para> + </refsect1> + + <refsect1> + <title>Special Passive User Units</title> + + <refsect2> + <title>graphical-session.target</title> + + <para>This target is active whenever any graphical session is running. It + is used to stop user services which only apply to a graphical (X, + Wayland, etc.) session when the session is terminated. Such services + should have <literal>PartOf=graphical-session.target</literal> in their + <literal>[Unit]</literal> section. A target for a particular session + (e. g. <filename>gnome-session.target</filename>) starts and stops + <literal>graphical-session.target</literal> with + <literal>BindsTo=graphical-session.target</literal>.</para> + + <para>Which services are started by a session target is determined by the + <literal>Wants=</literal> and <literal>Requires=</literal> dependencies. + For services that can be enabled independently, symlinks in + <literal>.wants/</literal> and <literal>.requires/</literal> should be + used, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Those symlinks should either be shipped in packages, or should be added + dynamically after installation, for example using <literal>systemctl add-wants</literal>, see + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + + <example> + <title>Nautilus as part of a GNOME session</title> + + <para><literal>gnome-session.target</literal> pulls in Nautilus as + top-level service:</para> + + <programlisting>[Unit] +Description=User systemd services for GNOME graphical session +Wants=nautilus.service +BindsTo=graphical-session.target + </programlisting> + + <para><literal>nautilus.service</literal> gets stopped when the session stops:</para> + + <programlisting>[Unit] +Description=Render the desktop icons with Nautilus +PartOf=graphical-session.target + +[Service] +... + </programlisting> + </example> + </refsect2> + + <refsect2> + <title>graphical-session-pre.target</title> + + <para>This target contains services which set up the environment or + global configuration of a graphical session, such as SSH/GPG agents + (which need to export an environment variable into all desktop processes) + or migration of obsolete d-conf keys after an OS upgrade (which needs to + happen before starting any process that might use them). This target must + be started before starting a graphical session + like <filename>gnome-session.target</filename>.</para> + </refsect2> + + </refsect1> + + <refsect1> + <title>Special Slice Units</title> + + <para>There are four <literal>.slice</literal> units which form + the basis of the hierarchy for assignment of resources for + services, users, and virtual machines or containers.</para> + + <variablelist> + <varlistentry> + <term><filename>-.slice</filename></term> + <listitem> + <para>The root slice is the root of the hierarchy. It + usually does not contain units directly, but may be used to + set defaults for the whole tree.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>system.slice</filename></term> + <listitem> + <para>By default, all system services started by + <command>systemd</command> are found in this slice.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>user.slice</filename></term> + <listitem> + <para>By default, all user processes and services started on + behalf of the user, including the per-user systemd instance + are found in this slice.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>machine.slice</filename></term> + <listitem> + <para>By default, all virtual machines and containers + registered with <command>systemd-machined</command> are + found in this slice. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.swap.xml b/src/grp-system/systemd/systemd.swap.xml new file mode 100644 index 0000000000..cf4e1ba839 --- /dev/null +++ b/src/grp-system/systemd/systemd.swap.xml @@ -0,0 +1,250 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.swap"> + <refentryinfo> + <title>systemd.swap</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.swap</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.swap</refname> + <refpurpose>Swap unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>swap</replaceable>.swap</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.swap</literal> encodes information about a swap device + or file for memory paging controlled and supervised by + systemd.</para> + + <para>This man page lists the configuration options specific to + this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic [Unit] and + [Install] sections. The swap specific configuration options are + configured in the [Swap] section.</para> + + <para>Additional options are listed in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the execution environment the <citerefentry + project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> + binary is executed in, in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the way these processes are + terminated, and in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which configure resource control settings for these processes of the + unit.</para> + + <para>Swap units must be named after the devices or files they control. Example: the swap device <filename + noindex='true'>/dev/sda5</filename> must be configured in a unit file <filename>dev-sda5.swap</filename>. For + details about the escaping logic used to convert a file system path to a unit name, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that swap + units cannot be templated, nor is possible to add multiple names to a swap unit by creating additional symlinks to + it.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>All swap units automatically get the + <varname>BindsTo=</varname> and <varname>After=</varname> + dependencies on the device units or the mount units of the files + they are activated from.</para> + + <para>Swap units with <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section enabled + implicitly acquire a <varname>Conflicts=</varname> and an <varname>After=</varname> dependency on + <filename>umount.target</filename> so that they are deactivated at shutdown, unless + <varname>DefaultDependencies=no</varname> is specified.</para> + + <para>Additional implicit dependencies may be added as result of + execution and resource control parameters as documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title><filename>fstab</filename></title> + + <para>Swap units may either be configured via unit files, or via + <filename>/etc/fstab</filename> (see + <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). Swaps listed in <filename>/etc/fstab</filename> will + be converted into native units dynamically at boot and when the + configuration of the system manager is reloaded. See + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details about the conversion.</para> + + <para>If a swap device or file is configured in both + <filename>/etc/fstab</filename> and a unit file, the configuration + in the latter takes precedence.</para> + + <para>When reading <filename>/etc/fstab</filename>, a few special + options are understood by systemd which influence how dependencies + are created for swap units.</para> + + <variablelist class='fstab-options'> + <varlistentry> + <term><option>noauto</option></term> + <term><option>auto</option></term> + + <listitem><para>With <option>noauto</option>, the swap unit + will not be added as a dependency for + <filename>swap.target</filename>. This means that it will not + be activated automatically during boot, unless it is pulled in + by some other unit. The <option>auto</option> option has the + opposite meaning and is the default.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>nofail</option></term> + + <listitem><para>With <option>nofail</option>, the swap unit + will be only wanted, not required by + <filename>swap.target</filename>. This means that the boot + will continue even if this swap device is not activated + successfully.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Swap files must include a [Swap] section, which carries + information about the swap device it supervises. A number of + options that may be used in this section are shared with other + unit types. These options are documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + The options specific to the [Swap] section of swap units are the + following:</para> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>What=</varname></term> + <listitem><para>Takes an absolute path of a device node or + file to use for paging. See + <citerefentry project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details. If this refers to a device node, a dependency on + the respective device unit is automatically created. (See + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information.) If this refers to a file, a dependency + on the respective mount unit is automatically created. (See + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information.) This option is + mandatory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Priority=</varname></term> + + <listitem><para>Swap priority to use when activating the swap + device or file. This takes an integer. This setting is + optional and ignored when the priority is set by <option>pri=</option> in the + <varname>Options=</varname> key.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Options=</varname></term> + + <listitem><para>May contain an option string for the swap + device. This may be used for controlling discard options among + other functionality, if the swap backing device supports the + discard or trim operation. (See + <citerefentry project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for more information.) </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutSec=</varname></term> + <listitem><para>Configures the time to wait for the swapon + command to finish. If a command does not exit within the + configured time, the swap will be considered failed and be + shut down again. All commands still running will be terminated + forcibly via <constant>SIGTERM</constant>, and after another + delay of this time with <constant>SIGKILL</constant>. (See + <option>KillMode=</option> in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.) + Takes a unit-less value in seconds, or a time span value such + as "5min 20s". Pass <literal>0</literal> to disable the + timeout logic. Defaults to + <varname>DefaultTimeoutStartSec=</varname> from the manager + configuration file (see + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + </para></listitem> + </varlistentry> + </variablelist> + + <para>Check + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more settings.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.target.xml b/src/grp-system/systemd/systemd.target.xml new file mode 100644 index 0000000000..b3cccd4e52 --- /dev/null +++ b/src/grp-system/systemd/systemd.target.xml @@ -0,0 +1,112 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.target"> + <refentryinfo> + <title>systemd.target</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.target</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.target</refname> + <refpurpose>Target unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>target</replaceable>.target</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.target</literal> encodes information about a target unit + of systemd, which is used for grouping units and as well-known + synchronization points during start-up.</para> + + <para>This unit type has no specific options. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic [Unit] and + [Install] sections. A separate [Target] section does not exist, + since no target-specific options may be configured.</para> + + <para>Target units do not offer any additional functionality on + top of the generic functionality provided by units. They exist + merely to group units via dependencies (useful as boot targets), + and to establish standardized names for synchronization points + used in dependencies between units. Among other things, target + units are a more flexible replacement for SysV runlevels in the + classic SysV init system. (And for compatibility reasons special + target units such as <filename>runlevel3.target</filename> exist + which are used by the SysV runlevel compatibility code in systemd. + See + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details).</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>Unless <varname>DefaultDependencies=</varname> is set to + <option>no</option> in either of related units or an explicit ordering + dependency is already defined, target units will implicitly complement all + configured dependencies of type <varname>Wants=</varname> or + <varname>Requires=</varname> with dependencies of type + <varname>After=</varname>. Note that <varname>Wants=</varname> or + <varname>Requires=</varname> must be defined in the target unit itself — if + you for example define <varname>Wants=</varname>some.target in + some.service, the implicit ordering will not be added.</para> + + <para>All target units automatically gain <varname>Conflicts=</varname> + dependency against shutdown.target unless <varname>DefaultDependencies=</varname> + is set to <option>no</option>.</para> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.time.xml b/src/grp-system/systemd/systemd.time.xml new file mode 100644 index 0000000000..47229b4a4e --- /dev/null +++ b/src/grp-system/systemd/systemd.time.xml @@ -0,0 +1,310 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.time"> + + <refentryinfo> + <title>systemd.time</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.time</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.time</refname> + <refpurpose>Time and date specifications</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>In systemd, timestamps, time spans, and calendar events are + displayed and may be specified in closely related syntaxes.</para> + </refsect1> + + <refsect1> + <title>Displaying Time Spans</title> + + <para>Time spans refer to time durations. On display, systemd will present time spans as a space-separated series + of time values each suffixed by a time unit. Example:</para> + + <programlisting>2h 30min</programlisting> + + <para>All specified time values are meant to be added up. The above hence refers to 150 minutes. Display is + locale-independent, only English names for the time units are used.</para> + </refsect1> + + <refsect1> + <title>Parsing Time Spans</title> + + <para>When parsing, systemd will accept the same time span syntax. + Separating spaces may be omitted. The following time units are + understood:</para> + + <itemizedlist> + <listitem><para>usec, us</para></listitem> + <listitem><para>msec, ms</para></listitem> + <listitem><para>seconds, second, sec, s</para></listitem> + <listitem><para>minutes, minute, min, m</para></listitem> + <listitem><para>hours, hour, hr, h</para></listitem> + <listitem><para>days, day, d</para></listitem> + <listitem><para>weeks, week, w</para></listitem> + <listitem><para>months, month, M (defined as 30.44 days)</para></listitem> + <listitem><para>years, year, y (defined as 365.25 days)</para></listitem> + </itemizedlist> + + <para>If no time unit is specified, generally seconds are assumed, but some exceptions exist and are marked as + such. In a few cases <literal>ns</literal>, <literal>nsec</literal> is accepted too, where the granularity of the + time span permits this. Parsing is generally locale-independent, non-English names for the time units are not + accepted.</para> + + <para>Examples for valid time span specifications:</para> + + <programlisting>2 h +2hours +48hr +1y 12month +55s500ms +300ms20s 5day</programlisting> + </refsect1> + + <refsect1> + <title>Displaying Timestamps</title> + + <para>Timestamps refer to specific, unique points in time. On + display, systemd will format these in the local timezone as + follows:</para> + + <programlisting>Fri 2012-11-23 23:02:15 CET</programlisting> + + <para>The weekday is printed in the abbreviated English language form. The formatting is locale-independent.</para> + + <para>In some cases timestamps are shown in the UTC timezone instead of the local timezone, which is indicated via + the <literal>UTC</literal> timezone specifier in the output.</para> + + <para>In some cases timestamps are shown with microsecond granularity. In this case the sub-second remainder is + separated by a full stop from the seconds component.</para> + </refsect1> + + <refsect1> + <title>Parsing Timestamps</title> + + <para>When parsing, systemd will accept a similar syntax, but expects no timezone specification, unless it is given + as the literal string <literal>UTC</literal> (for the UTC timezone) or is specified to be the locally configured + timezone. Other timezones than the local and UTC are not supported. The weekday specification is optional, but when + the weekday is specified, it must either be in the abbreviated (<literal>Wed</literal>) or non-abbreviated + (<literal>Wednesday</literal>) English language form (case does not matter), and is not subject to the locale + choice of the user. Either the date, or the time part may be omitted, in which case the current date or 00:00:00, + respectively, is assumed. The seconds component of the time may also be omitted, in which case ":00" is + assumed. Year numbers may be specified in full or may be abbreviated (omitting the century).</para> + + <para>A timestamp is considered invalid if a weekday is specified and the date does not match the specified day of + the week.</para> + + <para>When parsing, systemd will also accept a few special + placeholders instead of timestamps: <literal>now</literal> may be + used to refer to the current time (or of the invocation of the + command that is currently executed). <literal>today</literal>, + <literal>yesterday</literal>, and <literal>tomorrow</literal> refer to + 00:00:00 of the current day, the day before, or the next day, + respectively.</para> + + <para>When parsing, systemd will also accept relative time + specifications. A time span (see above) that is prefixed with + <literal>+</literal> is evaluated to the current time plus the + specified time span. Correspondingly, a time span that is prefixed + with <literal>-</literal> is evaluated to the current time minus + the specified time span. Instead of prefixing the time span with + <literal>+</literal> or <literal>-</literal>, it may also be + suffixed with a space and the word <literal>left</literal> or + <literal>ago</literal>.</para> + + <para>Finally, a timespan prefixed with <literal>@</literal> is + evaluated relative to the UNIX time epoch 1st Jan, 1970, + 00:00.</para> + + <para>Examples for valid timestamps and their normalized form + (assuming the current time was 2012-11-23 18:15:22 and the timezone + was UTC+8, for example TZ=Asia/Shanghai):</para> + + <programlisting>Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13 + 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13 +2012-11-23 11:12:13 UTC → Fri 2012-11-23 19:12:13 + 2012-11-23 → Fri 2012-11-23 00:00:00 + 12-11-23 → Fri 2012-11-23 00:00:00 + 11:12:13 → Fri 2012-11-23 11:12:13 + 11:12 → Fri 2012-11-23 11:12:00 + now → Fri 2012-11-23 18:15:22 + today → Fri 2012-11-23 00:00:00 + today UTC → Fri 2012-11-23 16:00:00 + yesterday → Fri 2012-11-22 00:00:00 + tomorrow → Fri 2012-11-24 00:00:00 + +3h30min → Fri 2012-11-23 21:45:22 + -5s → Fri 2012-11-23 18:15:17 + 11min ago → Fri 2012-11-23 18:04:22 + @1395716396 → Tue 2014-03-25 03:59:56</programlisting> + + <para>Note that timestamps displayed by remote systems with a non-matching timezone are usually not parsable + locally, as the timezone component is not understood (unless it happens to be <literal>UTC</literal>).</para> + + <para>Timestamps may also be specified with microsecond granularity. The sub-second remainder is expected separated + by a full stop from the seconds component. Example:</para> + + <programlisting>2014-03-25 03:59:56.654563</programlisting> + + <para>In some cases, systemd will display a relative timestamp (relative to the current time, or the time of + invocation of the command) instead of or in addition to an absolute timestamp as described above. A relative + timestamp is formatted as follows:</para> + + <programlisting>2 months 5 days ago</programlisting> + + <para>Note that a relative timestamp is also accepted where a timestamp is expected (see above).</para> + </refsect1> + + <refsect1> + <title>Calendar Events</title> + + <para>Calendar events may be used to refer to one or more points + in time in a single expression. They form a superset of the + absolute timestamps explained above:</para> + + <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting> + + <para>The above refers to 11:12:13 of the first or fifth day of + any month of the year 2012, but only if that day is a Thursday or + Friday.</para> + + <para>The weekday specification is optional. If specified, it + should consist of one or more English language weekday names, + either in the abbreviated (Wed) or non-abbreviated (Wednesday) + form (case does not matter), separated by commas. Specifying two + weekdays separated by <literal>..</literal> refers to a range of + continuous weekdays. <literal>,</literal> and <literal>..</literal> + may be combined freely.</para> + + <para>In the date and time specifications, any component may be + specified as <literal>*</literal> in which case any value will + match. Alternatively, each component can be specified as a list of + values separated by commas. Values may also be suffixed with + <literal>/</literal> and a repetition value, which indicates that + the value itself and the value plus all multiples of the repetition value + are matched. Each component may also contain a range of values + separated by <literal>..</literal>.</para> + + <para>The seconds component may contain decimal fractions both in + the value and the repetition. All fractions are rounded to 6 + decimal places.</para> + + <para>Either time or date specification may be omitted, in which + case the current day and 00:00:00 is implied, respectively. If the + second component is not specified, <literal>:00</literal> is + assumed.</para> + + <para>A timezone specification is not expected, unless it is given as the literal string <literal>UTC</literal>, or + the local timezone, similar to the supported syntax of timestamps (see above). Non-local timezones except for UTC + are not supported.</para> + + <para>The special expressions + <literal>minutely</literal>, + <literal>hourly</literal>, <literal>daily</literal>, + <literal>monthly</literal>, <literal>weekly</literal>, + <literal>yearly</literal>, + <literal>quarterly</literal>, + <literal>semiannually</literal> may be used as + calendar events which refer to + <literal>*-*-* *:*:00</literal>, + <literal>*-*-* *:00:00</literal>, + <literal>*-*-* 00:00:00</literal>, + <literal>*-*-01 00:00:00</literal>, + <literal>Mon *-*-* 00:00:00</literal>, + <literal>*-01-01 00:00:00</literal>, + <literal>*-01,04,07,10-01 00:00:00</literal> and + <literal>*-01,07-01 00:00:00</literal>, respectively. + </para> + + <para>Examples for valid timestamps and their + normalized form:</para> + +<programlisting> Sat,Thu,Mon..Wed,Sat..Sun → Mon..Thu,Sat,Sun *-*-* 00:00:00 + Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00 + Wed *-1 → Wed *-*-01 00:00:00 + Wed..Wed,Wed *-1 → Wed *-*-01 00:00:00 + Wed, 17:48 → Wed *-*-* 17:48:00 +Wed..Sat,Tue 12-10-15 1:2:3 → Tue..Sat 2012-10-15 01:02:03 + *-*-7 0:0:0 → *-*-07 00:00:00 + 10-15 → *-10-15 00:00:00 + monday *-12-* 17:00 → Mon *-12-* 17:00:00 + Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45 + 12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00 + 12..14:10,20,30 → *-*-* 12,13,14:10,20,30:00 + mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45 + 03-05 08:05:40 → *-03-05 08:05:40 + 08:05:40 → *-*-* 08:05:40 + 05:40 → *-*-* 05:40:00 + Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40 + Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40 + 2003-03-05 05:40 → 2003-03-05 05:40:00 + 05:40:23.4200004/3.1700005 → 05:40:23.420000/3.170001 + 2003-02..04-05 → 2003-02,03,04-05 00:00:00 + 2003-03-05 05:40 UTC → 2003-03-05 05:40:00 UTC + 2003-03-05 → 2003-03-05 00:00:00 + 03-05 → *-03-05 00:00:00 + hourly → *-*-* *:00:00 + daily → *-*-* 00:00:00 + daily UTC → *-*-* 00:00:00 UTC + monthly → *-*-01 00:00:00 + weekly → Mon *-*-* 00:00:00 + yearly → *-01-01 00:00:00 + annually → *-01-01 00:00:00 + *:2/3 → *-*-* *:02/3:00</programlisting> + + <para>Calendar events are used by timer units, see + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.timer.xml b/src/grp-system/systemd/systemd.timer.xml new file mode 100644 index 0000000000..4fe140e4bc --- /dev/null +++ b/src/grp-system/systemd/systemd.timer.xml @@ -0,0 +1,313 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.timer"> + <refentryinfo> + <title>systemd.timer</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.timer</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.timer</refname> + <refpurpose>Timer unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>timer</replaceable>.timer</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.timer</literal> encodes information about a timer + controlled and supervised by systemd, for timer-based + activation.</para> + + <para>This man page lists the configuration options specific to + this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic [Unit] and + [Install] sections. The timer specific configuration options are + configured in the [Timer] section.</para> + + <para>For each timer file, a matching unit file must exist, + describing the unit to activate when the timer elapses. By + default, a service by the same name as the timer (except for the + suffix) is activated. Example: a timer file + <filename>foo.timer</filename> activates a matching service + <filename>foo.service</filename>. The unit to activate may be + controlled by <varname>Unit=</varname> (see below).</para> + + <para>Note that in case the unit to activate is already active at the time the timer elapses it is not restarted, + but simply left running. There is no concept of spawning new service instances in this case. Due to this, services + with <varname>RemainAfterExit=</varname> set (which stay around continuously even after the service's main process + exited) are usually not suitable for activation via repetitive timers, as they will only be activated once, and + then stay around forever.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>Timer units automatically gain a <varname>Before=</varname> + dependency on the service they are supposed to activate.</para> + + <para>Unless <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section is set to + <option>false</option>, all timer units will implicitly have dependencies of type <varname>Requires=</varname> and + <varname>After=</varname> on <filename>sysinit.target</filename>, a dependency of type <varname>Before=</varname> + on <filename>timers.target</filename>, as well as <varname>Conflicts=</varname> and <varname>Before=</varname> on + <filename>shutdown.target</filename> to ensure that they are stopped cleanly prior to system shutdown. Timer units + with at least one <varname>OnCalendar=</varname> directive will have an additional <varname>After=</varname> + dependency on <filename>timer-sync.target</filename> to avoid being started before the system clock has been + correctly set. Only timer units involved with early boot or late system shutdown should disable the + <varname>DefaultDependencies=</varname> option.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Timer files must include a [Timer] section, which carries + information about the timer it defines. The options specific to + the [Timer] section of timer units are the following:</para> + + <variablelist class='unit-directives'> + <varlistentry> + <term><varname>OnActiveSec=</varname></term> + <term><varname>OnBootSec=</varname></term> + <term><varname>OnStartupSec=</varname></term> + <term><varname>OnUnitActiveSec=</varname></term> + <term><varname>OnUnitInactiveSec=</varname></term> + + <listitem><para>Defines monotonic timers relative to different + starting points: <varname>OnActiveSec=</varname> defines a + timer relative to the moment the timer itself is activated. + <varname>OnBootSec=</varname> defines a timer relative to when + the machine was booted up. <varname>OnStartupSec=</varname> + defines a timer relative to when systemd was first started. + <varname>OnUnitActiveSec=</varname> defines a timer relative + to when the unit the timer is activating was last activated. + <varname>OnUnitInactiveSec=</varname> defines a timer relative + to when the unit the timer is activating was last + deactivated.</para> + + <para>Multiple directives may be combined of the same and of + different types. For example, by combining + <varname>OnBootSec=</varname> and + <varname>OnUnitActiveSec=</varname>, it is possible to define + a timer that elapses in regular intervals and activates a + specific service each time.</para> + + <para>The arguments to the directives are time spans + configured in seconds. Example: "OnBootSec=50" means 50s after + boot-up. The argument may also include time units. Example: + "OnBootSec=5h 30min" means 5 hours and 30 minutes after + boot-up. For details about the syntax of time spans, see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>If a timer configured with <varname>OnBootSec=</varname> + or <varname>OnStartupSec=</varname> is already in the past + when the timer unit is activated, it will immediately elapse + and the configured unit is started. This is not the case for + timers defined in the other directives.</para> + + <para>These are monotonic timers, independent of wall-clock + time and timezones. If the computer is temporarily suspended, + the monotonic clock stops too.</para> + + <para>If the empty string is assigned to any of these options, + the list of timers is reset, and all prior assignments will + have no effect.</para> + + <para>Note that timers do not necessarily expire at the + precise time configured with these settings, as they are + subject to the <varname>AccuracySec=</varname> setting + below.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><varname>OnCalendar=</varname></term> + + <listitem><para>Defines realtime (i.e. wallclock) timers with + calendar event expressions. See + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for more information on the syntax of calendar event + expressions. Otherwise, the semantics are similar to + <varname>OnActiveSec=</varname> and related settings.</para> + + <para>Note that timers do not necessarily expire at the + precise time configured with this setting, as it is subject to + the <varname>AccuracySec=</varname> setting + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>AccuracySec=</varname></term> + + <listitem><para>Specify the accuracy the timer shall elapse + with. Defaults to 1min. The timer is scheduled to elapse + within a time window starting with the time specified in + <varname>OnCalendar=</varname>, + <varname>OnActiveSec=</varname>, + <varname>OnBootSec=</varname>, + <varname>OnStartupSec=</varname>, + <varname>OnUnitActiveSec=</varname> or + <varname>OnUnitInactiveSec=</varname> and ending the time + configured with <varname>AccuracySec=</varname> later. Within + this time window, the expiry time will be placed at a + host-specific, randomized, but stable position that is + synchronized between all local timer units. This is done in + order to optimize power consumption to suppress unnecessary + CPU wake-ups. To get best accuracy, set this option to + 1us. Note that the timer is still subject to the timer slack + configured via + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s + <varname>TimerSlackNSec=</varname> setting. See + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. To optimize power consumption, make sure to set + this value as high as possible and as low as + necessary.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RandomizedDelaySec=</varname></term> + + <listitem><para>Delay the timer by a randomly selected, evenly + distributed amount of time between 0 and the specified time + value. Defaults to 0, indicating that no randomized delay + shall be applied. Each timer unit will determine this delay + randomly each time it is started, and the delay will simply be + added on top of the next determined elapsing time. This is + useful to stretch dispatching of similarly configured timer + events over a certain amount time, to avoid that they all fire + at the same time, possibly resulting in resource + congestion. Note the relation to + <varname>AccuracySec=</varname> above: the latter allows the + service manager to coalesce timer events within a specified + time range in order to minimize wakeups, the former does the + opposite: it stretches timer events over a time range, to make + it unlikely that they fire simultaneously. If + <varname>RandomizedDelaySec=</varname> and + <varname>AccuracySec=</varname> are used in conjunction, first + the randomized delay is added, and then the result is + possibly further shifted to coalesce it with other timer + events happening on the system. As mentioned above + <varname>AccuracySec=</varname> defaults to 1min and + <varname>RandomizedDelaySec=</varname> to 0, thus encouraging + coalescing of timer events. In order to optimally stretch + timer events over a certain range of time, make sure to set + <varname>RandomizedDelaySec=</varname> to a higher value, and + <varname>AccuracySec=1us</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Unit=</varname></term> + + <listitem><para>The unit to activate when this timer elapses. + The argument is a unit name, whose suffix is not + <literal>.timer</literal>. If not specified, this value + defaults to a service that has the same name as the timer + unit, except for the suffix. (See above.) It is recommended + that the unit name that is activated and the unit name of the + timer unit are named identically, except for the + suffix.</para></listitem> + </varlistentry> + + + <varlistentry> + <term><varname>Persistent=</varname></term> + + <listitem><para>Takes a boolean argument. If true, the time + when the service unit was last triggered is stored on disk. + When the timer is activated, the service unit is triggered + immediately if it would have been triggered at least once + during the time when the timer was inactive. This is useful to + catch up on missed runs of the service when the machine was + off. Note that this setting only has an effect on timers + configured with <varname>OnCalendar=</varname>. Defaults + to <varname>false</varname>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>WakeSystem=</varname></term> + + <listitem><para>Takes a boolean argument. If true, an elapsing + timer will cause the system to resume from suspend, should it + be suspended and if the system supports this. Note that this + option will only make sure the system resumes on the + appropriate times, it will not take care of suspending it + again after any work that is to be done is finished. Defaults + to <varname>false</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RemainAfterElapse=</varname></term> + + <listitem><para>Takes a boolean argument. If true, an elapsed + timer will stay loaded, and its state remains queriable. If + false, an elapsed timer unit that cannot elapse anymore is + unloaded. Turning this off is particularly useful for + transient timer units that shall disappear after they first + elapse. Note that this setting has an effect on repeatedly + starting a timer unit that only elapses once: if + <varname>RemainAfterElapse=</varname> is on, it will not be + started again, and is guaranteed to elapse only once. However, + if <varname>RemainAfterElapse=</varname> is off, it might be + started again if it is already elapsed, and thus be triggered + multiple times. Defaults to + <varname>yes</varname>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.tmpfiles b/src/grp-system/systemd/systemd.tmpfiles new file mode 100644 index 0000000000..00951c92c9 --- /dev/null +++ b/src/grp-system/systemd/systemd.tmpfiles @@ -0,0 +1,20 @@ +# This file is part of systemd. +# +# systemd is free software; you can redistribute it and/or modify it +# under the terms of the GNU Lesser General Public License as published by +# the Free Software Foundation; either version 2.1 of the License, or +# (at your option) any later version. + +# See tmpfiles.d(5) for details + +d /run/user 0755 root root - +F! /run/utmp 0664 root utmp - + +d /run/systemd/ask-password 0755 root root - +d /run/systemd/seats 0755 root root - +d /run/systemd/sessions 0755 root root - +d /run/systemd/users 0755 root root - +d /run/systemd/machines 0755 root root - +d /run/systemd/shutdown 0755 root root - + +d /var/lib/systemd 0755 root root - diff --git a/src/grp-system/systemd/systemd.unit.xml b/src/grp-system/systemd/systemd.unit.xml new file mode 100644 index 0000000000..40c4cfd854 --- /dev/null +++ b/src/grp-system/systemd/systemd.unit.xml @@ -0,0 +1,1493 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.unit"> + + <refentryinfo> + <title>systemd.unit</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.unit</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.unit</refname> + <refpurpose>Unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>service</replaceable>.service</filename>, + <filename><replaceable>socket</replaceable>.socket</filename>, + <filename><replaceable>device</replaceable>.device</filename>, + <filename><replaceable>mount</replaceable>.mount</filename>, + <filename><replaceable>automount</replaceable>.automount</filename>, + <filename><replaceable>swap</replaceable>.swap</filename>, + <filename><replaceable>target</replaceable>.target</filename>, + <filename><replaceable>path</replaceable>.path</filename>, + <filename><replaceable>timer</replaceable>.timer</filename>, + <filename><replaceable>slice</replaceable>.slice</filename>, + <filename><replaceable>scope</replaceable>.scope</filename></para> + + <para><literallayout><filename>/etc/systemd/system/*</filename> +<filename>/run/systemd/system/*</filename> +<filename>/usr/lib/systemd/system/*</filename> +<filename>…</filename> + </literallayout></para> + + <para><literallayout><filename>~/.config/systemd/user/*</filename> +<filename>/etc/systemd/user/*</filename> +<filename>$XDG_RUNTIME_DIR/systemd/user/*</filename> +<filename>/run/systemd/user/*</filename> +<filename>~/.local/share/systemd/user/*</filename> +<filename>/usr/lib/systemd/user/*</filename> +<filename>…</filename> + </literallayout></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file encodes information about a + service, a socket, a device, a mount point, an automount point, a + swap file or partition, a start-up target, a watched file system + path, a timer controlled and supervised by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + a resource management slice or + a group of externally created processes. The syntax is inspired by + <ulink + url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG + Desktop Entry Specification</ulink> <filename>.desktop</filename> + files, which are in turn inspired by Microsoft Windows + <filename>.ini</filename> files.</para> + + <para>This man page lists the common configuration options of all + the unit types. These options need to be configured in the [Unit] + or [Install] sections of the unit files.</para> + + <para>In addition to the generic [Unit] and [Install] sections + described here, each unit may have a type-specific section, e.g. + [Service] for a service unit. See the respective man pages for + more information: + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para>Various settings are allowed to be specified more than once, + in which case the interpretation depends on the setting. Often, + multiple settings form a list, and setting to an empty value + "resets", which means that previous assignments are ignored. When + this is allowed, it is mentioned in the description of the + setting. Note that using multiple assignments to the same value + makes the unit file incompatible with parsers for the XDG + <filename>.desktop</filename> file format.</para> + + <para>Unit files are loaded from a set of paths determined during + compilation, described in the next section.</para> + + <para>Unit files may contain additional options on top of those + listed here. If systemd encounters an unknown option, it will + write a warning log message but continue loading the unit. If an + option or section name is prefixed with <option>X-</option>, it is + ignored completely by systemd. Options within an ignored section + do not need the prefix. Applications may use this to include + additional information in the unit files.</para> + + <para>Boolean arguments used in unit files can be written in + various formats. For positive settings the strings + <option>1</option>, <option>yes</option>, <option>true</option> + and <option>on</option> are equivalent. For negative settings, the + strings <option>0</option>, <option>no</option>, + <option>false</option> and <option>off</option> are + equivalent.</para> + + <para>Time span values encoded in unit files can be written in various formats. A stand-alone + number specifies a time in seconds. If suffixed with a time unit, the unit is honored. A + concatenation of multiple values with units is supported, in which case the values are added + up. Example: <literal>50</literal> refers to 50 seconds; <literal>2min 200ms</literal> refers to + 2 minutes and 200 milliseconds, i.e. 120200 ms. The following time units are understood: + <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>d</literal>, + <literal>w</literal>, <literal>ms</literal>, <literal>us</literal>. For details see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are + ignored. This may be used for commenting. Lines ending in a backslash are concatenated with the + following line while reading and the backslash is replaced by a space character. This may be + used to wrap long lines.</para> + + <para>Units can be aliased (have an alternative name), by creating a symlink from the new name + to the existing name in one of the unit search paths. For example, + <filename>systemd-networkd.service</filename> has the alias + <filename>dbus-org.freedesktop.network1.service</filename>, created during installation as the + symlink <filename>/usr/lib/systemd/system/dbus-org.freedesktop.network1.service</filename>. In + addition, unit files may specify aliases through the <varname>Alias=</varname> directive in the + [Install] section; those aliases are only effective when the unit is enabled. When the unit is + enabled, symlinks will be created for those names, and removed when the unit is disabled. For + example, <filename>reboot.target</filename> specifies + <varname>Alias=ctrl-alt-del.target</varname>, so when enabled it will be invoked whenever + CTRL+ALT+DEL is pressed. Alias names may be used in commands like <command>enable</command>, + <command>disable</command>, <command>start</command>, <command>stop</command>, + <command>status</command>, …, and in unit dependency directives <varname>Wants=</varname>, + <varname>Requires=</varname>, <varname>Before=</varname>, <varname>After=</varname>, …, with the + limitation that aliases specified through <varname>Alias=</varname> are only effective when the + unit is enabled. Aliases cannot be used with the <command>preset</command> command.</para> + + <para>Along with a unit file <filename>foo.service</filename>, the directory + <filename>foo.service.wants/</filename> may exist. All unit files symlinked from such a + directory are implicitly added as dependencies of type <varname>Wants=</varname> to the unit. + This is useful to hook units into the start-up of other units, without having to modify their + unit files. For details about the semantics of <varname>Wants=</varname>, see below. The + preferred way to create symlinks in the <filename>.wants/</filename> directory of a unit file is + with the <command>enable</command> command of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool which reads information from the [Install] section of unit files (see below). A similar + functionality exists for <varname>Requires=</varname> type dependencies as well, the directory + suffix is <filename>.requires/</filename> in this case.</para> + + <para>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory + <filename>foo.service.d/</filename> may exist. All files with the suffix + <literal>.conf</literal> from this directory will be parsed after the file itself is + parsed. This is useful to alter or add configuration settings for a unit, without having to + modify unit files. Each drop-in file must have appropriate section headers. Note that for + instantiated units, this logic will first look for the instance <literal>.d/</literal> + subdirectory and read its <literal>.conf</literal> files, followed by the template + <literal>.d/</literal> subdirectory and the <literal>.conf</literal> files there. Also note that + settings from the <literal>[Install]</literal> section are not honored in drop-in unit files, + and have no effect.</para> + + <para>In addition to <filename>/etc/systemd/system</filename>, the drop-in <literal>.d</literal> + directories for system services can be placed in <filename>/usr/lib/systemd/system</filename> or + <filename>/run/systemd/system</filename> directories. Drop-in files in <filename>/etc</filename> + take precedence over those in <filename>/run</filename> which in turn take precedence over those + in <filename>/usr/lib</filename>. Drop-in files under any of these directories take precedence + over unit files wherever located.</para> + + <!-- Note that we do not document .include here, as we consider it mostly obsolete, and want + people to use .d/ drop-ins instead. --> + + <para>Some unit names reflect paths existing in the file system + namespace. Example: a device unit + <filename>dev-sda.device</filename> refers to a device with the + device node <filename noindex='true'>/dev/sda</filename> in the + file system namespace. If this applies, a special way to escape + the path name is used, so that the result is usable as part of a + filename. Basically, given a path, "/" is replaced by "-", and all + other characters which are not ASCII alphanumerics are replaced by + C-style "\x2d" escapes (except that "_" is never replaced and "." + is only replaced when it would be the first character in the + escaped path). The root directory "/" is encoded as single dash, + while otherwise the initial and ending "/" are removed from all + paths during transformation. This escaping is reversible. Properly + escaped paths can be generated using the + <citerefentry><refentrytitle>systemd-escape</refentrytitle><manvolnum>1</manvolnum></citerefentry> + command.</para> + + <para>Optionally, units may be instantiated from a + template file at runtime. This allows creation of + multiple units from a single configuration file. If + systemd looks for a unit configuration file, it will + first search for the literal unit name in the + file system. If that yields no success and the unit + name contains an <literal>@</literal> character, systemd will look for a + unit template that shares the same name but with the + instance string (i.e. the part between the <literal>@</literal> character + and the suffix) removed. Example: if a service + <filename>getty@tty3.service</filename> is requested + and no file by that name is found, systemd will look + for <filename>getty@.service</filename> and + instantiate a service from that configuration file if + it is found.</para> + + <para>To refer to the instance string from within the + configuration file you may use the special <literal>%i</literal> + specifier in many of the configuration options. See below for + details.</para> + + <para>If a unit file is empty (i.e. has the file size 0) or is + symlinked to <filename>/dev/null</filename>, its configuration + will not be loaded and it appears with a load state of + <literal>masked</literal>, and cannot be activated. Use this as an + effective way to fully disable a unit, making it impossible to + start it even manually.</para> + + <para>The unit file format is covered by the + <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface + Stability Promise</ulink>.</para> + + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <para>Note that while systemd offers a flexible dependency system + between units it is recommended to use this functionality only + sparingly and instead rely on techniques such as bus-based or + socket-based activation which make dependencies implicit, + resulting in a both simpler and more flexible system.</para> + + <para>A number of unit dependencies are automatically established, + depending on unit configuration. On top of that, for units with + <varname>DefaultDependencies=yes</varname> (the default) a couple + of additional dependencies are added. The precise effect of + <varname>DefaultDependencies=yes</varname> depends on the unit + type (see below).</para> + + <para>If <varname>DefaultDependencies=yes</varname> is set, units + that are referenced by other units of type + <filename>.target</filename> via a <varname>Wants=</varname> or + <varname>Requires=</varname> dependency might automatically gain + an <varname>Before=</varname> dependency too. See + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </refsect1> + + <refsect1> + <title>Unit File Load Path</title> + + <para>Unit files are loaded from a set of paths determined during + compilation, described in the two tables below. Unit files found + in directories listed earlier override files with the same name in + directories lower in the list.</para> + + <para>When the variable <varname>$SYSTEMD_UNIT_PATH</varname> is set, + the contents of this variable overrides the unit load path. If + <varname>$SYSTEMD_UNIT_PATH</varname> ends with an empty component + (<literal>:</literal>), the usual unit load path will be appended + to the contents of the variable.</para> + + <table> + <title> + Load path when running in system mode (<option>--system</option>). + </title> + + <tgroup cols='2'> + <colspec colname='path' /> + <colspec colname='expl' /> + <thead> + <row> + <entry>Path</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>/etc/systemd/system</filename></entry> + <entry>Local configuration</entry> + </row> + <row> + <entry><filename>/run/systemd/system</filename></entry> + <entry>Runtime units</entry> + </row> + <row> + <entry><filename>/usr/lib/systemd/system</filename></entry> + <entry>Units of installed packages</entry> + </row> + </tbody> + </tgroup> + </table> + + <table> + <title> + Load path when running in user mode (<option>--user</option>). + </title> + + <tgroup cols='2'> + <colspec colname='path' /> + <colspec colname='expl' /> + <thead> + <row> + <entry>Path</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename></entry> + <entry>User configuration (only used when $XDG_CONFIG_HOME is set)</entry> + </row> + <row> + <entry><filename>$HOME/.config/systemd/user</filename></entry> + <entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</entry> + </row> + <row> + <entry><filename>/etc/systemd/user</filename></entry> + <entry>Local configuration</entry> + </row> + <row> + <entry><filename>$XDG_RUNTIME_DIR/systemd/user</filename></entry> + <entry>Runtime units (only used when $XDG_RUNTIME_DIR is set)</entry> + </row> + <row> + <entry><filename>/run/systemd/user</filename></entry> + <entry>Runtime units</entry> + </row> + <row> + <entry><filename>$XDG_DATA_HOME/systemd/user</filename></entry> + <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)</entry> + </row> + <row> + <entry><filename>$HOME/.local/share/systemd/user</filename></entry> + <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)</entry> + </row> + <row> + <entry><filename>/usr/lib/systemd/user</filename></entry> + <entry>Units of packages that have been installed system-wide</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Additional units might be loaded into systemd ("linked") + from directories not on the unit load path. See the + <command>link</command> command for + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + Also, some units are dynamically created via a + <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para> + </refsect1> + + <refsect1> + <title>[Unit] Section Options</title> + + <para>The unit file may include a [Unit] section, which carries + generic information about the unit that is not dependent on the + type of unit:</para> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>Description=</varname></term> + <listitem><para>A free-form string describing the unit. This + is intended for use in UIs to show descriptive information + along with the unit name. The description should contain a + name that means something to the end user. <literal>Apache2 + Web Server</literal> is a good example. Bad examples are + <literal>high-performance light-weight HTTP server</literal> + (too generic) or <literal>Apache2</literal> (too specific and + meaningless for people who do not know + Apache).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Documentation=</varname></term> + <listitem><para>A space-separated list of URIs referencing + documentation for this unit or its configuration. Accepted are + only URIs of the types <literal>http://</literal>, + <literal>https://</literal>, <literal>file:</literal>, + <literal>info:</literal>, <literal>man:</literal>. For more + information about the syntax of these URIs, see <citerefentry + project='man-pages'><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + The URIs should be listed in order of relevance, starting with + the most relevant. It is a good idea to first reference + documentation that explains what the unit's purpose is, + followed by how it is configured, followed by any other + related documentation. This option may be specified more than + once, in which case the specified list of URIs is merged. If + the empty string is assigned to this option, the list is reset + and all prior assignments will have no + effect.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Requires=</varname></term> + + <listitem><para>Configures requirement dependencies on other + units. If this unit gets activated, the units listed here will + be activated as well. If one of the other units gets + deactivated or its activation fails, this unit will be + deactivated. This option may be specified more than once or + multiple space-separated units may be specified in one option + in which case requirement dependencies for all listed names + will be created. Note that requirement dependencies do not + influence the order in which services are started or stopped. + This has to be configured independently with the + <varname>After=</varname> or <varname>Before=</varname> + options. If a unit <filename>foo.service</filename> requires a + unit <filename>bar.service</filename> as configured with + <varname>Requires=</varname> and no ordering is configured + with <varname>After=</varname> or <varname>Before=</varname>, + then both units will be started simultaneously and without any + delay between them if <filename>foo.service</filename> is + activated. Often, it is a better choice to use + <varname>Wants=</varname> instead of + <varname>Requires=</varname> in order to achieve a system that + is more robust when dealing with failing services.</para> + + <para>Note that dependencies of this type may also be + configured outside of the unit configuration file by adding a + symlink to a <filename>.requires/</filename> directory + accompanying the unit file. For details, see + above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Requisite=</varname></term> + + <listitem><para>Similar to <varname>Requires=</varname>. + However, if the units listed here are not started already, + they will not be started and the transaction will fail + immediately. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Wants=</varname></term> + + <listitem><para>A weaker version of + <varname>Requires=</varname>. Units listed in this option will + be started if the configuring unit is. However, if the listed + units fail to start or cannot be added to the transaction, + this has no impact on the validity of the transaction as a + whole. This is the recommended way to hook start-up of one + unit to the start-up of another unit.</para> + + <para>Note that dependencies of this type may also be + configured outside of the unit configuration file by adding + symlinks to a <filename>.wants/</filename> directory + accompanying the unit file. For details, see + above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>BindsTo=</varname></term> + + <listitem><para>Configures requirement dependencies, very + similar in style to <varname>Requires=</varname>, however in + addition to this behavior, it also declares that this unit is + stopped when any of the units listed suddenly disappears. + Units can suddenly, unexpectedly disappear if a service + terminates on its own choice, a device is unplugged or a mount + point unmounted without involvement of + systemd.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PartOf=</varname></term> + + <listitem><para>Configures dependencies similar to + <varname>Requires=</varname>, but limited to stopping and + restarting of units. When systemd stops or restarts the units + listed here, the action is propagated to this unit. Note that + this is a one-way dependency — changes to this unit do not + affect the listed units. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Conflicts=</varname></term> + + <listitem><para>A space-separated list of unit names. + Configures negative requirement dependencies. If a unit has a + <varname>Conflicts=</varname> setting on another unit, + starting the former will stop the latter and vice versa. Note + that this setting is independent of and orthogonal to the + <varname>After=</varname> and <varname>Before=</varname> + ordering dependencies.</para> + + <para>If a unit A that conflicts with a unit B is scheduled to + be started at the same time as B, the transaction will either + fail (in case both are required part of the transaction) or be + modified to be fixed (in case one or both jobs are not a + required part of the transaction). In the latter case, the job + that is not the required will be removed, or in case both are + not required, the unit that conflicts will be started and the + unit that is conflicted is stopped.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Before=</varname></term> + <term><varname>After=</varname></term> + + <listitem><para>A space-separated list of unit names. + Configures ordering dependencies between units. If a unit + <filename>foo.service</filename> contains a setting + <option>Before=bar.service</option> and both units are being + started, <filename>bar.service</filename>'s start-up is + delayed until <filename>foo.service</filename> is started up. + Note that this setting is independent of and orthogonal to the + requirement dependencies as configured by + <varname>Requires=</varname>. It is a common pattern to + include a unit name in both the <varname>After=</varname> and + <varname>Requires=</varname> option, in which case the unit + listed will be started before the unit that is configured with + these options. This option may be specified more than once, in + which case ordering dependencies for all listed names are + created. <varname>After=</varname> is the inverse of + <varname>Before=</varname>, i.e. while + <varname>After=</varname> ensures that the configured unit is + started after the listed unit finished starting up, + <varname>Before=</varname> ensures the opposite, i.e. that the + configured unit is fully started up before the listed unit is + started. Note that when two units with an ordering dependency + between them are shut down, the inverse of the start-up order + is applied. i.e. if a unit is configured with + <varname>After=</varname> on another unit, the former is + stopped before the latter if both are shut down. Given two units + with any ordering dependency between them, if one unit is shut + down and the other is started up, the shutdown is ordered + before the start-up. It doesn't matter if the ordering + dependency is <varname>After=</varname> or + <varname>Before=</varname>. It also doesn't matter which of the + two is shut down, as long as one is shut down and the other is + started up. The shutdown is ordered before the start-up in all + cases. If two units have no ordering dependencies between them, + they are shut down or started up simultaneously, and no ordering + takes place. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>OnFailure=</varname></term> + + <listitem><para>A space-separated list of one or more units + that are activated when this unit enters the + <literal>failed</literal> state.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PropagatesReloadTo=</varname></term> + <term><varname>ReloadPropagatedFrom=</varname></term> + + <listitem><para>A space-separated list of one or more units + where reload requests on this unit will be propagated to, or + reload requests on the other unit will be propagated to this + unit, respectively. Issuing a reload request on a unit will + automatically also enqueue a reload request on all units that + the reload request shall be propagated to via these two + settings.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>JoinsNamespaceOf=</varname></term> + + <listitem><para>For units that start processes (such as + service units), lists one or more other units whose network + and/or temporary file namespace to join. This only applies to + unit types which support the + <varname>PrivateNetwork=</varname> and + <varname>PrivateTmp=</varname> directives (see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). If a unit that has this setting set is started, + its processes will see the same <filename>/tmp</filename>, + <filename>/var/tmp</filename> and network namespace as one + listed unit that is started. If multiple listed units are + already started, it is not defined which namespace is joined. + Note that this setting only has an effect if + <varname>PrivateNetwork=</varname> and/or + <varname>PrivateTmp=</varname> is enabled for both the unit + that joins the namespace and the unit whose namespace is + joined.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RequiresMountsFor=</varname></term> + + <listitem><para>Takes a space-separated list of absolute + paths. Automatically adds dependencies of type + <varname>Requires=</varname> and <varname>After=</varname> for + all mount units required to access the specified path.</para> + + <para>Mount points marked with <option>noauto</option> are not + mounted automatically and will be ignored for the purposes of + this option. If such a mount should be a requirement for this + unit, direct dependencies on the mount units may be added + (<varname>Requires=</varname> and <varname>After=</varname> or + some other combination). </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>OnFailureJobMode=</varname></term> + + <listitem><para>Takes a value of + <literal>fail</literal>, + <literal>replace</literal>, + <literal>replace-irreversibly</literal>, + <literal>isolate</literal>, + <literal>flush</literal>, + <literal>ignore-dependencies</literal> or + <literal>ignore-requirements</literal>. Defaults to + <literal>replace</literal>. Specifies how the units listed in + <varname>OnFailure=</varname> will be enqueued. See + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <option>--job-mode=</option> option for details on the + possible values. If this is set to <literal>isolate</literal>, + only a single unit may be listed in + <varname>OnFailure=</varname>..</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IgnoreOnIsolate=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>true</option>, this unit will not be stopped when + isolating another unit. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>StopWhenUnneeded=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>true</option>, this unit will be stopped when it is no + longer used. Note that, in order to minimize the work to be + executed, systemd will not stop units by default unless they + are conflicting with other units, or the user explicitly + requested their shut down. If this option is set, a unit will + be automatically cleaned up if no other active unit requires + it. Defaults to <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RefuseManualStart=</varname></term> + <term><varname>RefuseManualStop=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>true</option>, this unit can only be activated or + deactivated indirectly. In this case, explicit start-up or + termination requested by the user is denied, however if it is + started or stopped as a dependency of another unit, start-up + or termination will succeed. This is mostly a safety feature + to ensure that the user does not accidentally activate units + that are not intended to be activated explicitly, and not + accidentally deactivate units that are not intended to be + deactivated. These options default to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>AllowIsolate=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>true</option>, this unit may be used with the + <command>systemctl isolate</command> command. Otherwise, this + will be refused. It probably is a good idea to leave this + disabled except for target units that shall be used similar to + runlevels in SysV init systems, just as a precaution to avoid + unusable system states. This option defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultDependencies=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>true</option>, (the default), a few default + dependencies will implicitly be created for the unit. The + actual dependencies created depend on the unit type. For + example, for service units, these dependencies ensure that the + service is started only after basic system initialization is + completed and is properly terminated on system shutdown. See + the respective man pages for details. Generally, only services + involved with early boot or late shutdown should set this + option to <option>false</option>. It is highly recommended to + leave this option enabled for the majority of common units. If + set to <option>false</option>, this option does not disable + all implicit dependencies, just non-essential + ones.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>JobTimeoutSec=</varname></term> + <term><varname>JobTimeoutAction=</varname></term> + <term><varname>JobTimeoutRebootArgument=</varname></term> + + <listitem><para>When a job for this unit is queued, a time-out may be configured. If this time limit is + reached, the job will be cancelled, the unit however will not change state or even enter the + <literal>failed</literal> mode. This value defaults to <literal>infinity</literal> (job timeouts disabled), + except for device units. NB: this timeout is independent from any unit-specific timeout (for example, the + timeout set with <varname>TimeoutStartSec=</varname> in service units) as the job timeout has no effect on the + unit itself, only on the job that might be pending for it. Or in other words: unit-specific timeouts are useful + to abort unit state changes, and revert them. The job timeout set with this option however is useful to abort + only the job waiting for the unit state to change.</para> + + <para><varname>JobTimeoutAction=</varname> + optionally configures an additional + action to take when the time-out is + hit. It takes the same values as the + per-service + <varname>StartLimitAction=</varname> + setting, see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. Defaults to + <option>none</option>. <varname>JobTimeoutRebootArgument=</varname> + configures an optional reboot string + to pass to the + <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system call.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>StartLimitIntervalSec=</varname></term> + <term><varname>StartLimitBurst=</varname></term> + + <listitem><para>Configure unit start rate limiting. By default, units which are started more than 5 times + within 10 seconds are not permitted to start any more times until the 10 second interval ends. With these two + options, this rate limiting may be modified. Use <varname>StartLimitIntervalSec=</varname> to configure the + checking interval (defaults to <varname>DefaultStartLimitIntervalSec=</varname> in manager configuration file, + set to 0 to disable any kind of rate limiting). Use <varname>StartLimitBurst=</varname> to configure how many + starts per interval are allowed (defaults to <varname>DefaultStartLimitBurst=</varname> in manager + configuration file). These configuration options are particularly useful in conjunction with the service + setting <varname>Restart=</varname> (see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>); however, + they apply to all kinds of starts (including manual), not just those triggered by the + <varname>Restart=</varname> logic. Note that units which are configured for <varname>Restart=</varname> and + which reach the start limit are not attempted to be restarted anymore; however, they may still be restarted + manually at a later point, from which point on, the restart logic is again activated. Note that + <command>systemctl reset-failed</command> will cause the restart rate counter for a service to be flushed, + which is useful if the administrator wants to manually start a unit and the start limit interferes with + that. Note that this rate-limiting is enforced after any unit condition checks are executed, and hence unit + activations with failing conditions are not counted by this rate limiting. Slice, target, device and scope + units do not enforce this setting, as they are unit types whose activation may either never fail, or may + succeed only a single time.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>StartLimitAction=</varname></term> + + <listitem><para>Configure the action to take if the rate limit configured with + <varname>StartLimitIntervalSec=</varname> and <varname>StartLimitBurst=</varname> is hit. Takes one of + <option>none</option>, <option>reboot</option>, <option>reboot-force</option>, + <option>reboot-immediate</option>, <option>poweroff</option>, <option>poweroff-force</option> or + <option>poweroff-immediate</option>. If <option>none</option> is set, hitting the rate limit will trigger no + action besides that the start will not be permitted. <option>reboot</option> causes a reboot following the + normal shutdown procedure (i.e. equivalent to <command>systemctl reboot</command>). + <option>reboot-force</option> causes a forced reboot which will terminate all processes forcibly but should + cause no dirty file systems on reboot (i.e. equivalent to <command>systemctl reboot -f</command>) and + <option>reboot-immediate</option> causes immediate execution of the + <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call, which + might result in data loss. Similarly, <option>poweroff</option>, <option>poweroff-force</option>, + <option>poweroff-immediate</option> have the effect of powering down the system with similar + semantics. Defaults to <option>none</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RebootArgument=</varname></term> + <listitem><para>Configure the optional argument for the + <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call if + <varname>StartLimitAction=</varname> or a service's <varname>FailureAction=</varname> is a reboot action. This + works just like the optional argument to <command>systemctl reboot</command> command.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ConditionArchitecture=</varname></term> + <term><varname>ConditionVirtualization=</varname></term> + <term><varname>ConditionHost=</varname></term> + <term><varname>ConditionKernelCommandLine=</varname></term> + <term><varname>ConditionSecurity=</varname></term> + <term><varname>ConditionCapability=</varname></term> + <term><varname>ConditionACPower=</varname></term> + <term><varname>ConditionNeedsUpdate=</varname></term> + <term><varname>ConditionFirstBoot=</varname></term> + <term><varname>ConditionPathExists=</varname></term> + <term><varname>ConditionPathExistsGlob=</varname></term> + <term><varname>ConditionPathIsDirectory=</varname></term> + <term><varname>ConditionPathIsSymbolicLink=</varname></term> + <term><varname>ConditionPathIsMountPoint=</varname></term> + <term><varname>ConditionPathIsReadWrite=</varname></term> + <term><varname>ConditionDirectoryNotEmpty=</varname></term> + <term><varname>ConditionFileNotEmpty=</varname></term> + <term><varname>ConditionFileIsExecutable=</varname></term> + + <!-- We do not document ConditionNull= + here, as it is not particularly + useful and probably just + confusing. --> + + <listitem><para>Before starting a unit, verify that the specified condition is true. If it is not true, the + starting of the unit will be (mostly silently) skipped, however all ordering dependencies of it are still + respected. A failing condition will not result in the unit being moved into a failure state. The condition is + checked at the time the queued start job is to be executed. Use condition expressions in order to silently skip + units that do not apply to the local running system, for example because the kernel or runtime environment + doesn't require its functionality. Use the various <varname>AssertArchitecture=</varname>, + <varname>AssertVirtualization=</varname>, … options for a similar mechanism that puts the unit in a failure + state and logs about the failed check (see below).</para> + + <para><varname>ConditionArchitecture=</varname> may be used to + check whether the system is running on a specific + architecture. Takes one of + <varname>x86</varname>, + <varname>x86-64</varname>, + <varname>ppc</varname>, + <varname>ppc-le</varname>, + <varname>ppc64</varname>, + <varname>ppc64-le</varname>, + <varname>ia64</varname>, + <varname>parisc</varname>, + <varname>parisc64</varname>, + <varname>s390</varname>, + <varname>s390x</varname>, + <varname>sparc</varname>, + <varname>sparc64</varname>, + <varname>mips</varname>, + <varname>mips-le</varname>, + <varname>mips64</varname>, + <varname>mips64-le</varname>, + <varname>alpha</varname>, + <varname>arm</varname>, + <varname>arm-be</varname>, + <varname>arm64</varname>, + <varname>arm64-be</varname>, + <varname>sh</varname>, + <varname>sh64</varname>, + <varname>m86k</varname>, + <varname>tilegx</varname>, + <varname>cris</varname> to test + against a specific architecture. The architecture is + determined from the information returned by + <citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> + and is thus subject to + <citerefentry><refentrytitle>personality</refentrytitle><manvolnum>2</manvolnum></citerefentry>. + Note that a <varname>Personality=</varname> setting in the + same unit file has no effect on this condition. A special + architecture name <varname>native</varname> is mapped to the + architecture the system manager itself is compiled for. The + test may be negated by prepending an exclamation mark.</para> + + <para><varname>ConditionVirtualization=</varname> may be used + to check whether the system is executed in a virtualized + environment and optionally test whether it is a specific + implementation. Takes either boolean value to check if being + executed in any virtualized environment, or one of + <varname>vm</varname> and + <varname>container</varname> to test against a generic type of + virtualization solution, or one of + <varname>qemu</varname>, + <varname>kvm</varname>, + <varname>zvm</varname>, + <varname>vmware</varname>, + <varname>microsoft</varname>, + <varname>oracle</varname>, + <varname>xen</varname>, + <varname>bochs</varname>, + <varname>uml</varname>, + <varname>openvz</varname>, + <varname>lxc</varname>, + <varname>lxc-libvirt</varname>, + <varname>systemd-nspawn</varname>, + <varname>docker</varname>, + <varname>rkt</varname> to test + against a specific implementation, or + <varname>private-users</varname> to check whether we are running in a user namespace. See + <citerefentry><refentrytitle>systemd-detect-virt</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for a full list of known virtualization technologies and their + identifiers. If multiple virtualization technologies are + nested, only the innermost is considered. The test may be + negated by prepending an exclamation mark.</para> + + <para><varname>ConditionHost=</varname> may be used to match + against the hostname or machine ID of the host. This either + takes a hostname string (optionally with shell style globs) + which is tested against the locally set hostname as returned + by + <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + or a machine ID formatted as string (see + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + The test may be negated by prepending an exclamation + mark.</para> + + <para><varname>ConditionKernelCommandLine=</varname> may be + used to check whether a specific kernel command line option is + set (or if prefixed with the exclamation mark unset). The + argument must either be a single word, or an assignment (i.e. + two words, separated <literal>=</literal>). In the former case + the kernel command line is searched for the word appearing as + is, or as left hand side of an assignment. In the latter case, + the exact assignment is looked for with right and left hand + side matching.</para> + + <para><varname>ConditionSecurity=</varname> may be used to + check whether the given security module is enabled on the + system. Currently, the recognized values are + <varname>selinux</varname>, + <varname>apparmor</varname>, + <varname>ima</varname>, + <varname>smack</varname> and + <varname>audit</varname>. The test may be negated by + prepending an exclamation mark.</para> + + <para><varname>ConditionCapability=</varname> may be used to + check whether the given capability exists in the capability + bounding set of the service manager (i.e. this does not check + whether capability is actually available in the permitted or + effective sets, see + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). Pass a capability name such as + <literal>CAP_MKNOD</literal>, possibly prefixed with an + exclamation mark to negate the check.</para> + + <para><varname>ConditionACPower=</varname> may be used to + check whether the system has AC power, or is exclusively + battery powered at the time of activation of the unit. This + takes a boolean argument. If set to <varname>true</varname>, + the condition will hold only if at least one AC connector of + the system is connected to a power source, or if no AC + connectors are known. Conversely, if set to + <varname>false</varname>, the condition will hold only if + there is at least one AC connector known and all AC connectors + are disconnected from a power source.</para> + + <para><varname>ConditionNeedsUpdate=</varname> takes one of + <filename>/var</filename> or <filename>/etc</filename> as + argument, possibly prefixed with a <literal>!</literal> (for + inverting the condition). This condition may be used to + conditionalize units on whether the specified directory + requires an update because <filename>/usr</filename>'s + modification time is newer than the stamp file + <filename>.updated</filename> in the specified directory. This + is useful to implement offline updates of the vendor operating + system resources in <filename>/usr</filename> that require + updating of <filename>/etc</filename> or + <filename>/var</filename> on the next following boot. Units + making use of this condition should order themselves before + <citerefentry><refentrytitle>systemd-update-done.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + to make sure they run before the stamp file's modification + time gets reset indicating a completed update.</para> + + <para><varname>ConditionFirstBoot=</varname> takes a boolean + argument. This condition may be used to conditionalize units + on whether the system is booting up with an unpopulated + <filename>/etc</filename> directory. This may be used to + populate <filename>/etc</filename> on the first boot after + factory reset, or when a new system instances boots up for the + first time.</para> + + <para>With <varname>ConditionPathExists=</varname> a file + existence condition is checked before a unit is started. If + the specified absolute path name does not exist, the condition + will fail. If the absolute path name passed to + <varname>ConditionPathExists=</varname> is prefixed with an + exclamation mark (<literal>!</literal>), the test is negated, + and the unit is only started if the path does not + exist.</para> + + <para><varname>ConditionPathExistsGlob=</varname> is similar + to <varname>ConditionPathExists=</varname>, but checks for the + existence of at least one file or directory matching the + specified globbing pattern.</para> + + <para><varname>ConditionPathIsDirectory=</varname> is similar + to <varname>ConditionPathExists=</varname> but verifies + whether a certain path exists and is a directory.</para> + + <para><varname>ConditionPathIsSymbolicLink=</varname> is + similar to <varname>ConditionPathExists=</varname> but + verifies whether a certain path exists and is a symbolic + link.</para> + + <para><varname>ConditionPathIsMountPoint=</varname> is similar + to <varname>ConditionPathExists=</varname> but verifies + whether a certain path exists and is a mount point.</para> + + <para><varname>ConditionPathIsReadWrite=</varname> is similar + to <varname>ConditionPathExists=</varname> but verifies + whether the underlying file system is readable and writable + (i.e. not mounted read-only).</para> + + <para><varname>ConditionDirectoryNotEmpty=</varname> is + similar to <varname>ConditionPathExists=</varname> but + verifies whether a certain path exists and is a non-empty + directory.</para> + + <para><varname>ConditionFileNotEmpty=</varname> is similar to + <varname>ConditionPathExists=</varname> but verifies whether a + certain path exists and refers to a regular file with a + non-zero size.</para> + + <para><varname>ConditionFileIsExecutable=</varname> is similar + to <varname>ConditionPathExists=</varname> but verifies + whether a certain path exists, is a regular file and marked + executable.</para> + + <para>If multiple conditions are specified, the unit will be + executed if all of them apply (i.e. a logical AND is applied). + Condition checks can be prefixed with a pipe symbol (|) in + which case a condition becomes a triggering condition. If at + least one triggering condition is defined for a unit, then the + unit will be executed if at least one of the triggering + conditions apply and all of the non-triggering conditions. If + you prefix an argument with the pipe symbol and an exclamation + mark, the pipe symbol must be passed first, the exclamation + second. Except for + <varname>ConditionPathIsSymbolicLink=</varname>, all path + checks follow symlinks. If any of these options is assigned + the empty string, the list of conditions is reset completely, + all previous condition settings (of any kind) will have no + effect.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>AssertArchitecture=</varname></term> + <term><varname>AssertVirtualization=</varname></term> + <term><varname>AssertHost=</varname></term> + <term><varname>AssertKernelCommandLine=</varname></term> + <term><varname>AssertSecurity=</varname></term> + <term><varname>AssertCapability=</varname></term> + <term><varname>AssertACPower=</varname></term> + <term><varname>AssertNeedsUpdate=</varname></term> + <term><varname>AssertFirstBoot=</varname></term> + <term><varname>AssertPathExists=</varname></term> + <term><varname>AssertPathExistsGlob=</varname></term> + <term><varname>AssertPathIsDirectory=</varname></term> + <term><varname>AssertPathIsSymbolicLink=</varname></term> + <term><varname>AssertPathIsMountPoint=</varname></term> + <term><varname>AssertPathIsReadWrite=</varname></term> + <term><varname>AssertDirectoryNotEmpty=</varname></term> + <term><varname>AssertFileNotEmpty=</varname></term> + <term><varname>AssertFileIsExecutable=</varname></term> + + <listitem><para>Similar to the <varname>ConditionArchitecture=</varname>, + <varname>ConditionVirtualization=</varname>, …, condition settings described above, these settings add + assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting + that is not met results in failure of the start job (which means this is logged loudly). Use assertion + expressions for units that cannot operate when specific requirements are not met, and when this is something + the administrator or user should look into.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SourcePath=</varname></term> + <listitem><para>A path to a configuration file this unit has + been generated from. This is primarily useful for + implementation of generator tools that convert configuration + from an external configuration file format into native unit + files. This functionality should not be used in normal + units.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>[Install] Section Options</title> + + <para>Unit files may include an <literal>[Install]</literal> section, which carries installation information for + the unit. This section is not interpreted by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> during runtime; it is + used by the <command>enable</command> and <command>disable</command> commands of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool during + installation of a unit. Note that settings in the <literal>[Install]</literal> section may not appear in + <filename>.d/*.conf</filename> unit file drop-ins (see above).</para> + + <variablelist class='unit-directives'> + <varlistentry> + <term><varname>Alias=</varname></term> + + <listitem><para>A space-separated list of additional names this unit shall be installed under. The names listed + here must have the same suffix (i.e. type) as the unit file name. This option may be specified more than once, + in which case all listed names are used. At installation time, <command>systemctl enable</command> will create + symlinks from these names to the unit filename. Note that not all unit types support such alias names, and this + setting is not supported for them. Specifically, mount, slice, swap, and automount units do not support + aliasing.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>WantedBy=</varname></term> + <term><varname>RequiredBy=</varname></term> + + <listitem><para>This option may be used more than once, or a + space-separated list of unit names may be given. A symbolic + link is created in the <filename>.wants/</filename> or + <filename>.requires/</filename> directory of each of the + listed units when this unit is installed by <command>systemctl + enable</command>. This has the effect that a dependency of + type <varname>Wants=</varname> or <varname>Requires=</varname> + is added from the listed unit to the current unit. The primary + result is that the current unit will be started when the + listed unit is started. See the description of + <varname>Wants=</varname> and <varname>Requires=</varname> in + the [Unit] section for details.</para> + + <para><command>WantedBy=foo.service</command> in a service + <filename>bar.service</filename> is mostly equivalent to + <command>Alias=foo.service.wants/bar.service</command> in the + same file. In case of template units, <command>systemctl + enable</command> must be called with an instance name, and + this instance will be added to the + <filename>.wants/</filename> or + <filename>.requires/</filename> list of the listed unit. E.g. + <command>WantedBy=getty.target</command> in a service + <filename>getty@.service</filename> will result in + <command>systemctl enable getty@tty2.service</command> + creating a + <filename>getty.target.wants/getty@tty2.service</filename> + link to <filename>getty@.service</filename>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Also=</varname></term> + + <listitem><para>Additional units to install/deinstall when + this unit is installed/deinstalled. If the user requests + installation/deinstallation of a unit with this option + configured, <command>systemctl enable</command> and + <command>systemctl disable</command> will automatically + install/uninstall units listed in this option as well.</para> + + <para>This option may be used more than once, or a + space-separated list of unit names may be + given.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultInstance=</varname></term> + + <listitem><para>In template unit files, this specifies for + which instance the unit shall be enabled if the template is + enabled without any explicitly set instance. This option has + no effect in non-template unit files. The specified string + must be usable as instance identifier.</para></listitem> + </varlistentry> + </variablelist> + + <para>The following specifiers are interpreted in the Install + section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v. For their meaning + see the next section. + </para> + </refsect1> + + <refsect1> + <title>Specifiers</title> + + <para>Many settings resolve specifiers which may be used to write + generic unit files referring to runtime or unit parameters that + are replaced when the unit files are loaded. The following + specifiers are understood:</para> + + <table> + <title>Specifiers available in unit files</title> + <tgroup cols='3' align='left' colsep='1' rowsep='1'> + <colspec colname="spec" /> + <colspec colname="mean" /> + <colspec colname="detail" /> + <thead> + <row> + <entry>Specifier</entry> + <entry>Meaning</entry> + <entry>Details</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>%n</literal></entry> + <entry>Full unit name</entry> + <entry></entry> + </row> + <row> + <entry><literal>%N</literal></entry> + <entry>Unescaped full unit name</entry> + <entry>Same as <literal>%n</literal>, but with escaping undone</entry> + </row> + <row> + <entry><literal>%p</literal></entry> + <entry>Prefix name</entry> + <entry>For instantiated units, this refers to the string before the <literal>@</literal> character of the unit name. For non-instantiated units, this refers to the name of the unit with the type suffix removed.</entry> + </row> + <row> + <entry><literal>%P</literal></entry> + <entry>Unescaped prefix name</entry> + <entry>Same as <literal>%p</literal>, but with escaping undone</entry> + </row> + <row> + <entry><literal>%i</literal></entry> + <entry>Instance name</entry> + <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix of the unit name.</entry> + </row> + <row> + <entry><literal>%I</literal></entry> + <entry>Unescaped instance name</entry> + <entry>Same as <literal>%i</literal>, but with escaping undone</entry> + </row> + <row> + <entry><literal>%f</literal></entry> + <entry>Unescaped filename</entry> + <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the unescaped prefix name prepended with <filename>/</filename>.</entry> + </row> + <row> + <entry><literal>%c</literal></entry> + <entry>Control group path of the unit</entry> + <entry>This path does not include the <filename>/sys/fs/cgroup/systemd/</filename> prefix.</entry> + </row> + <row> + <entry><literal>%r</literal></entry> + <entry>Control group path of the slice the unit is placed in</entry> + <entry>This usually maps to the parent control group path of <literal>%c</literal>.</entry> + </row> + <row> + <entry><literal>%R</literal></entry> + <entry>Root control group path below which slices and units are placed</entry> + <entry>For system instances, this resolves to <filename>/</filename>, except in containers, where this maps to the container's root control group path.</entry> + </row> + <row> + <entry><literal>%t</literal></entry> + <entry>Runtime directory</entry> + <entry>This is either <filename>/run</filename> (for the system manager) or the path <literal>$XDG_RUNTIME_DIR</literal> resolves to (for user managers).</entry> + </row> + <row> + <entry><literal>%u</literal></entry> + <entry>User name</entry> + <entry>This is the name of the user running the service manager instance. In case of the system manager this resolves to <literal>root</literal>.</entry> + </row> + <row> + <entry><literal>%U</literal></entry> + <entry>User UID</entry> + <entry>This is the numeric UID of the user running the service manager instance. In case of the system manager this resolves to <literal>0</literal>.</entry> + </row> + <row> + <entry><literal>%h</literal></entry> + <entry>User home directory</entry> + <entry>This is the home directory of the user running the service manager instance. In case of the system manager this resolves to <literal>/root</literal>.</entry> + </row> + <row> + <entry><literal>%s</literal></entry> + <entry>User shell</entry> + <entry>This is the shell of the user running the service manager instance. In case of the system manager this resolves to <literal>/bin/sh</literal>.</entry> + </row> + <row> + <entry><literal>%m</literal></entry> + <entry>Machine ID</entry> + <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry> + </row> + <row> + <entry><literal>%b</literal></entry> + <entry>Boot ID</entry> + <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry> + </row> + <row> + <entry><literal>%H</literal></entry> + <entry>Host name</entry> + <entry>The hostname of the running system at the point in time the unit configuration is loaded.</entry> + </row> + <row> + <entry><literal>%v</literal></entry> + <entry>Kernel release</entry> + <entry>Identical to <command>uname -r</command> output</entry> + </row> + <row> + <entry><literal>%%</literal></entry> + <entry>Single percent sign</entry> + <entry>Use <literal>%%</literal> in place of <literal>%</literal> to specify a single percent sign.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Please note that specifiers <literal>%U</literal>, + <literal>%h</literal>, <literal>%s</literal> are mostly useless + when systemd is running in system mode. PID 1 cannot query the + user account database for information, so the specifiers only work + as shortcuts for things which are already specified in a different + way in the unit file. They are fully functional when systemd is + running in <option>--user</option> mode.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Allowing units to be enabled</title> + + <para>The following snippet (highlighted) allows a unit (e.g. + <filename>foo.service</filename>) to be enabled via + <command>systemctl enable</command>:</para> + + <programlisting>[Unit] +Description=Foo + +[Service] +ExecStart=/usr/sbin/foo-daemon + +<emphasis>[Install]</emphasis> +<emphasis>WantedBy=multi-user.target</emphasis></programlisting> + + <para>After running <command>systemctl enable</command>, a + symlink + <filename>/etc/systemd/system/multi-user.target.wants/foo.service</filename> + linking to the actual unit will be created. It tells systemd to + pull in the unit when starting + <filename>multi-user.target</filename>. The inverse + <command>systemctl disable</command> will remove that symlink + again.</para> + </example> + + <example> + <title>Overriding vendor settings</title> + + <para>There are two methods of overriding vendor settings in + unit files: copying the unit file from + <filename>/usr/lib/systemd/system</filename> to + <filename>/etc/systemd/system</filename> and modifying the + chosen settings. Alternatively, one can create a directory named + <filename><replaceable>unit</replaceable>.d/</filename> within + <filename>/etc/systemd/system</filename> and place a drop-in + file <filename><replaceable>name</replaceable>.conf</filename> + there that only changes the specific settings one is interested + in. Note that multiple such drop-in files are read if + present.</para> + + <para>The advantage of the first method is that one easily + overrides the complete unit, the vendor unit is not parsed at + all anymore. It has the disadvantage that improvements to the + unit file by the vendor are not automatically incorporated on + updates.</para> + + <para>The advantage of the second method is that one only + overrides the settings one specifically wants, where updates to + the unit by the vendor automatically apply. This has the + disadvantage that some future updates by the vendor might be + incompatible with the local changes.</para> + + <para>Note that for drop-in files, if one wants to remove + entries from a setting that is parsed as a list (and is not a + dependency), such as <varname>ConditionPathExists=</varname> (or + e.g. <varname>ExecStart=</varname> in service units), one needs + to first clear the list before re-adding all entries except the + one that is to be removed. See below for an example.</para> + + <para>This also applies for user instances of systemd, but with + different locations for the unit files. See the section on unit + load paths for further details.</para> + + <para>Suppose there is a vendor-supplied unit + <filename>/usr/lib/systemd/system/httpd.service</filename> with + the following contents:</para> + + <programlisting>[Unit] +Description=Some HTTP server +After=remote-fs.target sqldb.service +Requires=sqldb.service +AssertPathExists=/srv/webserver + +[Service] +Type=notify +ExecStart=/usr/sbin/some-fancy-httpd-server +Nice=5 + +[Install] +WantedBy=multi-user.target</programlisting> + + <para>Now one wants to change some settings as an administrator: + firstly, in the local setup, <filename>/srv/webserver</filename> + might not exist, because the HTTP server is configured to use + <filename>/srv/www</filename> instead. Secondly, the local + configuration makes the HTTP server also depend on a memory + cache service, <filename>memcached.service</filename>, that + should be pulled in (<varname>Requires=</varname>) and also be + ordered appropriately (<varname>After=</varname>). Thirdly, in + order to harden the service a bit more, the administrator would + like to set the <varname>PrivateTmp=</varname> setting (see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). And lastly, the administrator would like to reset + the niceness of the service to its default value of 0.</para> + + <para>The first possibility is to copy the unit file to + <filename>/etc/systemd/system/httpd.service</filename> and + change the chosen settings:</para> + + <programlisting>[Unit] +Description=Some HTTP server +After=remote-fs.target sqldb.service <emphasis>memcached.service</emphasis> +Requires=sqldb.service <emphasis>memcached.service</emphasis> +AssertPathExists=<emphasis>/srv/www</emphasis> + +[Service] +Type=notify +ExecStart=/usr/sbin/some-fancy-httpd-server +<emphasis>Nice=0</emphasis> +<emphasis>PrivateTmp=yes</emphasis> + +[Install] +WantedBy=multi-user.target</programlisting> + + <para>Alternatively, the administrator could create a drop-in + file + <filename>/etc/systemd/system/httpd.service.d/local.conf</filename> + with the following contents:</para> + + <programlisting>[Unit] +After=memcached.service +Requires=memcached.service +# Reset all assertions and then re-add the condition we want +AssertPathExists= +AssertPathExists=/srv/www + +[Service] +Nice=0 +PrivateTmp=yes</programlisting> + + <para>Note that dependencies (<varname>After=</varname>, etc.) + cannot be reset to an empty list, so dependencies can only be + added in drop-ins. If you want to remove dependencies, you have + to override the entire unit.</para> + + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/systemd.xml b/src/grp-system/systemd/systemd.xml new file mode 100644 index 0000000000..79d8aedbbc --- /dev/null +++ b/src/grp-system/systemd/systemd.xml @@ -0,0 +1,1157 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd</refname> + <refname>init</refname> + <refpurpose>systemd system and service manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd <arg choice="opt" rep="repeat">OPTIONS</arg></command> + </cmdsynopsis> + <cmdsynopsis> + <command>init <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>systemd is a system and service manager for GNU/Linux operating + systems. When run as first process on boot (as PID 1), it acts as + init system that brings up and maintains userspace + services.</para> + + <para>For compatibility with SysV, if systemd is called as + <command>init</command> and a PID that is not 1, it will execute + <command>telinit</command> and pass all command line arguments + unmodified. That means <command>init</command> and + <command>telinit</command> are mostly equivalent when invoked from + normal login sessions. See + <citerefentry><refentrytitle>telinit</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for more information.</para> + + <para>When run as a system instance, systemd interprets the + configuration file <filename>system.conf</filename> and the files + in <filename>system.conf.d</filename> directories; when run as a + user instance, systemd interprets the configuration file + <filename>user.conf</filename> and the files in + <filename>user.conf.d</filename> directories. See + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--test</option></term> + + <listitem><para>Determine startup sequence, dump it and exit. + This is an option useful for debugging only.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dump-configuration-items</option></term> + + <listitem><para>Dump understood unit configuration items. This + outputs a terse but complete list of configuration items + understood in unit definition files.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unit=</option></term> + + <listitem><para>Set default unit to activate on startup. If + not specified, defaults to + <filename>default.target</filename>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--system</option></term> + <term><option>--user</option></term> + + <listitem><para>For <option>--system</option>, tell systemd to + run a system instance, even if the process ID is not 1, i.e. + systemd is not run as init process. <option>--user</option> + does the opposite, running a user instance even if the process + ID is 1. Normally, it should not be necessary to pass these + options, as systemd automatically detects the mode it is + started in. These options are hence of little use except for + debugging. Note that it is not supported booting and + maintaining a full system with systemd running in + <option>--system</option> mode, but PID not 1. In practice, + passing <option>--system</option> explicitly is only useful in + conjunction with <option>--test</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dump-core</option></term> + + <listitem><para>Enable core dumping on crash. This switch has + no effect when running as user instance. This setting may also + be enabled during boot on the kernel command line via the + <varname>systemd.dump_core=</varname> option, see + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--crash-vt=</option><replaceable>VT</replaceable></term> + + <listitem><para>Switch to a specific virtual console (VT) on + crash. Takes a positive integer in the range 1–63, or a + boolean argument. If an integer is passed, selects which VT to + switch to. If <constant>yes</constant>, the VT kernel messages + are written to is selected. If <constant>no</constant>, no VT + switch is attempted. This switch has no effect when running as + user instance. This setting may also be enabled during boot, + on the kernel command line via the + <varname>systemd.crash_vt=</varname> option, see + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--crash-shell</option></term> + + <listitem><para>Run a shell on crash. This switch has no + effect when running as user instance. This setting may also be + enabled during boot, on the kernel command line via the + <varname>systemd.crash_shell=</varname> option, see + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--crash-reboot</option></term> + + <listitem><para>Automatically reboot the system on crash. This + switch has no effect when running as user instance. This + setting may also be enabled during boot, on the kernel command + line via the <varname>systemd.crash_reboot=</varname> option, + see below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--confirm-spawn</option></term> + + <listitem><para>Ask for confirmation when spawning processes. + This switch has no effect when run as user + instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--show-status=</option></term> + + <listitem><para>Show terse service status information while + booting. This switch has no effect when run as user instance. + Takes a boolean argument which may be omitted which is + interpreted as <option>true</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-target=</option></term> + + <listitem><para>Set log target. Argument must be one of + <option>console</option>, + <option>journal</option>, + <option>kmsg</option>, + <option>journal-or-kmsg</option>, + <option>null</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-level=</option></term> + + <listitem><para>Set log level. As + argument this accepts a numerical log + level or the well-known <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + symbolic names (lowercase): + <option>emerg</option>, + <option>alert</option>, + <option>crit</option>, + <option>err</option>, + <option>warning</option>, + <option>notice</option>, + <option>info</option>, + <option>debug</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-color=</option></term> + + <listitem><para>Highlight important log messages. Argument is + a boolean value. If the argument is omitted, it defaults to + <option>true</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-location=</option></term> + + <listitem><para>Include code location in log messages. This is + mostly relevant for debugging purposes. Argument is a boolean + value. If the argument is omitted it defaults to + <option>true</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--default-standard-output=</option></term> + <term><option>--default-standard-error=</option></term> + + <listitem><para>Sets the default output or error output for + all services and sockets, respectively. That is, controls the + default for <option>StandardOutput=</option> and + <option>StandardError=</option> (see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). Takes one of + <option>inherit</option>, + <option>null</option>, + <option>tty</option>, + <option>journal</option>, + <option>journal+console</option>, + <option>syslog</option>, + <option>syslog+console</option>, + <option>kmsg</option>, + <option>kmsg+console</option>. If the + argument is omitted + <option>--default-standard-output=</option> defaults to + <option>journal</option> and + <option>--default-standard-error=</option> to + <option>inherit</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--machine-id=</option></term> + + <listitem><para>Override the machine-id set on the hard drive, + useful for network booting or for containers. May not be set + to all zeros.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + </refsect1> + + <refsect1> + <title>Concepts</title> + + <para>systemd provides a dependency system between various + entities called "units" of 11 different types. Units encapsulate + various objects that are relevant for system boot-up and + maintenance. The majority of units are configured in unit + configuration files, whose syntax and basic set of options is + described in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + however some are created automatically from other configuration, + dynamically from system state or programmatically at runtime. + Units may be "active" (meaning started, bound, plugged in, ..., + depending on the unit type, see below), or "inactive" (meaning + stopped, unbound, unplugged, ...), as well as in the process of + being activated or deactivated, i.e. between the two states (these + states are called "activating", "deactivating"). A special + "failed" state is available as well, which is very similar to + "inactive" and is entered when the service failed in some way + (process returned error code on exit, or crashed, or an operation + timed out). If this state is entered, the cause will be logged, + for later reference. Note that the various unit types may have a + number of additional substates, which are mapped to the five + generalized unit states described here.</para> + + <para>The following unit types are available:</para> + + <orderedlist> + <listitem><para>Service units, which start and control daemons + and the processes they consist of. For details, see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Socket units, which encapsulate local IPC or + network sockets in the system, useful for socket-based + activation. For details about socket units, see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + for details on socket-based activation and other forms of + activation, see + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Target units are useful to group units, or + provide well-known synchronization points during boot-up, see + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Device units expose kernel devices in systemd + and may be used to implement device-based activation. For + details, see + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Mount units control mount points in the file + system, for details see + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Automount units provide automount capabilities, + for on-demand mounting of file systems as well as parallelized + boot-up. See + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Timer units are useful for triggering activation + of other units based on timers. You may find details in + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Swap units are very similar to mount units and + encapsulate memory swap partitions or files of the operating + system. They are described in + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Path units may be used to activate other + services when file system objects change or are modified. See + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Slice units may be used to group units which + manage system processes (such as service and scope units) in a + hierarchical tree for resource management purposes. See + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Scope units are similar to service units, but + manage foreign processes instead of starting them as well. See + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + </orderedlist> + + <para>Units are named as their configuration files. Some units + have special semantics. A detailed list is available in + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>systemd knows various kinds of dependencies, including + positive and negative requirement dependencies (i.e. + <varname>Requires=</varname> and <varname>Conflicts=</varname>) as + well as ordering dependencies (<varname>After=</varname> and + <varname>Before=</varname>). NB: ordering and requirement + dependencies are orthogonal. If only a requirement dependency + exists between two units (e.g. <filename>foo.service</filename> + requires <filename>bar.service</filename>), but no ordering + dependency (e.g. <filename>foo.service</filename> after + <filename>bar.service</filename>) and both are requested to start, + they will be started in parallel. It is a common pattern that both + requirement and ordering dependencies are placed between two + units. Also note that the majority of dependencies are implicitly + created and maintained by systemd. In most cases, it should be + unnecessary to declare additional dependencies manually, however + it is possible to do this.</para> + + <para>Application programs and units (via dependencies) may + request state changes of units. In systemd, these requests are + encapsulated as 'jobs' and maintained in a job queue. Jobs may + succeed or can fail, their execution is ordered based on the + ordering dependencies of the units they have been scheduled + for.</para> + + <para>On boot systemd activates the target unit + <filename>default.target</filename> whose job is to activate + on-boot services and other on-boot units by pulling them in via + dependencies. Usually, the unit name is just an alias (symlink) for + either <filename>graphical.target</filename> (for fully-featured + boots into the UI) or <filename>multi-user.target</filename> (for + limited console-only boots for use in embedded or server + environments, or similar; a subset of graphical.target). However, + it is at the discretion of the administrator to configure it as an + alias to any other target unit. See + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about these target units.</para> + + <para>Processes systemd spawns are placed in individual Linux + control groups named after the unit which they belong to in the + private systemd hierarchy. (see <ulink + url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink> + for more information about control groups, or short "cgroups"). + systemd uses this to effectively keep track of processes. Control + group information is maintained in the kernel, and is accessible + via the file system hierarchy (beneath + <filename>/sys/fs/cgroup/systemd/</filename>), or in tools such as + <citerefentry project='man-pages'><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry> + or + <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> + (<command>ps xawf -eo pid,user,cgroup,args</command> is + particularly useful to list all processes and the systemd units + they belong to.).</para> + + <para>systemd is compatible with the SysV init system to a large + degree: SysV init scripts are supported and simply read as an + alternative (though limited) configuration file format. The SysV + <filename>/dev/initctl</filename> interface is provided, and + compatibility implementations of the various SysV client tools are + available. In addition to that, various established Unix + functionality such as <filename>/etc/fstab</filename> or the + <filename>utmp</filename> database are supported.</para> + + <para>systemd has a minimal transaction system: if a unit is + requested to start up or shut down it will add it and all its + dependencies to a temporary transaction. Then, it will verify if + the transaction is consistent (i.e. whether the ordering of all + units is cycle-free). If it is not, systemd will try to fix it up, + and removes non-essential jobs from the transaction that might + remove the loop. Also, systemd tries to suppress non-essential + jobs in the transaction that would stop a running service. Finally + it is checked whether the jobs of the transaction contradict jobs + that have already been queued, and optionally the transaction is + aborted then. If all worked out and the transaction is consistent + and minimized in its impact it is merged with all already + outstanding jobs and added to the run queue. Effectively this + means that before executing a requested operation, systemd will + verify that it makes sense, fixing it if possible, and only + failing if it really cannot work.</para> + + <para>Systemd contains native implementations of various tasks + that need to be executed as part of the boot process. For example, + it sets the hostname or configures the loopback network device. It + also sets up and mounts various API file systems, such as + <filename>/sys</filename> or <filename>/proc</filename>.</para> + + <para>For more information about the concepts and + ideas behind systemd, please refer to the + <ulink url="http://0pointer.de/blog/projects/systemd.html">Original Design Document</ulink>.</para> + + <para>Note that some but not all interfaces provided + by systemd are covered by the + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface + Stability Promise</ulink>.</para> + + <para>Units may be generated dynamically at boot and system + manager reload time, for example based on other configuration + files or parameters passed on the kernel command line. For details, see + <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>Systems which invoke systemd in a container or initrd + environment should implement the + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container Interface</ulink> or + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/InitrdInterface">initrd Interface</ulink> + specifications, respectively.</para> + </refsect1> + + <refsect1> + <title>Directories</title> + + <variablelist> + <varlistentry> + <term>System unit directories</term> + + <listitem><para>The systemd system manager reads unit + configuration from various directories. Packages that want to + install unit files shall place them in the directory returned + by <command>pkg-config systemd + --variable=systemdsystemunitdir</command>. Other directories + checked are <filename>/usr/local/lib/systemd/system</filename> + and <filename>/usr/lib/systemd/system</filename>. User + configuration always takes precedence. <command>pkg-config + systemd --variable=systemdsystemconfdir</command> returns the + path of the system configuration directory. Packages should + alter the content of these directories only with the + <command>enable</command> and <command>disable</command> + commands of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool. Full list of directories is provided in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>User unit directories</term> + + <listitem><para>Similar rules apply for the user unit + directories. However, here the + <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG + Base Directory specification</ulink> is followed to find + units. Applications should place their unit files in the + directory returned by <command>pkg-config systemd + --variable=systemduserunitdir</command>. Global configuration + is done in the directory reported by <command>pkg-config + systemd --variable=systemduserconfdir</command>. The + <command>enable</command> and <command>disable</command> + commands of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool can handle both global (i.e. for all users) and private + (for one user) enabling/disabling of units. Full list of + directories is provided in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>SysV init scripts directory</term> + + <listitem><para>The location of the SysV init script directory + varies between distributions. If systemd cannot find a native + unit file for a requested service, it will look for a SysV + init script of the same name (with the + <filename>.service</filename> suffix + removed).</para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>SysV runlevel link farm directory</term> + + <listitem><para>The location of the SysV runlevel link farm + directory varies between distributions. systemd will take the + link farm into account when figuring out whether a service + shall be enabled. Note that a service unit with a native unit + configuration file cannot be started by activating it in the + SysV runlevel link farm.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Signals</title> + + <variablelist> + <varlistentry> + <term><constant>SIGTERM</constant></term> + + <listitem><para>Upon receiving this signal the systemd system + manager serializes its state, reexecutes itself and + deserializes the saved state again. This is mostly equivalent + to <command>systemctl daemon-reexec</command>.</para> + + <para>systemd user managers will start the + <filename>exit.target</filename> unit when this signal is + received. This is mostly equivalent to <command>systemctl + --user start exit.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGINT</constant></term> + + <listitem><para>Upon receiving this signal the systemd system + manager will start the + <filename>ctrl-alt-del.target</filename> unit. This is mostly + equivalent to <command>systemctl start + ctl-alt-del.target</command>. If this signal is received more + than 7 times per 2s, an immediate reboot is triggered. + Note that pressing Ctrl-Alt-Del on the console will trigger + this signal. Hence, if a reboot is hanging, pressing + Ctrl-Alt-Del more than 7 times in 2s is a relatively safe way + to trigger an immediate reboot.</para> + + <para>systemd user managers treat this signal the same way as + <constant>SIGTERM</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGWINCH</constant></term> + + <listitem><para>When this signal is received the systemd + system manager will start the + <filename>kbrequest.target</filename> unit. This is mostly + equivalent to <command>systemctl start + kbrequest.target</command>.</para> + + <para>This signal is ignored by systemd user + managers.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGPWR</constant></term> + + <listitem><para>When this signal is received the systemd + manager will start the <filename>sigpwr.target</filename> + unit. This is mostly equivalent to <command>systemctl start + sigpwr.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGUSR1</constant></term> + + <listitem><para>When this signal is received the systemd + manager will try to reconnect to the D-Bus + bus.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGUSR2</constant></term> + + <listitem><para>When this signal is received the systemd + manager will log its complete state in human-readable form. + The data logged is the same as printed by + <command>systemd-analyze dump</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGHUP</constant></term> + + <listitem><para>Reloads the complete daemon configuration. + This is mostly equivalent to <command>systemctl + daemon-reload</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+0</constant></term> + + <listitem><para>Enters default mode, starts the + <filename>default.target</filename> unit. This is mostly + equivalent to <command>systemctl start + default.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+1</constant></term> + + <listitem><para>Enters rescue mode, starts the + <filename>rescue.target</filename> unit. This is mostly + equivalent to <command>systemctl isolate + rescue.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+2</constant></term> + + <listitem><para>Enters emergency mode, starts the + <filename>emergency.service</filename> unit. This is mostly + equivalent to <command>systemctl isolate + emergency.service</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+3</constant></term> + + <listitem><para>Halts the machine, starts the + <filename>halt.target</filename> unit. This is mostly + equivalent to <command>systemctl start + halt.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+4</constant></term> + + <listitem><para>Powers off the machine, starts the + <filename>poweroff.target</filename> unit. This is mostly + equivalent to <command>systemctl start + poweroff.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+5</constant></term> + + <listitem><para>Reboots the machine, starts the + <filename>reboot.target</filename> unit. This is mostly + equivalent to <command>systemctl start + reboot.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+6</constant></term> + + <listitem><para>Reboots the machine via kexec, starts the + <filename>kexec.target</filename> unit. This is mostly + equivalent to <command>systemctl start + kexec.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+13</constant></term> + + <listitem><para>Immediately halts the machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+14</constant></term> + + <listitem><para>Immediately powers off the machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+15</constant></term> + + <listitem><para>Immediately reboots the machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+16</constant></term> + + <listitem><para>Immediately reboots the machine with kexec.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+20</constant></term> + + <listitem><para>Enables display of status messages on the + console, as controlled via + <varname>systemd.show_status=1</varname> on the kernel command + line.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+21</constant></term> + + <listitem><para>Disables display of + status messages on the console, as + controlled via + <varname>systemd.show_status=0</varname> + on the kernel command + line.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+22</constant></term> + <term><constant>SIGRTMIN+23</constant></term> + + <listitem><para>Sets the log level to <literal>debug</literal> + (or <literal>info</literal> on + <constant>SIGRTMIN+23</constant>), as controlled via + <varname>systemd.log_level=debug</varname> (or + <varname>systemd.log_level=info</varname> on + <constant>SIGRTMIN+23</constant>) on the kernel command + line.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+24</constant></term> + + <listitem><para>Immediately exits the manager (only available + for --user instances).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+26</constant></term> + <term><constant>SIGRTMIN+27</constant></term> + <term><constant>SIGRTMIN+28</constant></term> + + <listitem><para>Sets the log level to + <literal>journal-or-kmsg</literal> (or + <literal>console</literal> on + <constant>SIGRTMIN+27</constant>, <literal>kmsg</literal> on + <constant>SIGRTMIN+28</constant>), as controlled via + <varname>systemd.log_target=journal-or-kmsg</varname> (or + <varname>systemd.log_target=console</varname> on + <constant>SIGRTMIN+27</constant> or + <varname>systemd.log_target=kmsg</varname> on + <constant>SIGRTMIN+28</constant>) on the kernel command + line.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$SYSTEMD_LOG_LEVEL</varname></term> + <listitem><para>systemd reads the log level from this + environment variable. This can be overridden with + <option>--log-level=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_LOG_TARGET</varname></term> + <listitem><para>systemd reads the log target from this + environment variable. This can be overridden with + <option>--log-target=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_LOG_COLOR</varname></term> + <listitem><para>Controls whether systemd highlights important + log messages. This can be overridden with + <option>--log-color=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_LOG_LOCATION</varname></term> + <listitem><para>Controls whether systemd prints the code + location along with log messages. This can be overridden with + <option>--log-location=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$XDG_CONFIG_HOME</varname></term> + <term><varname>$XDG_CONFIG_DIRS</varname></term> + <term><varname>$XDG_DATA_HOME</varname></term> + <term><varname>$XDG_DATA_DIRS</varname></term> + + <listitem><para>The systemd user manager uses these variables + in accordance to the <ulink + url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG + Base Directory specification</ulink> to find its + configuration.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_UNIT_PATH</varname></term> + + <listitem><para>Controls where systemd looks for unit + files.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_SYSVINIT_PATH</varname></term> + + <listitem><para>Controls where systemd looks for SysV init + scripts.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_SYSVRCND_PATH</varname></term> + + <listitem><para>Controls where systemd looks for SysV init + script runlevel link farms.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_COLORS</varname></term> + + <listitem><para>The value must be a boolean. Controls whether colorized output should be + generated. This can be specified to override the decision that <command>systemd</command> + makes based on <varname>$TERM</varname> and what the console is connected to.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>$LISTEN_PID</varname></term> + <term><varname>$LISTEN_FDS</varname></term> + <term><varname>$LISTEN_FDNAMES</varname></term> + + <listitem><para>Set by systemd for supervised processes during + socket-based activation. See + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$NOTIFY_SOCKET</varname></term> + + <listitem><para>Set by systemd for supervised processes for + status and start-up completion notification. See + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para>When run as system instance systemd parses a number of + kernel command line arguments<footnote><para>If run inside a Linux + container these arguments may be passed as command line arguments + to systemd itself, next to any of the command line options listed + in the Options section above. If run outside of Linux containers, + these arguments are parsed from <filename>/proc/cmdline</filename> + instead.</para></footnote>:</para> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>systemd.unit=</varname></term> + <term><varname>rd.systemd.unit=</varname></term> + + <listitem><para>Overrides the unit to activate on boot. + Defaults to <filename>default.target</filename>. This may be + used to temporarily boot into a different boot unit, for + example <filename>rescue.target</filename> or + <filename>emergency.service</filename>. See + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about these units. The option prefixed with + <literal>rd.</literal> is honored only in the initial RAM disk + (initrd), while the one that is not prefixed only in the main + system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.dump_core=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>yes</option>, the systemd manager (PID 1) dumps core + when it crashes. Otherwise, no core dump is created. Defaults + to <option>yes</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.crash_chvt=</varname></term> + + <listitem><para>Takes a positive integer, or a boolean + argument. If a positive integer (in the range 1–63) is + specified, the system manager (PID 1) will activate the specified + virtual terminal (VT) when it crashes. Defaults to + <constant>no</constant>, meaning that no such switch is + attempted. If set to <constant>yes</constant>, the VT the + kernel messages are written to is selected.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.crash_shell=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>yes</option>, the system manager (PID 1) spawns a + shell when it crashes, after a 10s delay. Otherwise, no shell + is spawned. Defaults to <option>no</option>, for security + reasons, as the shell is not protected by password + authentication.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.crash_reboot=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>yes</option>, the system manager (PID 1) will reboot + the machine automatically when it crashes, after a 10s delay. + Otherwise, the system will hang indefinitely. Defaults to + <option>no</option>, in order to avoid a reboot loop. If + combined with <varname>systemd.crash_shell=</varname>, the + system is rebooted after the shell exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.confirm_spawn=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>yes</option>, the system manager (PID 1) asks for + confirmation when spawning processes. Defaults to + <option>no</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.show_status=</varname></term> + + <listitem><para>Takes a boolean argument or the constant + <constant>auto</constant>. If <option>yes</option>, the + systemd manager (PID 1) shows terse service status updates on + the console during bootup. <constant>auto</constant> behaves + like <option>false</option> until a service fails or there is + a significant delay in boot. Defaults to + <option>yes</option>, unless <option>quiet</option> is passed + as kernel command line option, in which case it defaults to + <constant>auto</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.log_target=</varname></term> + <term><varname>systemd.log_level=</varname></term> + <term><varname>systemd.log_color=</varname></term> + <term><varname>systemd.log_location=</varname></term> + + <listitem><para>Controls log output, with the same effect as + the <varname>$SYSTEMD_LOG_TARGET</varname>, + <varname>$SYSTEMD_LOG_LEVEL</varname>, + <varname>$SYSTEMD_LOG_COLOR</varname>, + <varname>$SYSTEMD_LOG_LOCATION</varname> environment variables + described above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.default_standard_output=</varname></term> + <term><varname>systemd.default_standard_error=</varname></term> + <listitem><para>Controls default standard output and error + output for services, with the same effect as the + <option>--default-standard-output=</option> and + <option>--default-standard-error=</option> command line + arguments described above, respectively.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.setenv=</varname></term> + + <listitem><para>Takes a string argument in the form + VARIABLE=VALUE. May be used to set default environment + variables to add to forked child processes. May be used more + than once to set multiple variables.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.machine_id=</varname></term> + + <listitem><para>Takes a 32 character hex value to be + used for setting the machine-id. Intended mostly for + network booting where the same machine-id is desired + for every boot.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>quiet</varname></term> + + <listitem><para>Turn off status output at boot, much like + <varname>systemd.show_status=false</varname> would. Note that + this option is also read by the kernel itself and disables + kernel log output. Passing this option hence turns off the + usual output from both the system manager and the kernel. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>debug</varname></term> + + <listitem><para>Turn on debugging output. This is equivalent + to <varname>systemd.log_level=debug</varname>. Note that this + option is also read by the kernel itself and enables kernel + debug output. Passing this option hence turns on the debug + output from both the system manager and the + kernel.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>emergency</varname></term> + <term><varname>rd.emergency</varname></term> + <term><varname>-b</varname></term> + + <listitem><para>Boot into emergency mode. This is equivalent + to <varname>systemd.unit=emergency.target</varname> or + <varname>rd.systemd.unit=emergency.target</varname>, respectively, and + provided for compatibility reasons and to be easier to type.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>rescue</varname></term> + <term><varname>rd.rescue</varname></term> + <term><varname>single</varname></term> + <term><varname>s</varname></term> + <term><varname>S</varname></term> + <term><varname>1</varname></term> + + <listitem><para>Boot into rescue mode. This is equivalent to + <varname>systemd.unit=rescue.target</varname> or + <varname>rd.systemd.unit=rescue.target</varname>, respectively, and + provided for compatibility reasons and to be easier to type.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>2</varname></term> + <term><varname>3</varname></term> + <term><varname>4</varname></term> + <term><varname>5</varname></term> + + <listitem><para>Boot into the specified legacy SysV runlevel. + These are equivalent to + <varname>systemd.unit=runlevel2.target</varname>, + <varname>systemd.unit=runlevel3.target</varname>, + <varname>systemd.unit=runlevel4.target</varname>, and + <varname>systemd.unit=runlevel5.target</varname>, + respectively, and provided for compatibility reasons and to be + easier to type.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>locale.LANG=</varname></term> + <term><varname>locale.LANGUAGE=</varname></term> + <term><varname>locale.LC_CTYPE=</varname></term> + <term><varname>locale.LC_NUMERIC=</varname></term> + <term><varname>locale.LC_TIME=</varname></term> + <term><varname>locale.LC_COLLATE=</varname></term> + <term><varname>locale.LC_MONETARY=</varname></term> + <term><varname>locale.LC_MESSAGES=</varname></term> + <term><varname>locale.LC_PAPER=</varname></term> + <term><varname>locale.LC_NAME=</varname></term> + <term><varname>locale.LC_ADDRESS=</varname></term> + <term><varname>locale.LC_TELEPHONE=</varname></term> + <term><varname>locale.LC_MEASUREMENT=</varname></term> + <term><varname>locale.LC_IDENTIFICATION=</varname></term> + + <listitem><para>Set the system locale to use. This overrides + the settings in <filename>/etc/locale.conf</filename>. For + more information, see + <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry project='man-pages'><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + </variablelist> + + <para>For other kernel command line parameters understood by + components of the core OS, please refer to + <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Sockets and FIFOs</title> + + <variablelist> + <varlistentry> + <term><filename>/run/systemd/notify</filename></term> + + <listitem><para>Daemon status notification socket. This is an + <constant>AF_UNIX</constant> datagram socket and is used to + implement the daemon notification logic as implemented by + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><filename>/run/systemd/private</filename></term> + + <listitem><para>Used internally as communication channel + between + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and the systemd process. This is an + <constant>AF_UNIX</constant> stream socket. This interface is + private to systemd and should not be used in external + projects.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/dev/initctl</filename></term> + + <listitem><para>Limited compatibility support for the SysV + client interface, as implemented by the + <filename>systemd-initctl.service</filename> unit. This is a + named pipe in the file system. This interface is obsolete and + should not be used in new applications.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + The <ulink url="http://www.freedesktop.org/wiki/Software/systemd/">systemd Homepage</ulink>, + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-notify</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/grp-system/systemd/triggers.systemd.in b/src/grp-system/systemd/triggers.systemd.in new file mode 100644 index 0000000000..0d8c303136 --- /dev/null +++ b/src/grp-system/systemd/triggers.systemd.in @@ -0,0 +1,66 @@ +# -*- Mode: rpm-spec; indent-tabs-mode: nil -*- */ +# +# This file is part of systemd. +# +# Copyright 2015 Zbigniew Jędrzejewski-Szmek +# +# systemd is free software; you can redistribute it and/or modify it +# under the terms of the GNU Lesser General Public License as published by +# the Free Software Foundation; either version 2.1 of the License, or +# (at your option) any later version. +# +# systemd is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public License +# along with systemd; If not, see <http://www.gnu.org/licenses/>. + +# The contents of this are an example to be copied into systemd.spec. +# +# Minimum rpm version supported: 4.13.0 + +%transfiletriggerin -P 900900 -p <lua> -- @systemunitdir@ /etc/systemd/system +-- This script will run after any package is initially installed or +-- upgraded. We care about the case where a package is initially +-- installed, because other cases are covered by the *un scriptlets, +-- so sometimes we will reload needlessly. + +pid = posix.fork() +if pid == 0 then + assert(posix.exec("%{_bindir}/systemctl", "daemon-reload")) +elseif pid > 0 then + posix.wait(pid) +end + +%transfiletriggerun -p <lua> -- @systemunitdir@ /etc/systemd/system +-- On removal, we need to run daemon-reload after any units have been +-- removed. %transfiletriggerpostun would be ideal, but it does not get +-- executed for some reason. +-- On upgrade, we need to run daemon-reload after any new unit files +-- have been installed, but before %postun scripts in packages get +-- executed. %transfiletriggerun gets the right list of files +-- but it is invoked too early (before changes happen). +-- %filetriggerpostun happens at the right time, but it fires for +-- every package. +-- To execute the reload at the right time, we create a state +-- file in %transfiletriggerun and execute the daemon-reload in +-- the first %filetriggerpostun. + +posix.mkdir("%{_localstatedir}/lib") +posix.mkdir("%{_localstatedir}/lib/rpm-state") +posix.mkdir("%{_localstatedir}/lib/rpm-state/systemd") +io.open("%{_localstatedir}/lib/rpm-state/systemd/needs-reload", "w") + +%filetriggerpostun -P 1000100 -p <lua> -- @systemunitdir@ /etc/systemd/system +if posix.access("%{_localstatedir}/lib/rpm-state/systemd/needs-reload") then + posix.unlink("%{_localstatedir}/lib/rpm-state/systemd/needs-reload") + posix.rmdir("%{_localstatedir}/lib/rpm-state/systemd") + pid = posix.fork() + if pid == 0 then + assert(posix.exec("%{_bindir}/systemctl", "daemon-reload")) + elseif pid > 0 then + posix.wait(pid) + end +end diff --git a/src/grp-system/systemd/user.conf b/src/grp-system/systemd/user.conf new file mode 100644 index 0000000000..b427f1ef6d --- /dev/null +++ b/src/grp-system/systemd/user.conf @@ -0,0 +1,44 @@ +# This file is part of systemd. +# +# systemd is free software; you can redistribute it and/or modify it +# under the terms of the GNU Lesser General Public License as published by +# the Free Software Foundation; either version 2.1 of the License, or +# (at your option) any later version. +# +# You can override the directives in this file by creating files in +# /etc/systemd/user.conf.d/*.conf. +# +# See systemd-user.conf(5) for details + +[Manager] +#LogLevel=info +#LogTarget=console +#LogColor=yes +#LogLocation=no +#SystemCallArchitectures= +#TimerSlackNSec= +#DefaultTimerAccuracySec=1min +#DefaultStandardOutput=inherit +#DefaultStandardError=inherit +#DefaultTimeoutStartSec=90s +#DefaultTimeoutStopSec=90s +#DefaultRestartSec=100ms +#DefaultStartLimitIntervalSec=10s +#DefaultStartLimitBurst=5 +#DefaultEnvironment= +#DefaultLimitCPU= +#DefaultLimitFSIZE= +#DefaultLimitDATA= +#DefaultLimitSTACK= +#DefaultLimitCORE= +#DefaultLimitRSS= +#DefaultLimitNOFILE= +#DefaultLimitAS= +#DefaultLimitNPROC= +#DefaultLimitMEMLOCK= +#DefaultLimitLOCKS= +#DefaultLimitSIGPENDING= +#DefaultLimitMSGQUEUE= +#DefaultLimitNICE= +#DefaultLimitRTPRIO= +#DefaultLimitRTTIME= |