From 4160043a0fac8b812905b7502ce34adf3af538f1 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Tue, 6 Sep 2016 02:27:18 -0400 Subject: move man pages to appropriate directories --- src/busctl/busctl.xml | 480 +++++ src/grp-boot/bootctl/bootctl.xml | 128 ++ src/grp-coredump/coredump.conf.xml | 161 ++ src/grp-coredump/coredumpctl/coredumpctl.xml | 259 +++ .../systemd-coredump/systemd-coredump.xml | 145 ++ src/grp-hostname/hostnamectl/hostnamectl.xml | 260 +++ .../systemd-hostnamed.service.xml | 85 + .../systemd-hibernate-resume-generator.xml | 93 + .../systemd-hibernate-resume@.service.xml | 81 + .../grp-sleep/systemd-sleep/systemd-sleep.conf.xml | 186 ++ .../systemd-sleep/systemd-suspend.service.xml | 146 ++ .../systemd-backlight@.service.xml | 94 + src/grp-initprogs/systemd-binfmt/binfmt.d.xml | 101 ++ .../systemd-binfmt/systemd-binfmt.service.xml | 75 + .../systemd-detect-virt/systemd-detect-virt.xml | 245 +++ .../systemd-firstboot/systemd-firstboot.xml | 259 +++ .../systemd-fsck/systemd-fsck@.service.xml | 139 ++ .../systemd-modules-load/modules-load.d.xml | 101 ++ .../systemd-modules-load.service.xml | 96 + .../systemd-quotacheck.service.xml | 94 + .../systemd-random-seed.service.xml | 75 + .../systemd-rfkill/systemd-rfkill.service.xml | 90 + src/grp-initprogs/systemd-sysctl/sysctl.d.xml | 184 ++ .../systemd-sysctl/systemd-sysctl.service.xml | 152 ++ .../systemd-sysusers/systemd-sysusers.xml | 116 ++ src/grp-initprogs/systemd-sysusers/sysusers.d.xml | 223 +++ .../systemd-tmpfiles/systemd-tmpfiles.xml | 200 +++ src/grp-initprogs/systemd-tmpfiles/tmpfiles.d.xml | 703 ++++++++ .../systemd-update-done.service.xml | 97 ++ .../systemd-update-utmp.service.xml | 76 + .../systemd-user-sessions.service.xml | 75 + .../systemd-vconsole-setup.service.xml | 114 ++ .../systemd-vconsole-setup/vconsole.conf.xml | 139 ++ .../systemd-journal-gatewayd.service.xml | 302 ++++ .../systemd-journal-remote/journal-remote.conf.xml | 121 ++ .../systemd-journal-remote.xml | 325 ++++ .../systemd-journal-upload.xml | 263 +++ src/grp-journal/journalctl/journalctl.xml | 914 ++++++++++ src/grp-journal/systemd-cat/systemd-cat.xml | 178 ++ src/grp-journal/systemd-journald/journald.conf.xml | 410 +++++ .../systemd-journald/systemd-journald.service.xml | 276 +++ src/grp-locale/locale.conf.xml | 152 ++ src/grp-locale/localectl/localectl.xml | 221 +++ .../systemd-localed/systemd-localed.service.xml | 87 + src/grp-login/loginctl/loginctl.xml | 459 +++++ src/grp-login/pam_systemd/pam_systemd.xml | 296 ++++ src/grp-login/systemd-inhibit/systemd-inhibit.xml | 177 ++ src/grp-login/systemd-logind/logind.conf.xml | 349 ++++ .../systemd-logind/systemd-logind.service.xml | 121 ++ .../systemd-importd/systemd-importd.service.xml | 82 + src/grp-machine/machinectl/machinectl.xml | 1022 +++++++++++ src/grp-machine/nss-mymachines/nss-mymachines.xml | 113 ++ .../systemd-machined/systemd-machined.service.xml | 90 + src/grp-network/networkctl/networkctl.xml | 193 ++ .../systemd-networkd-wait-online.service.xml | 110 ++ src/grp-network/systemd-networkd/networkd.conf.xml | 154 ++ .../systemd-networkd/systemd-networkd.service.xml | 103 ++ src/grp-resolve/nss-resolve/nss-resolve.xml | 111 ++ .../systemd-resolve/systemd-resolve.xml | 375 ++++ .../systemd-resolved/dnssec-trust-anchors.d.xml | 200 +++ src/grp-resolve/systemd-resolved/resolved.conf.xml | 219 +++ .../systemd-resolved/systemd-resolved.service.xml | 163 ++ src/grp-system/bootup.xml | 305 ++++ .../grp-utils/systemd-analyze/systemd-analyze.xml | 388 +++++ .../grp-utils/systemd-delta/systemd-delta.xml | 205 +++ .../systemd-fstab-generator.xml | 183 ++ .../grp-utils/systemd-run/systemd-run.xml | 459 +++++ .../systemd-sysv-generator.xml | 97 ++ src/grp-system/kernel-command-line.xml | 382 ++++ src/grp-system/systemctl/halt.xml | 176 ++ src/grp-system/systemctl/runlevel.xml | 192 ++ src/grp-system/systemctl/shutdown.xml | 175 ++ src/grp-system/systemctl/systemctl.xml | 1838 ++++++++++++++++++++ src/grp-system/systemctl/systemd-halt.service.xml | 118 ++ src/grp-system/systemctl/telinit.xml | 179 ++ src/grp-system/systemd/systemd-system.conf.xml | 394 +++++ src/grp-system/systemd/systemd.automount.xml | 173 ++ src/grp-system/systemd/systemd.device.xml | 182 ++ src/grp-system/systemd/systemd.exec.xml | 1475 ++++++++++++++++ src/grp-system/systemd/systemd.generator.xml | 348 ++++ src/grp-system/systemd/systemd.journal-fields.xml | 525 ++++++ src/grp-system/systemd/systemd.kill.xml | 189 ++ src/grp-system/systemd/systemd.link.xml | 477 +++++ src/grp-system/systemd/systemd.mount.xml | 406 +++++ src/grp-system/systemd/systemd.netdev.xml | 1116 ++++++++++++ src/grp-system/systemd/systemd.network.xml | 1205 +++++++++++++ src/grp-system/systemd/systemd.nspawn.xml | 454 +++++ src/grp-system/systemd/systemd.offline-updates.xml | 169 ++ src/grp-system/systemd/systemd.path.xml | 202 +++ src/grp-system/systemd/systemd.preset.xml | 189 ++ .../systemd/systemd.resource-control.xml | 628 +++++++ src/grp-system/systemd/systemd.scope.xml | 108 ++ src/grp-system/systemd/systemd.service.xml | 1352 ++++++++++++++ src/grp-system/systemd/systemd.slice.xml | 132 ++ src/grp-system/systemd/systemd.socket.xml | 860 +++++++++ src/grp-system/systemd/systemd.special.xml | 935 ++++++++++ src/grp-system/systemd/systemd.swap.xml | 250 +++ src/grp-system/systemd/systemd.target.xml | 103 ++ src/grp-system/systemd/systemd.time.xml | 313 ++++ src/grp-system/systemd/systemd.timer.xml | 313 ++++ src/grp-system/systemd/systemd.unit.xml | 1484 ++++++++++++++++ src/grp-system/systemd/systemd.xml | 1153 ++++++++++++ .../systemd-timedated.service.xml | 85 + src/grp-timedate/timedatectl/timedatectl.xml | 253 +++ src/grp-udev/hwdb/hwdb.xml | 85 + src/grp-udev/systemd-hwdb/systemd-hwdb.xml | 93 + .../systemd-udevd/systemd-udevd.service.xml | 188 ++ src/grp-udev/udev.conf.xml | 94 + src/grp-udev/udev.xml | 755 ++++++++ src/grp-udev/udevadm/udevadm.xml | 576 ++++++ src/grp-utils/systemd-escape/systemd-escape.xml | 178 ++ src/grp-utils/systemd-notify/systemd-notify.xml | 185 ++ src/grp-utils/systemd-path/systemd-path.xml | 107 ++ .../systemd-socket-activate.xml | 206 +++ src/libsystemd/sd-bus-errors.xml | 309 ++++ src/libsystemd/sd_booted.xml | 95 + src/libsystemd/sd_bus_creds_get_pid.xml | 566 ++++++ src/libsystemd/sd_bus_creds_new_from_pid.xml | 353 ++++ src/libsystemd/sd_bus_default.xml | 312 ++++ src/libsystemd/sd_bus_error.xml | 389 +++++ src/libsystemd/sd_bus_error_add_map.xml | 173 ++ src/libsystemd/sd_bus_message_append.xml | 264 +++ src/libsystemd/sd_bus_message_append_array.xml | 213 +++ src/libsystemd/sd_bus_message_append_basic.xml | 295 ++++ .../sd_bus_message_append_string_memfd.xml | 153 ++ src/libsystemd/sd_bus_message_append_strv.xml | 116 ++ src/libsystemd/sd_bus_message_get_cookie.xml | 146 ++ .../sd_bus_message_get_monotonic_usec.xml | 181 ++ src/libsystemd/sd_bus_negotiate_fds.xml | 200 +++ src/libsystemd/sd_bus_new.xml | 189 ++ src/libsystemd/sd_bus_path_encode.xml | 188 ++ src/libsystemd/sd_bus_request_name.xml | 213 +++ src/libsystemd/sd_event_add_child.xml | 246 +++ src/libsystemd/sd_event_add_defer.xml | 216 +++ src/libsystemd/sd_event_add_io.xml | 300 ++++ src/libsystemd/sd_event_add_signal.xml | 221 +++ src/libsystemd/sd_event_add_time.xml | 313 ++++ src/libsystemd/sd_event_exit.xml | 163 ++ src/libsystemd/sd_event_get_fd-glib-example.c | 68 + src/libsystemd/sd_event_get_fd.xml | 140 ++ src/libsystemd/sd_event_new.xml | 245 +++ src/libsystemd/sd_event_now.xml | 146 ++ src/libsystemd/sd_event_run.xml | 190 ++ src/libsystemd/sd_event_set_watchdog.xml | 177 ++ src/libsystemd/sd_event_source_get_event.xml | 100 ++ src/libsystemd/sd_event_source_get_pending.xml | 167 ++ src/libsystemd/sd_event_source_set_description.xml | 170 ++ src/libsystemd/sd_event_source_set_enabled.xml | 179 ++ src/libsystemd/sd_event_source_set_prepare.xml | 171 ++ src/libsystemd/sd_event_source_set_priority.xml | 189 ++ src/libsystemd/sd_event_source_set_userdata.xml | 119 ++ src/libsystemd/sd_event_source_unref.xml | 142 ++ src/libsystemd/sd_event_wait.xml | 346 ++++ src/libsystemd/sd_get_seats.xml | 164 ++ src/libsystemd/sd_id128_get_machine.xml | 129 ++ src/libsystemd/sd_id128_randomize.xml | 114 ++ src/libsystemd/sd_id128_to_string.xml | 132 ++ src/libsystemd/sd_is_fifo.xml | 200 +++ src/libsystemd/sd_journal_add_match.xml | 216 +++ src/libsystemd/sd_journal_enumerate_fields.xml | 161 ++ src/libsystemd/sd_journal_get_catalog.xml | 137 ++ src/libsystemd/sd_journal_get_cursor.xml | 144 ++ .../sd_journal_get_cutoff_realtime_usec.xml | 145 ++ src/libsystemd/sd_journal_get_data.xml | 235 +++ src/libsystemd/sd_journal_get_fd.xml | 332 ++++ src/libsystemd/sd_journal_get_realtime_usec.xml | 141 ++ src/libsystemd/sd_journal_get_usage.xml | 100 ++ src/libsystemd/sd_journal_has_runtime_files.xml | 95 + src/libsystemd/sd_journal_next.xml | 207 +++ src/libsystemd/sd_journal_open.xml | 228 +++ src/libsystemd/sd_journal_print.xml | 260 +++ src/libsystemd/sd_journal_query_unique.xml | 212 +++ src/libsystemd/sd_journal_seek_head.xml | 172 ++ src/libsystemd/sd_journal_stream_fd.xml | 163 ++ src/libsystemd/sd_listen_fds.xml | 257 +++ src/libsystemd/sd_login_monitor_new.xml | 287 +++ src/libsystemd/sd_machine_get_class.xml | 152 ++ src/libsystemd/sd_notify.xml | 399 +++++ src/libsystemd/sd_pid_get_session.xml | 359 ++++ src/libsystemd/sd_seat_get_active.xml | 212 +++ src/libsystemd/sd_session_is_active.xml | 359 ++++ src/libsystemd/sd_uid_get_state.xml | 230 +++ src/libsystemd/sd_watchdog_enabled.xml | 169 ++ src/libsystemd/src/sd-bus/sd-bus.xml | 123 ++ src/libsystemd/src/sd-daemon/sd-daemon.xml | 144 ++ src/libsystemd/src/sd-event/sd-event.xml | 187 ++ src/libsystemd/src/sd-id128/sd-id128.xml | 166 ++ src/libsystemd/src/sd-journal/sd-journal.xml | 133 ++ src/libsystemd/src/sd-login/sd-login.xml | 135 ++ src/libudev/libudev.xml | 125 ++ src/libudev/udev_device_get_syspath.xml | 207 +++ src/libudev/udev_device_has_tag.xml | 163 ++ src/libudev/udev_device_new_from_syspath.xml | 214 +++ src/libudev/udev_enumerate_add_match_subsystem.xml | 163 ++ src/libudev/udev_enumerate_new.xml | 111 ++ src/libudev/udev_enumerate_scan_devices.xml | 133 ++ src/libudev/udev_list_entry.xml | 123 ++ src/libudev/udev_monitor_filter_update.xml | 122 ++ src/libudev/udev_monitor_new_from_netlink.xml | 113 ++ src/libudev/udev_monitor_receive_device.xml | 137 ++ src/libudev/udev_new.xml | 110 ++ src/nss-myhostname/nss-myhostname.xml | 148 ++ src/systemd-ask-password/systemd-ask-password.xml | 227 +++ src/systemd-cgls/systemd-cgls.xml | 139 ++ src/systemd-cgtop/systemd-cgtop.xml | 373 ++++ src/systemd-cryptsetup/crypttab.xml | 416 +++++ .../systemd-cryptsetup-generator.xml | 193 ++ .../systemd-cryptsetup@.service.xml | 85 + .../systemd-debug-generator.xml | 95 + .../systemd-getty-generator.xml | 96 + .../systemd-gpt-auto-generator.xml | 186 ++ src/systemd-initctl/systemd-initctl.service.xml | 76 + .../systemd-machine-id-commit.service.xml | 95 + .../systemd-machine-id-setup.xml | 178 ++ src/systemd-nspawn/systemd-nspawn.xml | 1066 ++++++++++++ .../systemd-remount-fs.service.xml | 88 + .../systemd-socket-proxyd.xml | 190 ++ .../systemd-system-update-generator.xml | 76 + .../systemd-timesyncd.service.xml | 108 ++ src/systemd-timesyncd/timesyncd.conf.xml | 112 ++ .../systemd-ask-password-console.service.xml | 93 + .../systemd-tty-ask-password-agent.xml | 149 ++ 222 files changed, 56967 insertions(+) create mode 100644 src/busctl/busctl.xml create mode 100644 src/grp-boot/bootctl/bootctl.xml create mode 100644 src/grp-coredump/coredump.conf.xml create mode 100644 src/grp-coredump/coredumpctl/coredumpctl.xml create mode 100644 src/grp-coredump/systemd-coredump/systemd-coredump.xml create mode 100644 src/grp-hostname/hostnamectl/hostnamectl.xml create mode 100644 src/grp-hostname/systemd-hostnamed/systemd-hostnamed.service.xml create mode 100644 src/grp-initprogs/grp-sleep/systemd-hibernate-resume-generator/systemd-hibernate-resume-generator.xml create mode 100644 src/grp-initprogs/grp-sleep/systemd-hibernate-resume/systemd-hibernate-resume@.service.xml create mode 100644 src/grp-initprogs/grp-sleep/systemd-sleep/systemd-sleep.conf.xml create mode 100644 src/grp-initprogs/grp-sleep/systemd-sleep/systemd-suspend.service.xml create mode 100644 src/grp-initprogs/systemd-backlight/systemd-backlight@.service.xml create mode 100644 src/grp-initprogs/systemd-binfmt/binfmt.d.xml create mode 100644 src/grp-initprogs/systemd-binfmt/systemd-binfmt.service.xml create mode 100644 src/grp-initprogs/systemd-detect-virt/systemd-detect-virt.xml create mode 100644 src/grp-initprogs/systemd-firstboot/systemd-firstboot.xml create mode 100644 src/grp-initprogs/systemd-fsck/systemd-fsck@.service.xml create mode 100644 src/grp-initprogs/systemd-modules-load/modules-load.d.xml create mode 100644 src/grp-initprogs/systemd-modules-load/systemd-modules-load.service.xml create mode 100644 src/grp-initprogs/systemd-quotacheck/systemd-quotacheck.service.xml create mode 100644 src/grp-initprogs/systemd-random-seed/systemd-random-seed.service.xml create mode 100644 src/grp-initprogs/systemd-rfkill/systemd-rfkill.service.xml create mode 100644 src/grp-initprogs/systemd-sysctl/sysctl.d.xml create mode 100644 src/grp-initprogs/systemd-sysctl/systemd-sysctl.service.xml create mode 100644 src/grp-initprogs/systemd-sysusers/systemd-sysusers.xml create mode 100644 src/grp-initprogs/systemd-sysusers/sysusers.d.xml create mode 100644 src/grp-initprogs/systemd-tmpfiles/systemd-tmpfiles.xml create mode 100644 src/grp-initprogs/systemd-tmpfiles/tmpfiles.d.xml create mode 100644 src/grp-initprogs/systemd-update-done/systemd-update-done.service.xml create mode 100644 src/grp-initprogs/systemd-update-utmp/systemd-update-utmp.service.xml create mode 100644 src/grp-initprogs/systemd-user-sessions/systemd-user-sessions.service.xml create mode 100644 src/grp-initprogs/systemd-vconsole-setup/systemd-vconsole-setup.service.xml create mode 100644 src/grp-initprogs/systemd-vconsole-setup/vconsole.conf.xml create mode 100644 src/grp-journal/grp-remote/systemd-journal-gatewayd/systemd-journal-gatewayd.service.xml create mode 100644 src/grp-journal/grp-remote/systemd-journal-remote/journal-remote.conf.xml create mode 100644 src/grp-journal/grp-remote/systemd-journal-remote/systemd-journal-remote.xml create mode 100644 src/grp-journal/grp-remote/systemd-journal-upload/systemd-journal-upload.xml create mode 100644 src/grp-journal/journalctl/journalctl.xml create mode 100644 src/grp-journal/systemd-cat/systemd-cat.xml create mode 100644 src/grp-journal/systemd-journald/journald.conf.xml create mode 100644 src/grp-journal/systemd-journald/systemd-journald.service.xml create mode 100644 src/grp-locale/locale.conf.xml create mode 100644 src/grp-locale/localectl/localectl.xml create mode 100644 src/grp-locale/systemd-localed/systemd-localed.service.xml create mode 100644 src/grp-login/loginctl/loginctl.xml create mode 100644 src/grp-login/pam_systemd/pam_systemd.xml create mode 100644 src/grp-login/systemd-inhibit/systemd-inhibit.xml create mode 100644 src/grp-login/systemd-logind/logind.conf.xml create mode 100644 src/grp-login/systemd-logind/systemd-logind.service.xml create mode 100644 src/grp-machine/grp-import/systemd-importd/systemd-importd.service.xml create mode 100644 src/grp-machine/machinectl/machinectl.xml create mode 100644 src/grp-machine/nss-mymachines/nss-mymachines.xml create mode 100644 src/grp-machine/systemd-machined/systemd-machined.service.xml create mode 100644 src/grp-network/networkctl/networkctl.xml create mode 100644 src/grp-network/systemd-networkd-wait-online/systemd-networkd-wait-online.service.xml create mode 100644 src/grp-network/systemd-networkd/networkd.conf.xml create mode 100644 src/grp-network/systemd-networkd/systemd-networkd.service.xml create mode 100644 src/grp-resolve/nss-resolve/nss-resolve.xml create mode 100644 src/grp-resolve/systemd-resolve/systemd-resolve.xml create mode 100644 src/grp-resolve/systemd-resolved/dnssec-trust-anchors.d.xml create mode 100644 src/grp-resolve/systemd-resolved/resolved.conf.xml create mode 100644 src/grp-resolve/systemd-resolved/systemd-resolved.service.xml create mode 100644 src/grp-system/bootup.xml create mode 100644 src/grp-system/grp-utils/systemd-analyze/systemd-analyze.xml create mode 100644 src/grp-system/grp-utils/systemd-delta/systemd-delta.xml create mode 100644 src/grp-system/grp-utils/systemd-fstab-generator/systemd-fstab-generator.xml create mode 100644 src/grp-system/grp-utils/systemd-run/systemd-run.xml create mode 100644 src/grp-system/grp-utils/systemd-sysv-generator/systemd-sysv-generator.xml create mode 100644 src/grp-system/kernel-command-line.xml create mode 100644 src/grp-system/systemctl/halt.xml create mode 100644 src/grp-system/systemctl/runlevel.xml create mode 100644 src/grp-system/systemctl/shutdown.xml create mode 100644 src/grp-system/systemctl/systemctl.xml create mode 100644 src/grp-system/systemctl/systemd-halt.service.xml create mode 100644 src/grp-system/systemctl/telinit.xml create mode 100644 src/grp-system/systemd/systemd-system.conf.xml create mode 100644 src/grp-system/systemd/systemd.automount.xml create mode 100644 src/grp-system/systemd/systemd.device.xml create mode 100644 src/grp-system/systemd/systemd.exec.xml create mode 100644 src/grp-system/systemd/systemd.generator.xml create mode 100644 src/grp-system/systemd/systemd.journal-fields.xml create mode 100644 src/grp-system/systemd/systemd.kill.xml create mode 100644 src/grp-system/systemd/systemd.link.xml create mode 100644 src/grp-system/systemd/systemd.mount.xml create mode 100644 src/grp-system/systemd/systemd.netdev.xml create mode 100644 src/grp-system/systemd/systemd.network.xml create mode 100644 src/grp-system/systemd/systemd.nspawn.xml create mode 100644 src/grp-system/systemd/systemd.offline-updates.xml create mode 100644 src/grp-system/systemd/systemd.path.xml create mode 100644 src/grp-system/systemd/systemd.preset.xml create mode 100644 src/grp-system/systemd/systemd.resource-control.xml create mode 100644 src/grp-system/systemd/systemd.scope.xml create mode 100644 src/grp-system/systemd/systemd.service.xml create mode 100644 src/grp-system/systemd/systemd.slice.xml create mode 100644 src/grp-system/systemd/systemd.socket.xml create mode 100644 src/grp-system/systemd/systemd.special.xml create mode 100644 src/grp-system/systemd/systemd.swap.xml create mode 100644 src/grp-system/systemd/systemd.target.xml create mode 100644 src/grp-system/systemd/systemd.time.xml create mode 100644 src/grp-system/systemd/systemd.timer.xml create mode 100644 src/grp-system/systemd/systemd.unit.xml create mode 100644 src/grp-system/systemd/systemd.xml create mode 100644 src/grp-timedate/systemd-timedated/systemd-timedated.service.xml create mode 100644 src/grp-timedate/timedatectl/timedatectl.xml create mode 100644 src/grp-udev/hwdb/hwdb.xml create mode 100644 src/grp-udev/systemd-hwdb/systemd-hwdb.xml create mode 100644 src/grp-udev/systemd-udevd/systemd-udevd.service.xml create mode 100644 src/grp-udev/udev.conf.xml create mode 100644 src/grp-udev/udev.xml create mode 100644 src/grp-udev/udevadm/udevadm.xml create mode 100644 src/grp-utils/systemd-escape/systemd-escape.xml create mode 100644 src/grp-utils/systemd-notify/systemd-notify.xml create mode 100644 src/grp-utils/systemd-path/systemd-path.xml create mode 100644 src/grp-utils/systemd-socket-activate/systemd-socket-activate.xml create mode 100644 src/libsystemd/sd-bus-errors.xml create mode 100644 src/libsystemd/sd_booted.xml create mode 100644 src/libsystemd/sd_bus_creds_get_pid.xml create mode 100644 src/libsystemd/sd_bus_creds_new_from_pid.xml create mode 100644 src/libsystemd/sd_bus_default.xml create mode 100644 src/libsystemd/sd_bus_error.xml create mode 100644 src/libsystemd/sd_bus_error_add_map.xml create mode 100644 src/libsystemd/sd_bus_message_append.xml create mode 100644 src/libsystemd/sd_bus_message_append_array.xml create mode 100644 src/libsystemd/sd_bus_message_append_basic.xml create mode 100644 src/libsystemd/sd_bus_message_append_string_memfd.xml create mode 100644 src/libsystemd/sd_bus_message_append_strv.xml create mode 100644 src/libsystemd/sd_bus_message_get_cookie.xml create mode 100644 src/libsystemd/sd_bus_message_get_monotonic_usec.xml create mode 100644 src/libsystemd/sd_bus_negotiate_fds.xml create mode 100644 src/libsystemd/sd_bus_new.xml create mode 100644 src/libsystemd/sd_bus_path_encode.xml create mode 100644 src/libsystemd/sd_bus_request_name.xml create mode 100644 src/libsystemd/sd_event_add_child.xml create mode 100644 src/libsystemd/sd_event_add_defer.xml create mode 100644 src/libsystemd/sd_event_add_io.xml create mode 100644 src/libsystemd/sd_event_add_signal.xml create mode 100644 src/libsystemd/sd_event_add_time.xml create mode 100644 src/libsystemd/sd_event_exit.xml create mode 100644 src/libsystemd/sd_event_get_fd-glib-example.c create mode 100644 src/libsystemd/sd_event_get_fd.xml create mode 100644 src/libsystemd/sd_event_new.xml create mode 100644 src/libsystemd/sd_event_now.xml create mode 100644 src/libsystemd/sd_event_run.xml create mode 100644 src/libsystemd/sd_event_set_watchdog.xml create mode 100644 src/libsystemd/sd_event_source_get_event.xml create mode 100644 src/libsystemd/sd_event_source_get_pending.xml create mode 100644 src/libsystemd/sd_event_source_set_description.xml create mode 100644 src/libsystemd/sd_event_source_set_enabled.xml create mode 100644 src/libsystemd/sd_event_source_set_prepare.xml create mode 100644 src/libsystemd/sd_event_source_set_priority.xml create mode 100644 src/libsystemd/sd_event_source_set_userdata.xml create mode 100644 src/libsystemd/sd_event_source_unref.xml create mode 100644 src/libsystemd/sd_event_wait.xml create mode 100644 src/libsystemd/sd_get_seats.xml create mode 100644 src/libsystemd/sd_id128_get_machine.xml create mode 100644 src/libsystemd/sd_id128_randomize.xml create mode 100644 src/libsystemd/sd_id128_to_string.xml create mode 100644 src/libsystemd/sd_is_fifo.xml create mode 100644 src/libsystemd/sd_journal_add_match.xml create mode 100644 src/libsystemd/sd_journal_enumerate_fields.xml create mode 100644 src/libsystemd/sd_journal_get_catalog.xml create mode 100644 src/libsystemd/sd_journal_get_cursor.xml create mode 100644 src/libsystemd/sd_journal_get_cutoff_realtime_usec.xml create mode 100644 src/libsystemd/sd_journal_get_data.xml create mode 100644 src/libsystemd/sd_journal_get_fd.xml create mode 100644 src/libsystemd/sd_journal_get_realtime_usec.xml create mode 100644 src/libsystemd/sd_journal_get_usage.xml create mode 100644 src/libsystemd/sd_journal_has_runtime_files.xml create mode 100644 src/libsystemd/sd_journal_next.xml create mode 100644 src/libsystemd/sd_journal_open.xml create mode 100644 src/libsystemd/sd_journal_print.xml create mode 100644 src/libsystemd/sd_journal_query_unique.xml create mode 100644 src/libsystemd/sd_journal_seek_head.xml create mode 100644 src/libsystemd/sd_journal_stream_fd.xml create mode 100644 src/libsystemd/sd_listen_fds.xml create mode 100644 src/libsystemd/sd_login_monitor_new.xml create mode 100644 src/libsystemd/sd_machine_get_class.xml create mode 100644 src/libsystemd/sd_notify.xml create mode 100644 src/libsystemd/sd_pid_get_session.xml create mode 100644 src/libsystemd/sd_seat_get_active.xml create mode 100644 src/libsystemd/sd_session_is_active.xml create mode 100644 src/libsystemd/sd_uid_get_state.xml create mode 100644 src/libsystemd/sd_watchdog_enabled.xml create mode 100644 src/libsystemd/src/sd-bus/sd-bus.xml create mode 100644 src/libsystemd/src/sd-daemon/sd-daemon.xml create mode 100644 src/libsystemd/src/sd-event/sd-event.xml create mode 100644 src/libsystemd/src/sd-id128/sd-id128.xml create mode 100644 src/libsystemd/src/sd-journal/sd-journal.xml create mode 100644 src/libsystemd/src/sd-login/sd-login.xml create mode 100644 src/libudev/libudev.xml create mode 100644 src/libudev/udev_device_get_syspath.xml create mode 100644 src/libudev/udev_device_has_tag.xml create mode 100644 src/libudev/udev_device_new_from_syspath.xml create mode 100644 src/libudev/udev_enumerate_add_match_subsystem.xml create mode 100644 src/libudev/udev_enumerate_new.xml create mode 100644 src/libudev/udev_enumerate_scan_devices.xml create mode 100644 src/libudev/udev_list_entry.xml create mode 100644 src/libudev/udev_monitor_filter_update.xml create mode 100644 src/libudev/udev_monitor_new_from_netlink.xml create mode 100644 src/libudev/udev_monitor_receive_device.xml create mode 100644 src/libudev/udev_new.xml create mode 100644 src/nss-myhostname/nss-myhostname.xml create mode 100644 src/systemd-ask-password/systemd-ask-password.xml create mode 100644 src/systemd-cgls/systemd-cgls.xml create mode 100644 src/systemd-cgtop/systemd-cgtop.xml create mode 100644 src/systemd-cryptsetup/crypttab.xml create mode 100644 src/systemd-cryptsetup/systemd-cryptsetup-generator.xml create mode 100644 src/systemd-cryptsetup/systemd-cryptsetup@.service.xml create mode 100644 src/systemd-debug-generator/systemd-debug-generator.xml create mode 100644 src/systemd-getty-generator/systemd-getty-generator.xml create mode 100644 src/systemd-gpt-auto-generator/systemd-gpt-auto-generator.xml create mode 100644 src/systemd-initctl/systemd-initctl.service.xml create mode 100644 src/systemd-machine-id-setup/systemd-machine-id-commit.service.xml create mode 100644 src/systemd-machine-id-setup/systemd-machine-id-setup.xml create mode 100644 src/systemd-nspawn/systemd-nspawn.xml create mode 100644 src/systemd-remount-fs/systemd-remount-fs.service.xml create mode 100644 src/systemd-socket-proxyd/systemd-socket-proxyd.xml create mode 100644 src/systemd-system-update-generator/systemd-system-update-generator.xml create mode 100644 src/systemd-timesyncd/systemd-timesyncd.service.xml create mode 100644 src/systemd-timesyncd/timesyncd.conf.xml create mode 100644 src/systemd-tty-ask-password-agent/systemd-ask-password-console.service.xml create mode 100644 src/systemd-tty-ask-password-agent/systemd-tty-ask-password-agent.xml (limited to 'src') diff --git a/src/busctl/busctl.xml b/src/busctl/busctl.xml new file mode 100644 index 0000000000..b71a174634 --- /dev/null +++ b/src/busctl/busctl.xml @@ -0,0 +1,480 @@ + + + + + + + + + busctl + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + busctl + 1 + + + + busctl + Introspect the bus + + + + + busctl + OPTIONS + COMMAND + NAME + + + + + Description + + busctl may be used to + introspect and monitor the D-Bus bus. + + + + Options + + The following options are understood: + + + + + + Connect to the bus specified by + ADDRESS instead of using suitable + defaults for either the system or user bus (see + and + options). + + + + + + When showing the list of peers, show a + column containing the names of containers they belong to. + See + systemd-machined.service8. + + + + + + + When showing the list of peers, show only + "unique" names (of the form + :number.number). + + + + + + + The opposite of — + only "well-known" names will be shown. + + + + + + When showing the list of peers, show only + peers which have actually not been activated yet, but may be + started automatically if accessed. + + + + + + + When showing messages being exchanged, show only the + subset matching MATCH. + + + + + + + + When used with the capture command, + specifies the maximum bus message size to capture + ("snaplen"). Defaults to 4096 bytes. + + + + + + + + When used with the tree command, shows a + flat list of object paths instead of a tree. + + + + + + + + When used with the call command, + suppresses display of the response message payload. Note that even + if this option is specified, errors returned will still be + printed and the tool will indicate success or failure with + the process exit code. + + + + + + + + When used with the call or + get-property command, shows output in a + more verbose format. + + + + + BOOL + + + When used with the call command, + specifies whether busctl shall wait for + completion of the method call, output the returned method + response data, and return success or failure via the process + exit code. If this is set to no, the + method call will be issued but no response is expected, the + tool terminates immediately, and thus no response can be + shown, and no success or failure is returned via the exit + code. To only suppress output of the reply message payload, + use above. Defaults to + yes. + + + + + BOOL + + + When used with the call command, specifies + whether the method call should implicitly activate the + called service, should it not be running yet but is + configured to be auto-started. Defaults to + yes. + + + + + BOOL + + + When used with the call command, + specifies whether the services may enforce interactive + authorization while executing the operation, if the security + policy is configured for this. Defaults to + yes. + + + + + SECS + + + When used with the call command, + specifies the maximum time to wait for method call + completion. If no time unit is specified, assumes + seconds. The usual other units are understood, too (ms, us, + s, min, h, d, w, month, y). Note that this timeout does not + apply if is used, as the + tool does not wait for any reply message then. When not + specified or when set to 0, the default of + 25s is assumed. + + + + + BOOL + + + Controls whether credential data reported by + list or status shall + be augmented with data from + /proc. When this is turned on, the data + shown is possibly inconsistent, as the data read from + /proc might be more recent than the rest of + the credential information. Defaults to yes. + + + + + + + + + + + + + + + + + Commands + + The following commands are understood: + + + + list + + Show all peers on the bus, by their service + names. By default, shows both unique and well-known names, but + this may be changed with the and + switches. This is the default + operation if no command is specified. + + + + status SERVICE + + Show process information and credentials of a + bus service (if one is specified by its unique or well-known + name), a process (if one is specified by its numeric PID), or + the owner of the bus (if no parameter is + specified). + + + + monitor SERVICE + + Dump messages being exchanged. If + SERVICE is specified, show messages + to or from this peer, identified by its well-known or unique + name. Otherwise, show all messages on the bus. Use Ctrl-C to + terminate the dump. + + + + capture SERVICE + + Similar to monitor but + writes the output in pcap format (for details, see the Libpcap + File Format description. Make sure to redirect the + output to STDOUT to a file. Tools like + wireshark1 + may be used to dissect and view the generated + files. + + + + tree SERVICE + + Shows an object tree of one or more + services. If SERVICE is specified, + show object tree of the specified services only. Otherwise, + show all object trees of all services on the bus that acquired + at least one well-known name. + + + + introspect SERVICE OBJECT INTERFACE + + Show interfaces, methods, properties and + signals of the specified object (identified by its path) on + the specified service. If the interface argument is passed, the + output is limited to members of the specified + interface. + + + + call SERVICE OBJECT INTERFACE METHOD SIGNATURE ARGUMENT + + Invoke a method and show the response. Takes a + service name, object path, interface name and method name. If + parameters shall be passed to the method call, a signature + string is required, followed by the arguments, individually + formatted as strings. For details on the formatting used, see + below. To suppress output of the returned data, use the + option. + + + + get-property SERVICE OBJECT INTERFACE PROPERTY + + Retrieve the current value of one or more + object properties. Takes a service name, object path, + interface name and property name. Multiple properties may be + specified at once, in which case their values will be shown one + after the other, separated by newlines. The output is, by + default, in terse format. Use for a + more elaborate output format. + + + + set-property SERVICE OBJECT INTERFACE PROPERTY SIGNATURE ARGUMENT + + Set the current value of an object + property. Takes a service name, object path, interface name, + property name, property signature, followed by a list of + parameters formatted as strings. + + + + help + + Show command syntax help. + + + + + + Parameter Formatting + + The call and + set-property commands take a signature string + followed by a list of parameters formatted as string (for details + on D-Bus signature strings, see the Type + system chapter of the D-Bus specification). For simple + types, each parameter following the signature should simply be the + parameter's value formatted as string. Positive boolean values may + be formatted as true, yes, + on, or 1; negative boolean + values may be specified as false, + no, off, or + 0. For arrays, a numeric argument for the + number of entries followed by the entries shall be specified. For + variants, the signature of the contents shall be specified, + followed by the contents. For dictionaries and structs, the + contents of them shall be directly specified. + + For example, + s jawoll is the formatting + of a single string jawoll. + + + as 3 hello world foobar + is the formatting of a string array with three entries, + hello, world and + foobar. + + + a{sv} 3 One s Eins Two u 2 Yes b true + is the formatting of a dictionary + array that maps strings to variants, consisting of three + entries. The string One is assigned the + string Eins. The string + Two is assigned the 32-bit unsigned + integer 2. The string Yes is assigned a + positive boolean. + + Note that the call, + get-property, introspect + commands will also generate output in this format for the returned + data. Since this format is sometimes too terse to be easily + understood, the call and + get-property commands may generate a more + verbose, multi-line output when passed the + option. + + + + Examples + + + Write and Read a Property + + The following two commands first write a property and then + read it back. The property is found on the + /org/freedesktop/systemd1 object of the + org.freedesktop.systemd1 service. The name of + the property is LogLevel on the + org.freedesktop.systemd1.Manager + interface. The property contains a single string: + + # busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug +# busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel +s "debug" + + + + + Terse and Verbose Output + + The following two commands read a property that contains + an array of strings, and first show it in terse format, followed + by verbose format: + + $ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment +as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin" +$ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment +ARRAY "s" { + STRING "LANG=en_US.UTF-8"; + STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"; +}; + + + + Invoking a Method + + The following command invokes the + StartUnit method on the + org.freedesktop.systemd1.Manager + interface of the + /org/freedesktop/systemd1 object + of the org.freedesktop.systemd1 + service, and passes it two strings + cups.service and + replace. As a result of the method + call, a single object path parameter is received and + shown: + + # busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace" +o "/org/freedesktop/systemd1/job/42684" + + + + + See Also + + + dbus-daemon1, + D-Bus, + sd-bus3, + systemd1, + machinectl1, + wireshark1 + + + diff --git a/src/grp-boot/bootctl/bootctl.xml b/src/grp-boot/bootctl/bootctl.xml new file mode 100644 index 0000000000..ebd58750d3 --- /dev/null +++ b/src/grp-boot/bootctl/bootctl.xml @@ -0,0 +1,128 @@ + + + + + + + + bootctl + systemd + + + + Developer + Kay + Sievers + kay@vrfy.org + + + + + + bootctl + 1 + + + + bootctl + Control the firmware and boot manager settings + + + + + bootctl OPTIONSstatus + + + bootctl OPTIONSupdate + + + bootctl OPTIONSinstall + + + bootctl OPTIONSremove + + + + + Description + + bootctl checks, updates, + installs or removes the boot loader from the current + system. + + bootctl status checks and prints the + currently installed versions of the boot loader binaries and + all current EFI boot variables. + + bootctl update updates all installed + versions of systemd-boot, if the current version is newer than the + version installed in the EFI system partition. This also includes + the EFI default/fallback loader at /EFI/Boot/boot*.efi. A + systemd-boot entry in the EFI boot variables is created if there + is no current entry. The created entry will be added to the end of + the boot order list. + + bootctl install installs systemd-boot into + the EFI system partition. A copy of systemd-boot will be stored as + the EFI default/fallback loader at /EFI/Boot/boot*.efi. A systemd-boot + entry in the EFI boot variables is created and added to the top + of the boot order list. + + bootctl remove removes all installed + versions of systemd-boot from the EFI system partition, and removes + systemd-boot from the EFI boot variables. + + If no command is passed, status is + implied. + + + + Options + The following options are understood: + + + + + + + Path to the EFI system partition. The default is /boot. + + + + + Do not touch the EFI boot variables. + + + + + + Exit status + On success, 0 is returned, a non-zero failure + code otherwise. + + + + See Also + + Boot loader specification + Systemd boot loader interface + + + diff --git a/src/grp-coredump/coredump.conf.xml b/src/grp-coredump/coredump.conf.xml new file mode 100644 index 0000000000..4f95680a3a --- /dev/null +++ b/src/grp-coredump/coredump.conf.xml @@ -0,0 +1,161 @@ + + + + + + + + coredump.conf + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + coredump.conf + 5 + + + + coredump.conf + coredump.conf.d + Core dump storage configuration files + + + + /etc/systemd/coredump.conf + /etc/systemd/coredump.conf.d/*.conf + /run/systemd/coredump.conf.d/*.conf + /usr/lib/systemd/coredump.conf.d/*.conf + + + + Description + + These files configure the behavior of + systemd-coredump8, + a handler for core dumps invoked by the kernel. Whether systemd-coredump is used + is determined by the kernel's + kernel.core_pattern sysctl8 + setting. See + systemd-coredump8 + and + core5 + pages for the details. + + + + + + Options + + All options are configured in the + [Coredump] section: + + + + + Storage= + + Controls where to store cores. One of + none, external, + journal, and both. When + none, the core dumps will be logged but not + stored permanently. When external (the + default), cores will be stored in /var/lib/systemd/coredump. + When journal, cores will be stored in + the journal and rotated following normal journal + rotation patterns. When both, cores + will be stored in both locations. + + When cores are stored in the journal, they might be + compressed following journal compression settings, see + journald.conf5. + When cores are stored externally, they will be compressed + by default, see below. + + + + Compress= + + Controls compression for external + storage. Takes a boolean argument, which defaults to + yes. + + + + + ProcessSizeMax= + + The maximum size in bytes of a core + which will be processed. Core dumps exceeding this size + will be logged, but the backtrace will not be generated + and the core will not be stored. + + + + ExternalSizeMax= + JournalSizeMax= + + The maximum (uncompressed) size in bytes of a + core to be saved. + + + + MaxUse= + KeepFree= + + Enforce limits on the disk space taken up by + externally stored core dumps. makes + sure that old core dumps are removed as soon as the total disk + space taken up by core dumps grows beyond this limit (defaults + to 10% of the total disk size). + controls how much disk space to keep free at least (defaults + to 15% of the total disk size). Note that the disk space used + by core dumps might temporarily exceed these limits while + core dumps are processed. Note that old core dumps are also + removed based on time via + systemd-tmpfiles8. Set + either value to 0 to turn off size-based + clean-up. + + + + + + + See Also + + systemd-journald.service8, + coredumpctl1, + systemd-tmpfiles8 + + + + diff --git a/src/grp-coredump/coredumpctl/coredumpctl.xml b/src/grp-coredump/coredumpctl/coredumpctl.xml new file mode 100644 index 0000000000..abc245be5e --- /dev/null +++ b/src/grp-coredump/coredumpctl/coredumpctl.xml @@ -0,0 +1,259 @@ + + + + + + + + + coredumpctl + systemd + + + + Developer + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + coredumpctl + 1 + + + + coredumpctl + Retrieve and process saved core dumps and metadata + + + + + coredumpctl + OPTIONS + COMMAND + PID|COMM|EXE|MATCH + + + + + Description + + coredumpctl is a tool that can be used to retrieve and process core + dumps and metadata which were saved by + systemd-coredump8. + + + + + Options + + The following options are understood: + + + + + + + + + + Do not print column headers. + + + + + + + + Show information of a single core dump only, instead of listing + all known core dumps. + + + + FIELD + FIELD + + Print all possible data values the specified + field takes in matching core dump entries of the + journal. + + + + FILE + FILE + + Write the core to . + + + + + DIR + DIR + + Use the journal files in the specified . + + + + + + + + Commands + + The following commands are understood: + + + + list + + List core dumps captured in the journal + matching specified characteristics. If no command is + specified, this is the implied default. + + It's worth noting that different restrictions apply to + data saved in the journal and core dump files saved in + /var/lib/systemd/coredump, see overview in + systemd-coredump8. + Thus it may very well happen that a particular core dump is still listed + in the journal while its corresponding core dump file has already been + removed. + + + + info + + Show detailed information about core dumps + captured in the journal. + + + + dump + + Extract the last core dump matching specified + characteristics. The core dump will be written on standard + output, unless an output file is specified with + . + + + + gdb + + Invoke the GNU debugger on the last core dump + matching specified characteristics. + + + + + + + + Matching + + A match can be: + + + + PID + + Process ID of the + process that dumped + core. An integer. + + + + COMM + + Name of the executable (matches + ). Must not contain slashes. + + + + + EXE + + Path to the executable (matches + ). Must contain at least one + slash. + + + + MATCH + + General journalctl predicates (see + journalctl1). + Must contain an equal sign. + + + + + + Exit status + On success, 0 is returned; otherwise, a non-zero failure + code is returned. Not finding any matching core dumps is treated as + failure. + + + + + Examples + + + List all the core dumps of a program named foo + + # coredumpctl list foo + + + + Invoke gdb on the last core dump + + # coredumpctl gdb + + + + Show information about a process that dumped core, + matching by its PID 6654 + + # coredumpctl info 6654 + + + + Extract the last core dump of /usr/bin/bar to a file named + <filename noindex="true">bar.coredump</filename> + + # coredumpctl -o bar.coredump dump /usr/bin/bar + + + + + See Also + + systemd-coredump8, + coredump.conf5, + systemd-journald.service8, + gdb1 + + + + diff --git a/src/grp-coredump/systemd-coredump/systemd-coredump.xml b/src/grp-coredump/systemd-coredump/systemd-coredump.xml new file mode 100644 index 0000000000..a28dc62e5a --- /dev/null +++ b/src/grp-coredump/systemd-coredump/systemd-coredump.xml @@ -0,0 +1,145 @@ + + + + + + + + + systemd-coredump + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-coredump + 8 + + + + systemd-coredump + systemd-coredump.socket + systemd-coredump@.service + Acquire, save and process core dumps + + + + /usr/lib/systemd/systemd-coredump + systemd-coredump@.service + systemd-coredump.socket + + + + Description + systemd-coredump is a system service that can acquire core dumps + from the kernel and handle them in various ways. + + Core dumps can be written to the journal or saved as a file. Once saved they can be retrieved + for further processing, for example in + gdb1. + + + By default, systemd-coredump will log the core dump including a backtrace + if possible to the journal and store the core dump itself in an external file in + /var/lib/systemd/coredump. + + When the kernel invokes systemd-coredump to handle a core dump, + it will connect to the socket created by the systemd-coredump.socket + unit, which in turn will spawn a systemd-coredump@.service instance + to process the core dump. Hence systemd-coredump.socket + and systemd-coredump@.service are helper units which do the actual + processing of core dumps and are subject to normal service management. + + The behavior of a specific program upon reception of a signal is governed by a few + factors which are described in detail in + core5. + In particular, the core dump will only be processed when the related resource limits are sufficient. + + + + + Configuration + For programs started by systemd process resource limits can be set by directive + LimitCore=, see + systemd.exec5. + + + In order to be used systemd-coredump must be configured in + sysctl8 + parameter kernel.core_pattern. The syntax of this parameter is explained in + core5. + Systemd installs the file /usr/lib/sysctl.d/50-coredump.conf which configures + kernel.core_pattern accordingly. This file may be masked or overridden to use a different + setting following normal + sysctl.d5 + rules. + If the sysctl configuration is modified, it must be updated in the kernel before + it takes effect, see + sysctl8 + and + systemd-sysctl8. + + + The behaviour of systemd-coredump itself is configured through the configuration file + /etc/systemd/coredump.conf and corresponding snippets + /etc/systemd/coredump.conf.d/*.conf, see + coredump.conf5. A new + instance of systemd-coredump is invoked upon receiving every core dump. Therefore, changes + in these files will take effect the next time a core dump is received. + + Resources used by core dump files are restricted in two ways. Parameters like maximum size of acquired + core dumps and files can be set in files /etc/systemd/coredump.conf and snippets mentioned + above. In addition the storage time of core dump files is restricted by systemd-tmpfiles, + corresponding settings are by default in /usr/lib/tmpfiles.d/systemd.conf. + + + + Usage + Data stored in the journal can be viewed with + journalctl1 + as usual. + coredumpctl1 + can be used to retrieve saved core dumps independent of their location, to display information and to process + them e.g. by passing to the GNU debugger (gdb). + + + + See Also + + coredump.conf5, + coredumpctl1, + systemd-journald.service8, + systemd-tmpfiles8, + core5, + sysctl.d5, + systemd-sysctl.service8. + + + diff --git a/src/grp-hostname/hostnamectl/hostnamectl.xml b/src/grp-hostname/hostnamectl/hostnamectl.xml new file mode 100644 index 0000000000..60004e9d04 --- /dev/null +++ b/src/grp-hostname/hostnamectl/hostnamectl.xml @@ -0,0 +1,260 @@ + + + + + + + + + hostnamectl + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + hostnamectl + 1 + + + + hostnamectl + Control the system hostname + + + + + hostnamectl + OPTIONS + COMMAND + + + + + Description + + hostnamectl may be used to query and + change the system hostname and related settings. + + This tool distinguishes three different hostnames: the + high-level "pretty" hostname which might include all kinds of + special characters (e.g. "Lennart's Laptop"), the static hostname + which is used to initialize the kernel hostname at boot (e.g. + "lennarts-laptop"), and the transient hostname which is a fallback + value received from network configuration. If a static hostname is + set, and is valid (something other than localhost), then the + transient hostname is not used. + + Note that the pretty hostname has little restrictions on the + characters used, while the static and transient hostnames are + limited to the usually accepted characters of Internet domain + names. + + The static hostname is stored in + /etc/hostname, see + hostname5 + for more information. The pretty hostname, chassis type, and icon + name are stored in /etc/machine-info, see + machine-info5. + + Use + systemd-firstboot1 + to initialize the system host name for mounted (but not booted) + system images. + + + + Options + + The following options are understood: + + + + + + Do not query the user for authentication for + privileged operations. + + + + + + + + If status is used (or no + explicit command is given) and one of those fields is given, + hostnamectl will print out just this + selected hostname. + + If used with set-hostname, only the + selected hostname(s) will be updated. When more than one of + those options is used, all the specified hostnames will be + updated. + + + + + + + + + + The following commands are understood: + + + + status + + Show current system + hostname and related + information. + + + + set-hostname NAME + + Set the system hostname to + NAME. By default, this will alter + the pretty, the static, and the transient hostname alike; + however, if one or more of , + , are + used, only the selected hostnames are changed. If the pretty + hostname is being set, and static or transient are being set + as well, the specified hostname will be simplified in regards + to the character set used before the latter are updated. This + is done by replacing spaces with - and + removing special characters. This ensures that the pretty and + the static hostname are always closely related while still + following the validity rules of the specific name. This + simplification of the hostname string is not done if only the + transient and/or static host names are set, and the pretty + host name is left untouched. + + Pass the empty string as the + hostname to reset the selected hostnames to their default + (usually localhost). + + + + set-icon-name NAME + + Set the system icon name to + NAME. The icon name is used by some + graphical applications to visualize this host. The icon name + should follow the Icon + Naming Specification. + + Pass an empty string to reset the icon name to the + default value, which is determined from chassis type (see + below) and possibly other parameters. + + + + set-chassis TYPE + + Set the chassis type to + TYPE. The chassis type is used by + some graphical applications to visualize the host or alter + user interaction. Currently, the following chassis types are + defined: + desktop, + laptop, + server, + tablet, + handset, + watch, + embedded, + as well as the special chassis types + vm and + container for virtualized systems that lack + an immediate physical chassis. + + Pass an empty string to reset the chassis type to the + default value which is determined from the firmware and + possibly other parameters. + + + + + set-deployment ENVIRONMENT + + Set the deployment environment description. + ENVIRONMENT must be a single word + without any control characters. One of the following is + suggested: + development, + integration, + staging, + production. + + + Pass an empty string to reset to the default empty + value. + + + + + set-location LOCATION + + Set the location string for the system, if it + is known. LOCATION should be a + human-friendly, free-form string describing the physical + location of the system, if it is known and applicable. This + may be as generic as Berlin, Germany or as + specific as Left Rack, 2nd Shelf. + + Pass an empty string to reset to the default empty + value. + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + See Also + + systemd1, + hostname1, + hostname5, + machine-info5, + systemctl1, + systemd-hostnamed.service8, + systemd-firstboot1 + + + + diff --git a/src/grp-hostname/systemd-hostnamed/systemd-hostnamed.service.xml b/src/grp-hostname/systemd-hostnamed/systemd-hostnamed.service.xml new file mode 100644 index 0000000000..6990d41b02 --- /dev/null +++ b/src/grp-hostname/systemd-hostnamed/systemd-hostnamed.service.xml @@ -0,0 +1,85 @@ + + + + + + + + + systemd-hostnamed.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-hostnamed.service + 8 + + + + systemd-hostnamed.service + systemd-hostnamed + Host name bus mechanism + + + + systemd-hostnamed.service + /usr/lib/systemd/systemd-hostnamed + + + + Description + + systemd-hostnamed is a system service + that may be used as a mechanism to change the system's hostname. + systemd-hostnamed is automatically activated + on request and terminates itself when it is unused. + + The tool + hostnamectl1 + is a command line client to this service. + + See the + developer documentation for information about the APIs + systemd-hostnamed provides. + + + + See Also + + systemd1, + hostname5, + machine-info5, + hostnamectl1, + sethostname2 + + + + diff --git a/src/grp-initprogs/grp-sleep/systemd-hibernate-resume-generator/systemd-hibernate-resume-generator.xml b/src/grp-initprogs/grp-sleep/systemd-hibernate-resume-generator/systemd-hibernate-resume-generator.xml new file mode 100644 index 0000000000..d811b9b551 --- /dev/null +++ b/src/grp-initprogs/grp-sleep/systemd-hibernate-resume-generator/systemd-hibernate-resume-generator.xml @@ -0,0 +1,93 @@ + + + + + + + + systemd-hibernate-resume-generator + systemd + + + + Developer + Ivan + Shapovalov + intelfx100@gmail.com + + + + + + systemd-hibernate-resume-generator + 8 + + + + systemd-hibernate-resume-generator + Unit generator for resume= kernel parameter + + + + /usr/lib/systemd/system-generators/systemd-hibernate-resume-generator + + + + Description + + systemd-hibernate-resume-generator is a + generator that instantiates + systemd-hibernate-resume@.service8 + unit according to the value of parameter + specified on the kernel command line. + + + + Kernel Command Line + + systemd-hibernate-resume-generator + understands the following kernel command line parameters: + + + + + resume= + + Takes a path to the resume device. Both + persistent block device paths like + /dev/disk/by-foo/bar and + fstab5-style + specifiers like FOO=bar are + supported. + + + + + + + See Also + + systemd1, + systemd-hibernate-resume@.service8, + kernel-command-line7 + + + + diff --git a/src/grp-initprogs/grp-sleep/systemd-hibernate-resume/systemd-hibernate-resume@.service.xml b/src/grp-initprogs/grp-sleep/systemd-hibernate-resume/systemd-hibernate-resume@.service.xml new file mode 100644 index 0000000000..7d00827447 --- /dev/null +++ b/src/grp-initprogs/grp-sleep/systemd-hibernate-resume/systemd-hibernate-resume@.service.xml @@ -0,0 +1,81 @@ + + + + + + + + systemd-hibernate-resume@.service + systemd + + + + Developer + Ivan + Shapovalov + intelfx100@gmail.com + + + + + + systemd-hibernate-resume@.service + 8 + + + + systemd-hibernate-resume@.service + systemd-hibernate-resume + Resume from hibernation + + + + systemd-hibernate-resume@.service + /usr/lib/systemd/systemd-hibernate-resume + + + + Description + + systemd-hibernate-resume@.service + initiates the resume from hibernation. It is instantiated with the + device to resume from as the template argument. + + systemd-hibernate-resume only supports + the in-kernel hibernation implementation, known as + swsusp. + Internally, it works by writing the major:minor of specified + device node to /sys/power/resume. + + Failing to initiate a resume is not an error condition. It + may mean that there was no resume image (e. g. if the system has + been simply powered off and not hibernated). In such case, the + boot is ordinarily continued. + + + + See Also + + systemd1, + systemd-hibernate-resume-generator8 + + + + diff --git a/src/grp-initprogs/grp-sleep/systemd-sleep/systemd-sleep.conf.xml b/src/grp-initprogs/grp-sleep/systemd-sleep/systemd-sleep.conf.xml new file mode 100644 index 0000000000..9a379ecb94 --- /dev/null +++ b/src/grp-initprogs/grp-sleep/systemd-sleep/systemd-sleep.conf.xml @@ -0,0 +1,186 @@ + + + + + + + + systemd-sleep.conf + systemd + + + + Developer + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + systemd-sleep.conf + 5 + + + + systemd-sleep.conf + sleep.conf.d + Suspend and hibernation configuration file + + + + /etc/systemd/sleep.conf + /etc/systemd/sleep.conf.d/*.conf + /run/systemd/sleep.conf.d/*.conf + /usr/lib/systemd/sleep.conf.d/*.conf + + + + Description + + systemd supports three general + power-saving modes: + + + + suspend + + a low-power state + where execution of the OS is paused, + and complete power loss might result + in lost data, and which is fast to + enter and exit. This corresponds to + suspend, standby, or freeze states as + understood by the kernel. + + + + + hibernate + + a low-power state + where execution of the OS is paused, + and complete power loss does not + result in lost data, and which might + be slow to enter and exit. This + corresponds to the hibernation as + understood by the kernel. + + + + + hybrid-sleep + + a low-power state + where execution of the OS is paused, + which might be slow to enter, and on + complete power loss does not result in + lost data but might be slower to exit + in that case. This mode is called + suspend-to-both by the kernel. + + + + + Settings in these files determine what strings + will be written to + /sys/power/disk and + /sys/power/state by + systemd-sleep8 + when + systemd1 + attempts to suspend or hibernate the machine. + + + + + + Options + + The following options can be configured in the + [Sleep] section of + /etc/systemd/sleep.conf or a + sleep.conf.d file: + + + + SuspendMode= + HibernateMode= + HybridSleepMode= + + The string to be written to + /sys/power/disk by, + respectively, + systemd-suspend.service8, + systemd-hibernate.service8, or + systemd-hybrid-sleep.service8. + More than one value can be specified by separating + multiple values with whitespace. They will be tried + in turn, until one is written without error. If + neither succeeds, the operation will be aborted. + + + + + SuspendState= + HibernateState= + HybridSleepState= + + The string to be written to + /sys/power/state by, + respectively, + systemd-suspend.service8, + systemd-hibernate.service8, or + systemd-hybrid-sleep.service8. + More than one value can be specified by separating + multiple values with whitespace. They will be tried + in turn, until one is written without error. If + neither succeeds, the operation will be aborted. + + + + + + + Example: freeze + + Example: to exploit the freeze mode added + in Linux 3.9, one can use systemctl suspend + with + [Sleep] +SuspendState=freeze + + + + See Also + + systemd-sleep8, + systemd-suspend.service8, + systemd-hibernate.service8, + systemd-hybrid-sleep.service8, + systemd1, + systemd.directives7 + + + + diff --git a/src/grp-initprogs/grp-sleep/systemd-sleep/systemd-suspend.service.xml b/src/grp-initprogs/grp-sleep/systemd-sleep/systemd-suspend.service.xml new file mode 100644 index 0000000000..a8beb86f4d --- /dev/null +++ b/src/grp-initprogs/grp-sleep/systemd-sleep/systemd-suspend.service.xml @@ -0,0 +1,146 @@ + + + + + + + + + systemd-suspend.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-suspend.service + 8 + + + + systemd-suspend.service + systemd-hibernate.service + systemd-hybrid-sleep.service + systemd-sleep + System sleep state logic + + + + systemd-suspend.service + systemd-hibernate.service + systemd-hybrid-sleep.service + /usr/lib/systemd/system-sleep + + + + Description + + systemd-suspend.service is a system + service that is pulled in by suspend.target + and is responsible for the actual system suspend. Similarly, + systemd-hibernate.service is pulled in by + hibernate.target to execute the actual + hibernation. Finally, + systemd-hybrid-sleep.service is pulled in by + hybrid-sleep.target to execute hybrid + hibernation with system suspend. + + Immediately before entering system suspend and/or + hibernation systemd-suspend.service (and the + other mentioned units, respectively) will run all executables in + /usr/lib/systemd/system-sleep/ and pass two + arguments to them. The first argument will be + pre, the second either + suspend, hibernate, or + hybrid-sleep depending on the chosen action. + Immediately after leaving system suspend and/or hibernation the + same executables are run, but the first argument is now + post. All executables in this directory are + executed in parallel, and execution of the action is not continued + until all executables have finished. + + Note that scripts or binaries dropped in + /usr/lib/systemd/system-sleep/ are intended + for local use only and should be considered hacks. If applications + want to be notified of system suspend/hibernation and resume, + there are much nicer interfaces available. + + Note that + systemd-suspend.service, + systemd-hibernate.service, and + systemd-hybrid-sleep.service + should never be executed directly. Instead, trigger system sleep + states with a command such as systemctl suspend + or similar. + + Internally, this service will echo a string like + mem into /sys/power/state, + to trigger the actual system suspend. What exactly is written + where can be configured in the [Sleep] section + of /etc/systemd/sleep.conf or a + sleep.conf.d file. See + systemd-sleep.conf5. + + + + + Options + + systemd-sleep understands the + following commands: + + + + + + + + + + + Suspend, hibernate, or put the system to + hybrid sleep. + + + + + + + See Also + + systemd-sleep.conf5, + systemd1, + systemctl1, + systemd.special7, + systemd-halt.service8 + + + + diff --git a/src/grp-initprogs/systemd-backlight/systemd-backlight@.service.xml b/src/grp-initprogs/systemd-backlight/systemd-backlight@.service.xml new file mode 100644 index 0000000000..3459ed8851 --- /dev/null +++ b/src/grp-initprogs/systemd-backlight/systemd-backlight@.service.xml @@ -0,0 +1,94 @@ + + + + + + + + systemd-backlight@.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-backlight@.service + 8 + + + + systemd-backlight@.service + systemd-backlight + Load and save the display backlight brightness at boot and shutdown + + + + systemd-backlight@.service + /usr/lib/systemd/systemd-backlight + + + + Description + + systemd-backlight@.service is a service + that restores the display backlight brightness at early boot and + saves it at shutdown. On disk, the backlight brightness is stored + in /var/lib/systemd/backlight/. During + loading, if the udev property is + not set to false, the brightness is clamped to a value of at + least 1 or 5% of maximum brightness, whichever is greater. This + restriction will be removed when the kernel allows user space to + reliably set a brightness value which does not turn off the + display. + + + + Kernel Command Line + + systemd-backlight understands the + following kernel command line parameter: + + + + systemd.restore_state= + + Takes a boolean argument. Defaults to + 1. If 0, does not + restore the backlight settings on boot. However, settings will + still be stored on shutdown. + + + + + + See Also + + systemd1 + + + + diff --git a/src/grp-initprogs/systemd-binfmt/binfmt.d.xml b/src/grp-initprogs/systemd-binfmt/binfmt.d.xml new file mode 100644 index 0000000000..5b63cfb4c3 --- /dev/null +++ b/src/grp-initprogs/systemd-binfmt/binfmt.d.xml @@ -0,0 +1,101 @@ + + + + + + + + binfmt.d + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + binfmt.d + 5 + + + + binfmt.d + Configure additional binary formats for + executables at boot + + + + /etc/binfmt.d/*.conf + /run/binfmt.d/*.conf + /usr/lib/binfmt.d/*.conf + + + + Description + + At boot, + systemd-binfmt.service8 + reads configuration files from the above directories to register + in the kernel additional binary formats for executables. + + + + Configuration Format + + Each file contains a list of binfmt_misc kernel binary + format rules. Consult binfmt_misc.txt + for more information on registration of additional binary formats + and how to write rules. + + Empty lines and lines beginning with ; and # are ignored. + Note that this means you may not use ; and # as delimiter in + binary format rules. + + + + + + Example + + /etc/binfmt.d/wine.conf example: + + # Start WINE on Windows executables +:DOSWin:M::MZ::/usr/bin/wine: + + + + + See Also + + systemd1, + systemd-binfmt.service8, + systemd-delta1, + wine8 + + + + diff --git a/src/grp-initprogs/systemd-binfmt/systemd-binfmt.service.xml b/src/grp-initprogs/systemd-binfmt/systemd-binfmt.service.xml new file mode 100644 index 0000000000..cccfb49ca9 --- /dev/null +++ b/src/grp-initprogs/systemd-binfmt/systemd-binfmt.service.xml @@ -0,0 +1,75 @@ + + + + + + + + systemd-binfmt.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-binfmt.service + 8 + + + + systemd-binfmt.service + systemd-binfmt + Configure additional binary formats for executables at boot + + + + systemd-binfmt.service + /usr/lib/systemd/systemd-binfmt + + + + Description + + systemd-binfmt.service is an early boot + service that registers additional binary formats for executables + in the kernel. + + See + binfmt.d5 + for information about the configuration of this service. + + + + See Also + + systemd1, + binfmt.d5, + wine8 + + + + diff --git a/src/grp-initprogs/systemd-detect-virt/systemd-detect-virt.xml b/src/grp-initprogs/systemd-detect-virt/systemd-detect-virt.xml new file mode 100644 index 0000000000..2b7f4e69ab --- /dev/null +++ b/src/grp-initprogs/systemd-detect-virt/systemd-detect-virt.xml @@ -0,0 +1,245 @@ + + + + + + + + + systemd-detect-virt + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-detect-virt + 1 + + + + systemd-detect-virt + Detect execution in a virtualized environment + + + + + systemd-detect-virt OPTIONS + + + + + Description + + systemd-detect-virt detects execution in + a virtualized environment. It identifies the virtualization + technology and can distinguish full machine virtualization from + container virtualization. systemd-detect-virt + exits with a return value of 0 (success) if a virtualization + technology is detected, and non-zero (error) otherwise. By default, + any type of virtualization is detected, and the options + and can be used + to limit what types of virtualization are detected. + + When executed without will print a + short identifier for the detected virtualization technology. The + following technologies are currently identified: + + + Known virtualization technologies (both + VM, i.e. full hardware virtualization, + and container, i.e. shared kernel virtualization) + + + + + + + Type + ID + Product + + + + + VM + qemu + QEMU software virtualization + + + + kvm + Linux KVM kernel virtual machine + + + + zvm + s390 z/VM + + + + vmware + VMware Workstation or Server, and related products + + + + microsoft + Hyper-V, also known as Viridian or Windows Server Virtualization + + + + oracle + Oracle VM VirtualBox (historically marketed by innotek and Sun Microsystems) + + + + xen + Xen hypervisor (only domU, not dom0) + + + + bochs + Bochs Emulator + + + + uml + User-mode Linux + + + + parallels + Parallels Desktop, Parallels Server + + + + Container + openvz + OpenVZ/Virtuozzo + + + + lxc + Linux container implementation by LXC + + + + lxc-libvirt + Linux container implementation by libvirt + + + + systemd-nspawn + systemd's minimal container implementation, see systemd-nspawn1 + + + + docker + Docker container manager + + + + rkt + rkt app container runtime + + + +
+ + If multiple virtualization solutions are used, only the + "innermost" is detected and identified. That means if both + machine and container virtualization are used in + conjunction, only the latter will be identified (unless + is passed). + + + + Options + + The following options are understood: + + + + + + + Only detects container virtualization (i.e. + shared kernel virtualization). + + + + + + + Only detects hardware virtualization). + + + + + + + Detect whether invoked in a + chroot2 + environment. In this mode, no output is written, but the return + value indicates whether the process was invoked in a + chroot() + environment or not. + + + + + + + Suppress output of the virtualization + technology identifier. + + + + + + + + + + Exit status + + If a virtualization technology is detected, 0 is returned, a + non-zero code otherwise. + + + + See Also + + systemd1, + systemd-nspawn1, + chroot2 + + + + diff --git a/src/grp-initprogs/systemd-firstboot/systemd-firstboot.xml b/src/grp-initprogs/systemd-firstboot/systemd-firstboot.xml new file mode 100644 index 0000000000..b269e48113 --- /dev/null +++ b/src/grp-initprogs/systemd-firstboot/systemd-firstboot.xml @@ -0,0 +1,259 @@ + + + + + + + + + systemd-firstboot + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-firstboot + 1 + + + + systemd-firstboot + systemd-firstboot.service + Initialize basic system settings on or before the first boot-up of a system + + + + + systemd-firstboot + OPTIONS + + + systemd-firstboot.service + + + + Description + + systemd-firstboot initializes the most + basic system settings interactively on the first boot, or + optionally non-interactively when a system image is created. The + following settings may be set up: + + + The system locale, more specifically the two + locale variables LANG= and + LC_MESSAGES + + The system time zone + + The system host name + + The machine ID of the system + + The root user's password + + + Each of the fields may either be queried interactively by + users, set non-interactively on the tool's command line, or be + copied from a host system that is used to set up the system + image. + + If a setting is already initialized, it will not be + overwritten and the user will not be prompted for the + setting. + + Note that this tool operates directly on the file system and + does not involve any running system services, unlike + localectl1, + timedatectl1 + or + hostnamectl1. + This allows systemd-firstboot to operate on + mounted but not booted disk images and in early boot. It is not + recommended to use systemd-firstboot on the + running system while it is up. + + + + Options + + The following options are understood: + + + + + Takes a directory path as an argument. All + paths will be prefixed with the given alternate + root path, including config search + paths. This is useful to operate on a system image mounted to + the specified directory instead of the host system itself. + + + + + + + + Sets the system locale, more specifically the + LANG= and LC_MESSAGES + settings. The argument should be a valid locale identifier, + such as de_DE.UTF-8. This controls the + locale.conf5 + configuration file. + + + + + + Sets the system time zone. The argument should + be a valid time zone identifier, such as + Europe/Berlin. This controls the + localtime5 + symlink. + + + + + + Sets the system hostname. The argument should + be a host name, compatible with DNS. This controls the + hostname5 + configuration file. + + + + + + Sets the system's machine ID. This controls + the + machine-id5 + file. + + + + + + + Sets the password of the system's root user. + This creates a + shadow5 + file. This setting exists in two forms: + accepts the password to set + directly on the command line, and + reads it from a file. + Note that it is not recommended to specify passwords on the + command line, as other users might be able to see them simply + by invoking + ps1. + + + + + + + + + Prompt the user interactively for a specific + basic setting. Note that any explicit configuration settings + specified on the command line take precedence, and the user is + not prompted for it. + + + + + + Query the user for locale, timezone, hostname + and root password. This is equivalent to specifying + , + , + , + in combination. + + + + + + + + + Copy a specific basic setting from the host. + This only works in combination with + (see above). + + + + + + Copy locale, time zone and root password from + the host. This is equivalent to specifying + , + , + in combination. + + + + + + + Initialize the system's machine ID to a random + ID. This only works in combination with + . + + + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + See Also + + systemd1, + locale.conf5, + localtime5, + hostname5, + machine-id5, + shadow5, + systemd-machine-id-setup1, + localectl1, + timedatectl1, + hostnamectl1 + + + + diff --git a/src/grp-initprogs/systemd-fsck/systemd-fsck@.service.xml b/src/grp-initprogs/systemd-fsck/systemd-fsck@.service.xml new file mode 100644 index 0000000000..933c3247ad --- /dev/null +++ b/src/grp-initprogs/systemd-fsck/systemd-fsck@.service.xml @@ -0,0 +1,139 @@ + + + + + + + + systemd-fsck@.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-fsck@.service + 8 + + + + systemd-fsck@.service + systemd-fsck-root.service + systemd-fsck + File system checker logic + + + + systemd-fsck@.service + systemd-fsck-root.service + /usr/lib/systemd/systemd-fsck + + + + Description + + systemd-fsck@.service and + systemd-fsck-root.service are services + responsible for file system checks. They are instantiated for each + device that is configured for file system checking. + systemd-fsck-root.service is responsible for + file system checks on the root file system, but only if the + root filesystem was not checked in the initramfs. + systemd-fsck@.service is used for all other + file systems and for the root file system in the initramfs. + + These services are started at boot if + in /etc/fstab for the + file system is set to a value greater than zero. The file system + check for root is performed before the other file systems. Other + file systems may be checked in parallel, except when they are on + the same rotating disk. + + systemd-fsck does not know any details + about specific filesystems, and simply executes file system + checkers specific to each filesystem type + (/sbin/fsck.*). This helper will decide if + the filesystem should actually be checked based on the time since + last check, number of mounts, unclean unmount, etc. + + If a file system check fails for a service without + , emergency mode is activated, by isolating + to emergency.target. + + + + Kernel Command Line + + systemd-fsck understands one kernel + command line parameter: + + + + fsck.mode= + + One of auto, + force, skip. Controls + the mode of operation. The default is auto, + and ensures that file system checks are done when the file + system checker deems them necessary. force + unconditionally results in full file system checks. + skip skips any file system + checks. + + + + fsck.repair= + + One of preen, + yes, no. Controls the + mode of operation. The default is preen, + and will automatically repair problems that can be safely + fixed. yes will answer yes to all + questions by fsck and no will answer no to + all questions. + + + + + + See Also + + systemd1, + fsck8, + systemd-quotacheck.service8, + fsck.btrfs8, + fsck.cramfs8, + fsck.ext48, + fsck.fat8, + fsck.hfsplus8, + fsck.minix8, + fsck.ntfs8, + fsck.xfs8 + + + + diff --git a/src/grp-initprogs/systemd-modules-load/modules-load.d.xml b/src/grp-initprogs/systemd-modules-load/modules-load.d.xml new file mode 100644 index 0000000000..4b722aa128 --- /dev/null +++ b/src/grp-initprogs/systemd-modules-load/modules-load.d.xml @@ -0,0 +1,101 @@ + + + + + + + + modules-load.d + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + modules-load.d + 5 + + + + modules-load.d + Configure kernel modules to load at boot + + + + /etc/modules-load.d/*.conf + /run/modules-load.d/*.conf + /usr/lib/modules-load.d/*.conf + + + + Description + + systemd-modules-load.service8 + reads files from the above directories which contain kernel + modules to load during boot in a static list. Each configuration + file is named in the style of + /etc/modules-load.d/program.conf. + Note that it is usually a better idea to rely on the automatic + module loading by PCI IDs, USB IDs, DMI IDs or similar triggers + encoded in the kernel modules themselves instead of static + configuration like this. In fact, most modern kernel modules are + prepared for automatic loading already. + + + + Configuration Format + + The configuration files should simply contain a list of + kernel module names to load, separated by newlines. Empty lines + and lines whose first non-whitespace character is # or ; are + ignored. + + + + + + Example + + /etc/modules-load.d/virtio-net.conf example: + + # Load virtio-net.ko at boot +virtio-net + + + + + See Also + + systemd1, + systemd-modules-load.service8, + systemd-delta1, + modprobe8 + + + + diff --git a/src/grp-initprogs/systemd-modules-load/systemd-modules-load.service.xml b/src/grp-initprogs/systemd-modules-load/systemd-modules-load.service.xml new file mode 100644 index 0000000000..b25929b2e4 --- /dev/null +++ b/src/grp-initprogs/systemd-modules-load/systemd-modules-load.service.xml @@ -0,0 +1,96 @@ + + + + + + + + systemd-modules-load.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-modules-load.service + 8 + + + + systemd-modules-load.service + systemd-modules-load + Load kernel modules at boot + + + + systemd-modules-load.service + /usr/lib/systemd/systemd-modules-load + + + + Description + + systemd-modules-load.service is an + early boot service that loads kernel modules based on static + configuration. + + See + modules-load.d5 + for information about the configuration of this service. + + + + + Kernel Command Line + + systemd-modules-load.service + understands the following kernel command line parameters: + + + + + modules-load= + rd.modules-load= + + Takes a comma-separated list of kernel modules + to statically load during early boot. The option prefixed with + rd. is read by the initial RAM disk + only. + + + + + + + See Also + + systemd1, + modules-load.d5, + + + + diff --git a/src/grp-initprogs/systemd-quotacheck/systemd-quotacheck.service.xml b/src/grp-initprogs/systemd-quotacheck/systemd-quotacheck.service.xml new file mode 100644 index 0000000000..9d4976274e --- /dev/null +++ b/src/grp-initprogs/systemd-quotacheck/systemd-quotacheck.service.xml @@ -0,0 +1,94 @@ + + + + + + + + systemd-quotacheck.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-quotacheck.service + 8 + + + + systemd-quotacheck.service + systemd-quotacheck + File system quota checker logic + + + + systemd-quotacheck.service + /usr/lib/systemd/systemd-quotacheck + + + + Description + + systemd-quotacheck.service is a service + responsible for file system quota checks. It is run once at boot + after all necessary file systems are mounted. It is pulled in only + if at least one file system has quotas enabled. + + + + Kernel Command Line + + systemd-quotacheck understands one + kernel command line parameter: + + + + quotacheck.mode= + + One of auto, + force, skip. Controls + the mode of operation. The default is auto, + and ensures that file system quota checks are done when the + file system quota checker deems them necessary. + force unconditionally results in full file + system quota checks. skip skips any file + system quota checks. + + + + + + See Also + + systemd1, + quotacheck8, + systemd-fsck@.service8 + + + + diff --git a/src/grp-initprogs/systemd-random-seed/systemd-random-seed.service.xml b/src/grp-initprogs/systemd-random-seed/systemd-random-seed.service.xml new file mode 100644 index 0000000000..f3b5a947da --- /dev/null +++ b/src/grp-initprogs/systemd-random-seed/systemd-random-seed.service.xml @@ -0,0 +1,75 @@ + + + + + + + + systemd-random-seed.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-random-seed.service + 8 + + + + systemd-random-seed.service + systemd-random-seed + Load and save the system random seed at boot and shutdown + + + + systemd-random-seed.service + /usr/lib/systemd/systemd-random-seed + + + + Description + + systemd-random-seed.service is a + service that restores the random seed of the system at early boot + and saves it at shutdown. See + random4 + for details. Saving/restoring the random seed across boots + increases the amount of available entropy early at boot. On disk + the random seed is stored in + /var/lib/systemd/random-seed. + + + + See Also + + systemd1, + random4 + + + + diff --git a/src/grp-initprogs/systemd-rfkill/systemd-rfkill.service.xml b/src/grp-initprogs/systemd-rfkill/systemd-rfkill.service.xml new file mode 100644 index 0000000000..f464842700 --- /dev/null +++ b/src/grp-initprogs/systemd-rfkill/systemd-rfkill.service.xml @@ -0,0 +1,90 @@ + + + + + + + + systemd-rfkill.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-rfkill.service + 8 + + + + systemd-rfkill.service + systemd-rfkill.socket + systemd-rfkill + Load and save the RF kill switch state at boot and change + + + + systemd-rfkill.service + systemd-rfkill.socket + /usr/lib/systemd/systemd-rfkill + + + + Description + + systemd-rfkill.service is a service + that restores the RF kill switch state at early boot and saves it + on each change. On disk, the RF kill switch state is stored in + /var/lib/systemd/rfkill/. + + + + Kernel Command Line + + systemd-rfkill understands the + following kernel command line parameter: + + + + systemd.restore_state= + + Takes a boolean argument. Defaults to + 1. If 0, does not + restore the rfkill settings on boot. However, settings will + still be stored on shutdown. + + + + + + See Also + + systemd1 + + + + diff --git a/src/grp-initprogs/systemd-sysctl/sysctl.d.xml b/src/grp-initprogs/systemd-sysctl/sysctl.d.xml new file mode 100644 index 0000000000..ccf6c8e39f --- /dev/null +++ b/src/grp-initprogs/systemd-sysctl/sysctl.d.xml @@ -0,0 +1,184 @@ + + + + + + + sysctl.d + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sysctl.d + 5 + + + + sysctl.d + Configure kernel parameters at boot + + + + /etc/sysctl.d/*.conf + /run/sysctl.d/*.conf + /usr/lib/sysctl.d/*.conf + + + + Description + + At boot, + systemd-sysctl.service8 + reads configuration files from the above directories to configure + sysctl8 + kernel parameters. + + + + Configuration Format + + The configuration files contain a list of variable + assignments, separated by newlines. Empty lines and lines whose + first non-whitespace character is # or + ; are ignored. + + Note that either / or + . may be used as separators within sysctl + variable names. If the first separator is a slash, remaining + slashes and dots are left intact. If the first separator is a dot, + dots and slashes are interchanged. + kernel.domainname=foo and + kernel/domainname=foo are equivalent and will + cause foo to be written to + /proc/sys/kernel/domainname. Either + net.ipv4.conf.enp3s0/200.forwarding or + net/ipv4/conf/enp3s0.200/forwarding may be used + to refer to + /proc/sys/net/ipv4/conf/enp3s0.200/forwarding. + + + The settings configured with sysctl.d + files will be applied early on boot. The network + interface-specific options will also be applied individually for + each network interface as it shows up in the system. (More + specifically, net.ipv4.conf.*, + net.ipv6.conf.*, + net.ipv4.neigh.* and + net.ipv6.neigh.*). + + Many sysctl parameters only become available when certain + kernel modules are loaded. Modules are usually loaded on demand, + e.g. when certain hardware is plugged in or network brought up. + This means that + systemd-sysctl.service8 + which runs during early boot will not configure such parameters if + they become available after it has run. To set such parameters, it + is recommended to add an + udev7 + rule to set those parameters when they become available. + Alternatively, a slightly simpler and less efficient option is to + add the module to + modules-load.d5, + causing it to be loaded statically before sysctl settings are + applied (see example below). + + + + + + Examples + + Set kernel YP domain name + /etc/sysctl.d/domain-name.conf: + + + kernel.domainname=example.com + + + + Apply settings available only when a certain module is loaded (method one) + /etc/udev/rules.d/99-bridge.rules: + + + ACTION=="add", SUBSYSTEM=="module", KERNEL=="br_netfilter", \ + RUN+="/usr/lib/systemd/systemd-sysctl --prefix=/net/bridge" + + + /etc/sysctl.d/bridge.conf: + + + net.bridge.bridge-nf-call-ip6tables = 0 +net.bridge.bridge-nf-call-iptables = 0 +net.bridge.bridge-nf-call-arptables = 0 + + + This method applies settings when the module is + loaded. Please note that, unless the br_netfilter + module is loaded, bridged packets will not be filtered by + Netfilter (starting with kernel 3.18), so simply not loading the + module is sufficient to avoid filtering. + + + + Apply settings available only when a certain module is loaded (method two) + /etc/modules-load.d/bridge.conf: + + + br_netfilter + + /etc/sysctl.d/bridge.conf: + + + net.bridge.bridge-nf-call-ip6tables = 0 +net.bridge.bridge-nf-call-iptables = 0 +net.bridge.bridge-nf-call-arptables = 0 + + + This method forces the module to be always loaded. Please + note that, unless the br_netfilter module is + loaded, bridged packets will not be filtered with Netfilter + (starting with kernel 3.18), so simply not loading the module is + sufficient to avoid filtering. + + + + + See Also + + systemd1, + systemd-sysctl.service8, + systemd-delta1, + sysctl8, + sysctl.conf5, + modprobe8 + + + + diff --git a/src/grp-initprogs/systemd-sysctl/systemd-sysctl.service.xml b/src/grp-initprogs/systemd-sysctl/systemd-sysctl.service.xml new file mode 100644 index 0000000000..686b2cdef4 --- /dev/null +++ b/src/grp-initprogs/systemd-sysctl/systemd-sysctl.service.xml @@ -0,0 +1,152 @@ + + + + + + + + systemd-sysctl.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-sysctl.service + 8 + + + + systemd-sysctl.service + systemd-sysctl + Configure kernel parameters at boot + + + + + /usr/lib/systemd/systemd-sysctl + OPTIONS + CONFIGFILE + + systemd-sysctl.service + + + + Description + + systemd-sysctl.service is an early boot + service that configures + sysctl8 + kernel parameters by invoking /usr/lib/systemd/systemd-sysctl. + + When invoked with no arguments, /usr/lib/systemd/systemd-sysctl applies + all directives from configuration files listed in + sysctl.d5. + If one or more filenames are passed on the command line, only the directives in these files are + applied. + + In addition, option may be used to limit which sysctl + settings are applied. + + See + sysctl.d5 + for information about the configuration of sysctl settings. After sysctl configuration is + changed on disk, it must be written to the files in /proc/sys before it + takes effect. It is possible to update specific settings, or simply to reload all configuration, + see Examples below. + + + Options + + + + + Only apply rules with the specified prefix. + + + + + + + + + + + Examples + + + Reset all sysctl settings + + systemctl restart systemd-sysctl + + + + View coredump handler configuration + + # sysctl kernel.core_pattern +kernel.core_pattern = |/usr/libexec/abrt-hook-ccpp %s %c %p %u %g %t %P %I + + + + + Update coredump handler configuration + + # /usr/lib/systemd/systemd-sysctl --prefix kernel.core_pattern + + This searches all the directories listed in + sysctl.d5 + for configuration files and writes /proc/sys/kernel/core_pattern. + + + + Update coredump handler configuration according to a specific file + + # /usr/lib/systemd/systemd-sysctl 50-coredump.conf + + This applies all the settings found in 50-coredump.conf. + Either /etc/sysctl.d/50-coredump.conf, or + /run/sysctl.d/50-coredump.conf, or + /usr/lib/sysctl.d/50-coredump.conf will be used, in the order + of preference. + + + See + sysctl8 + for various ways to directly apply sysctl settings. + + + + See Also + + systemd1, + sysctl.d5, + sysctl8, + + + + diff --git a/src/grp-initprogs/systemd-sysusers/systemd-sysusers.xml b/src/grp-initprogs/systemd-sysusers/systemd-sysusers.xml new file mode 100644 index 0000000000..4892caad12 --- /dev/null +++ b/src/grp-initprogs/systemd-sysusers/systemd-sysusers.xml @@ -0,0 +1,116 @@ + + + + + + + + + systemd-sysusers + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-sysusers + 8 + + + + systemd-sysusers + systemd-sysusers.service + Allocate system users and groups + + + + + systemd-sysusers + OPTIONS + CONFIGFILE + + + systemd-sysusers.service + + + + Description + + systemd-sysusers creates system users and + groups, based on the file format and location specified in + sysusers.d5. + + + If invoked with no arguments, it applies all directives from + all files found. If one or more filenames are passed on the + command line, only the directives in these files are applied. If + only the basename of a file is specified, all directories as + specified in + sysusers.d5 + are searched for a matching file. If the string + - is specified as filename, entries from the + standard input of the process are read. + + + + Options + + The following options are understood: + + + + + Takes a directory path as an argument. All + paths will be prefixed with the given alternate + root path, including config search + paths. + + + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + See Also + + systemd1, + sysusers.d5 + + + + diff --git a/src/grp-initprogs/systemd-sysusers/sysusers.d.xml b/src/grp-initprogs/systemd-sysusers/sysusers.d.xml new file mode 100644 index 0000000000..18ee3800d6 --- /dev/null +++ b/src/grp-initprogs/systemd-sysusers/sysusers.d.xml @@ -0,0 +1,223 @@ + + + + + + + + sysusers.d + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sysusers.d + 5 + + + + sysusers.d + Declarative allocation of system users and groups + + + + /usr/lib/sysusers.d/*.conf + + + + Description + + systemd-sysusers uses the files from + sysusers.d directory to create system users + and groups at package installation or boot time. This tool may be + used to allocate system users and groups only, it is not useful + for creating non-system users and groups, as it accesses + /etc/passwd and + /etc/group directly, bypassing any more + complex user databases, for example any database involving NIS or + LDAP. + + + + Configuration Format + + Each configuration file shall be named in the style of + package.conf or + package-part.conf. + The second variant should be used when it is desirable to make it + easy to override just this part of configuration. + + The file format is one line per user or group containing + name, ID, GECOS field description and home directory: + + # Type Name ID GECOS +u httpd 440 "HTTP User" +u authd /usr/bin/authd "Authorization user" +g input - - +m authd input +u root 0 "Superuser" /root + + + Type + + The type consists of a single letter. The following line + types are understood: + + + + u + Create a system user and group of the + specified name should they not exist yet. The user's primary + group will be set to the group bearing the same name. The + user's shell will be set to + /sbin/nologin, the home directory to + the specified home directory, or / if + none is given. The account will be created disabled, so that + logins are not allowed. + + + + g + Create a system group of the specified name + should it not exist yet. Note that u + implicitly create a matching group. The group will be + created with no password set. + + + + m + Add a user to a group. If the user or group + do not exist yet, they will be implicitly + created. + + + + r + Add a range of numeric UIDs/GIDs to the pool + to allocate new UIDs and GIDs from. If no line of this type + is specified, the range of UIDs/GIDs is set to some + compiled-in default. Note that both UIDs and GIDs are + allocated from the same pool, in order to ensure that users + and groups of the same name are likely to carry the same + numeric UID and GID. + + + + + + + Name + + The name field specifies the user or group name. It should + be shorter than 31 characters and avoid any non-ASCII + characters, and not begin with a numeric character. It is + strongly recommended to pick user and group names that are + unlikely to clash with normal users created by the + administrator. A good scheme to guarantee this is by prefixing + all system and group names with the underscore, and avoiding too + generic names. + + For m lines, this field should contain + the user name to add to a group. + + For lines of type r, this field should + be set to -. + + + + ID + + For u and g, the + numeric 32-bit UID or GID of the user/group. Do not use IDs 65535 + or 4294967295, as they have special placeholder meanings. + Specify - for automatic UID/GID allocation + for the user or group. Alternatively, specify an absolute path + in the file system. In this case, the UID/GID is read from the + path's owner/group. This is useful to create users whose UID/GID + match the owners of pre-existing files (such as SUID or SGID + binaries). + + For m lines, this field should contain + the group name to add to a user to. + + For lines of type r, this field should + be set to a UID/GID range in the format + FROM-TO, where both values are formatted as + decimal ASCII numbers. Alternatively, a single UID/GID may be + specified formatted as decimal ASCII numbers. + + + + GECOS + + A short, descriptive string for users to be created, + enclosed in quotation marks. Note that this field may not + contain colons. + + Only applies to lines of type u and + should otherwise be left unset, or be set to + -. + + + + Home Directory + + The home directory for a new system user. If omitted, + defaults to the root directory. It is recommended to not + unnecessarily specify home directories for system users, unless + software strictly requires one to be set. + + Only applies to lines of type u and + should otherwise be left unset, or be set to + -. + + + + + + + + Idempotence + + Note that systemd-sysusers will do + nothing if the specified users or groups already exist, so + normally, there is no reason to override + sysusers.d vendor configuration, except to + block certain users or groups from being created. + + + + See Also + + systemd1, + systemd-sysusers8 + + + + diff --git a/src/grp-initprogs/systemd-tmpfiles/systemd-tmpfiles.xml b/src/grp-initprogs/systemd-tmpfiles/systemd-tmpfiles.xml new file mode 100644 index 0000000000..c1aab51551 --- /dev/null +++ b/src/grp-initprogs/systemd-tmpfiles/systemd-tmpfiles.xml @@ -0,0 +1,200 @@ + + + + + + + + + systemd-tmpfiles + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-tmpfiles + 8 + + + + systemd-tmpfiles + systemd-tmpfiles-setup.service + systemd-tmpfiles-setup-dev.service + systemd-tmpfiles-clean.service + systemd-tmpfiles-clean.timer + Creates, deletes and cleans up volatile + and temporary files and directories + + + + + systemd-tmpfiles + OPTIONS + CONFIGFILE + + + systemd-tmpfiles-setup.service + systemd-tmpfiles-setup-dev.service + systemd-tmpfiles-clean.service + systemd-tmpfiles-clean.timer + + + + Description + + systemd-tmpfiles creates, deletes, and + cleans up volatile and temporary files and directories, based on + the configuration file format and location specified in + tmpfiles.d5. + + + If invoked with no arguments, it applies all directives from all configuration + files. If one or more absolute filenames are passed on the command line, only the + directives in these files are applied. If - is specified instead + of a filename, directives are read from standard input. If only the basename of a + configuration file is specified, all configuration directories as specified in + tmpfiles.d5 + are searched for a matching file. + + + + Options + + The following options are understood: + + + + + If this option is passed, all files and + directories marked with + f, + F, + w, + d, + D, + v, + p, + L, + c, + b, + m + in the configuration files are created or written to. Files + and directories marked with + z, + Z, + t, + T, + a, and + A have their ownership, access mode and + security labels set. + + + + + If this option is passed, all files and + directories with an age parameter configured will be cleaned + up. + + + + + If this option is passed, the contents of + directories marked with D or + R, and files or directories themselves + marked with r or R are + removed. + + + + Also execute lines with an exclamation mark. + + + + + Only apply rules with paths that start with + the specified prefix. This option can be specified multiple + times. + + + + Ignore rules with paths that start with the + specified prefix. This option can be specified multiple + times. + + + + Takes a directory path as an argument. All + paths will be prefixed with the given alternate + root path, including config search + paths. + + + + + + + It is possible to combine , + , and in one + invocation. For example, during boot the following command line is + executed to ensure that all temporary and volatile directories are + removed and created according to the configuration file: + + systemd-tmpfiles --remove --create + + + + + Unprivileged --cleanup operation + + systemd-tmpfiles tries to avoid changing + the access and modification times on the directories it accesses, + which requires CAP_ADMIN privileges. When + running as non-root, directories which are checked for files to + clean up will have their access time bumped, which might prevent + their cleanup. + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + See Also + + systemd1, + tmpfiles.d5 + + + + diff --git a/src/grp-initprogs/systemd-tmpfiles/tmpfiles.d.xml b/src/grp-initprogs/systemd-tmpfiles/tmpfiles.d.xml new file mode 100644 index 0000000000..957475d2bd --- /dev/null +++ b/src/grp-initprogs/systemd-tmpfiles/tmpfiles.d.xml @@ -0,0 +1,703 @@ + + + + + + + tmpfiles.d + systemd + + + + Documentation + Brandon + Philips + brandon@ifup.org + + + + + + tmpfiles.d + 5 + + + + tmpfiles.d + Configuration for creation, deletion and cleaning of + volatile and temporary files + + + + /etc/tmpfiles.d/*.conf + /run/tmpfiles.d/*.conf + /usr/lib/tmpfiles.d/*.conf + + + + Description + + systemd-tmpfiles uses the configuration + files from the above directories to describe the creation, + cleaning and removal of volatile and temporary files and + directories which usually reside in directories such as + /run or /tmp. + + Volatile and temporary files and directories are those + located in /run (and its alias + /var/run), /tmp, + /var/tmp, the API file systems such as + /sys or /proc, as well + as some other directories below /var. + + System daemons frequently require private runtime + directories below /run to place communication + sockets and similar in. For these, consider declaring them in + their unit files using RuntimeDirectory= (see + systemd.exec5 + for details), if this is feasible. + + + + Configuration Format + + Each configuration file shall be named in the style of + package.conf or + package-part.conf. + The second variant should be used when it is desirable to make it + easy to override just this part of configuration. + + Files in /etc/tmpfiles.d override files + with the same name in /usr/lib/tmpfiles.d and + /run/tmpfiles.d. Files in + /run/tmpfiles.d override files with the same + name in /usr/lib/tmpfiles.d. Packages should + install their configuration files in + /usr/lib/tmpfiles.d. Files in + /etc/tmpfiles.d are reserved for the local + administrator, who may use this logic to override the + configuration files installed by vendor packages. All + configuration files are sorted by their filename in lexicographic + order, regardless of which of the directories they reside in. If + multiple files specify the same path, the entry in the file with + the lexicographically earliest name will be applied. All other + conflicting entries will be logged as errors. When two lines are + prefix and suffix of each other, then the prefix is always + processed first, the suffix later. Lines that take globs are + applied after those accepting no globs. If multiple operations + shall be applied on the same file, (such as ACL, xattr, file + attribute adjustments), these are always done in the same fixed + order. Otherwise, the files/directories are processed in the order + they are listed. + + If the administrator wants to disable a configuration file + supplied by the vendor, the recommended way is to place a symlink + to /dev/null in + /etc/tmpfiles.d/ bearing the same filename. + + + The configuration format is one line per path containing + type, path, mode, ownership, age, and argument fields: + + #Type Path Mode UID GID Age Argument + d /run/user 0755 root root 10d - + L /tmp/foobar - - - - /dev/null + + Fields may be enclosed within quotes and contain C-style escapes. + + + Type + + The type consists of a single letter and optionally an + exclamation mark. + + The following line types are understood: + + + + f + Create a file if it does not exist yet. If + the argument parameter is given, it will be written to the + file. Does not follow symlinks. + + + + F + Create or truncate a file. If the argument + parameter is given, it will be written to the file. Does not follow symlinks. + + + + + w + Write the argument parameter to a file, if + the file exists. Lines of this type accept shell-style + globs in place of normal path names. The argument parameter + will be written without a trailing newline. C-style + backslash escapes are interpreted. Follows + symlinks. + + + + d + Create a directory. The mode and ownership will be adjusted if + specified and the directory already exists. Contents of this directory are subject + to time based cleanup if the time argument is specified. + + + + D + Similar to d, but in addition the contents + of the directory will be removed when is used. + + + + + e + Similar to d, but the directory will not be + created if it does not exist. Lines of this type accept shell-style globs in + place of normal path names. + + + + v + Create a subvolume if the path does not + exist yet, the file system supports subvolumes (btrfs), and + the system itself is installed into a subvolume + (specifically: the root directory / is + itself a subvolume). Otherwise, create a normal directory, in + the same way as d. A subvolume created + with this line type is not assigned to any higher-level + quota group. For that, use q or + Q, which allow creating simple quota + group hierarchies, see below. + + + + q + Similar to v. However, + makes sure that the subvolume will be assigned to the same + higher-level quota groups as the subvolume it has been + created in. This ensures that higher-level limits and + accounting applied to the parent subvolume also include the + specified subvolume. On non-btrfs file systems, this line + type is identical to d. If the subvolume + already exists and is already assigned to one or more higher + level quota groups, no change to the quota hierarchy is + made. Also see Q below. See btrfs-qgroup8 + for details about the btrfs quota group + concept. + + + + Q + Similar to q. However, + instead of copying the higher-level quota group assignments + from the parent as-is, the lowest quota group of the parent + subvolume is determined that is not the leaf quota + group. Then, an "intermediary" quota group is inserted that + is one level below this level, and shares the same ID part + as the specified subvolume. If no higher-level quota group + exists for the parent subvolume, a new quota group at level + 255 sharing the same ID as the specified subvolume is + inserted instead. This new intermediary quota group is then + assigned to the parent subvolume's higher-level quota + groups, and the specified subvolume's leaf quota group is + assigned to it. + + Effectively, this has a similar effect as + q, however introduces a new higher-level + quota group for the specified subvolume that may be used to + enforce limits and accounting to the specified subvolume and + children subvolume created within it. Thus, by creating + subvolumes only via q and + Q, a concept of "subtree quotas" is + implemented. Each subvolume for which Q + is set will get a "subtree" quota group created, and all + child subvolumes created within it will be assigned to + it. Each subvolume for which q is set + will not get such a "subtree" quota group, but it is ensured + that they are added to the same "subtree" quota group as their + immediate parents. + + It is recommended to use + Q for subvolumes that typically contain + further subvolumes, and where it is desirable to have + accounting and quota limits on all child subvolumes + together. Examples for Q are typically + /home or + /var/lib/machines. In contrast, + q should be used for subvolumes that + either usually do not include further subvolumes or where no + accounting and quota limits are needed that apply to all + child subvolumes together. Examples for q + are typically /var or + /var/tmp. As with Q, + q has no effect on the quota group + hierarchy if the subvolume exists and already has at least + one higher-level quota group assigned. + + + + p + p+ + Create a named pipe (FIFO) if it does not + exist yet. If suffixed with + and a file + already exists where the pipe is to be created, it will be + removed and be replaced by the pipe. + + + + L + L+ + Create a symlink if it does not exist + yet. If suffixed with + and a file + already exists where the symlink is to be created, it will + be removed and be replaced by the symlink. If the argument + is omitted, symlinks to files with the same name residing in + the directory /usr/share/factory/ are + created. Note that permissions and ownership on symlinks + are ignored. + + + + c + c+ + Create a character device node if it does + not exist yet. If suffixed with + and a + file already exists where the device node is to be created, + it will be removed and be replaced by the device node. It is + recommended to suffix this entry with an exclamation mark to + only create static device nodes at boot, as udev will not + manage static device nodes that are created at runtime. + + + + + b + b+ + Create a block device node if it does not + exist yet. If suffixed with + and a file + already exists where the device node is to be created, it + will be removed and be replaced by the device node. It is + recommended to suffix this entry with an exclamation mark to + only create static device nodes at boot, as udev will not + manage static device nodes that are created at runtime. + + + + + C + Recursively copy a file or directory, if the + destination files or directories do not exist yet. Note that + this command will not descend into subdirectories if the + destination directory already exists. Instead, the entire + copy operation is skipped. If the argument is omitted, files + from the source directory + /usr/share/factory/ with the same name + are copied. Does not follow symlinks. + + + + x + Ignore a path during cleaning. Use this type + to exclude paths from clean-up as controlled with the Age + parameter. Note that lines of this type do not influence the + effect of r or R + lines. Lines of this type accept shell-style globs in place + of normal path names. + + + + X + Ignore a path during cleaning. Use this type + to exclude paths from clean-up as controlled with the Age + parameter. Unlike x, this parameter will + not exclude the content if path is a directory, but only + directory itself. Note that lines of this type do not + influence the effect of r or + R lines. Lines of this type accept + shell-style globs in place of normal path names. + + + + + r + Remove a file or directory if it exists. + This may not be used to remove non-empty directories, use + R for that. Lines of this type accept + shell-style globs in place of normal path + names. Does not follow symlinks. + + + + R + Recursively remove a path and all its + subdirectories (if it is a directory). Lines of this type + accept shell-style globs in place of normal path + names. Does not follow symlinks. + + + + z + Adjust the access mode, group and user, and + restore the SELinux security context of a file or directory, + if it exists. Lines of this type accept shell-style globs in + place of normal path names. Does not follow symlinks. + + + + Z + Recursively set the access mode, group and + user, and restore the SELinux security context of a file or + directory if it exists, as well as of its subdirectories and + the files contained therein (if applicable). Lines of this + type accept shell-style globs in place of normal path + names. Does not follow symlinks. + + + + t + Set extended attributes. Lines of this type + accept shell-style globs in place of normal path names. + This can be useful for setting SMACK labels. Does not follow + symlinks. + + + + T + Recursively set extended attributes. Lines + of this type accept shell-style globs in place of normal + path names. This can be useful for setting SMACK + labels. Does not follow symlinks. + + + + h + Set file/directory attributes. Lines of this type + accept shell-style globs in place of normal path names. + + The format of the argument field is + [+-=][aAcCdDeijsStTu] . The prefix + + (the default one) causes the + attribute(s) to be added; - causes the + attribute(s) to be removed; = causes the + attributes to be set exactly as the following letters. The + letters aAcCdDeijsStTu select the new + attributes for the files, see + chattr + 1 for further information. + + Passing only = as argument resets + all the file attributes listed above. It has to be pointed + out that the = prefix limits itself to + the attributes corresponding to the letters listed here. All + other attributes will be left untouched. Does not follow + symlinks. + + + + + H + Recursively set file/directory attributes. Lines + of this type accept shell-style globs in place of normal + path names. Does not follow symlinks. + + + + + a + a+ + Set POSIX ACLs (access control lists). If + suffixed with +, the specified entries will + be added to the existing set. + systemd-tmpfiles will automatically add + the required base entries for user and group based on the + access mode of the file, unless base entries already exist + or are explicitly specified. The mask will be added if not + specified explicitly or already present. Lines of this type + accept shell-style globs in place of normal path names. This + can be useful for allowing additional access to certain + files. Does not follow symlinks. + + + + A + A+ + Same as a and + a+, but recursive. Does not follow + symlinks. + + + + If the exclamation mark is used, this line is only safe of + execute during boot, and can break a running system. Lines + without the exclamation mark are presumed to be safe to execute + at any time, e.g. on package upgrades. + systemd-tmpfiles will execute line with an + exclamation mark only if option is + given. + + For example: + # Make sure these are created by default so that nobody else can + d /tmp/.X11-unix 1777 root root 10d + + # Unlink the X11 lock files + r! /tmp/.X[0-9]*-lock + The second line in contrast to the first one would break a + running system, and will only be executed with + . + + + + Path + + The file system path specification supports simple + specifier expansion. The following expansions are + understood: + + + Specifiers available + + + + + + + Specifier + Meaning + Details + + + + + %m + Machine ID + The machine ID of the running system, formatted as string. See machine-id5 for more information. + + + %b + Boot ID + The boot ID of the running system, formatted as string. See random4 for more information. + + + %H + Host name + The hostname of the running system. + + + %v + Kernel release + Identical to uname -r output. + + + %% + Escaped % + Single percent sign. + + + +
+ + + + Mode + + The file access mode to use when creating this file or + directory. If omitted or when set to -, the + default is used: 0755 for directories, 0644 for all other file + objects. For z, Z lines, + if omitted or when set to -, the file access + mode will not be modified. This parameter is ignored for + x, r, + R, L, t, + and a lines. + + Optionally, if prefixed with ~, the + access mode is masked based on the already set access bits for + existing file or directories: if the existing file has all + executable bits unset, all executable bits are removed from the + new access mode, too. Similarly, if all read bits are removed + from the old access mode, they will be removed from the new + access mode too, and if all write bits are removed, they will be + removed from the new access mode too. In addition, the + sticky/SUID/SGID bit is removed unless applied to a + directory. This functionality is particularly useful in + conjunction with Z. + + + + UID, GID + + The user and group to use for this file or directory. This + may either be a numeric user/group ID or a user or group + name. If omitted or when set to -, the + default 0 (root) is used. For z and + Z lines, when omitted or when set to + -, the file ownership will not be + modified. These parameters are ignored for x, + r, R, + L, t, and + a lines. + + + + Age + The date field, when set, is used to decide what files to + delete when cleaning. If a file or directory is older than the + current time minus the age field, it is deleted. The field + format is a series of integers each followed by one of the + following suffixes for the respective time units: + s, + m or min, + h, + d, + w, + ms, and + us, + meaning seconds, minutes, hours, days, weeks, + milliseconds, and microseconds, respectively. Full names of the time units can + be used too. + + + If multiple integers and units are specified, the time + values are summed. If an integer is given without a unit, + s is assumed. + + + When the age is set to zero, the files are cleaned + unconditionally. + + The age field only applies to lines starting with + d, D, e, + v, q, + Q, C, x + and X. If omitted or set to + -, no automatic clean-up is done. + + If the age field starts with a tilde character + ~, the clean-up is only applied to files and + directories one level inside the directory specified, but not + the files and directories immediately inside it. + + + + Argument + + For L lines determines the destination + path of the symlink. For c and + b, determines the major/minor of the device + node, with major and minor formatted as integers, separated by + :, e.g. 1:3. For + f, F, and + w, the argument may be used to specify a short string that + is written to the file, suffixed by a newline. For + C, specifies the source file or + directory. For t and T, + determines extended attributes to be set. For + a and A, determines ACL + attributes to be set. For h and + H, determines the file attributes to + set. Ignored for all other lines. + + + + + + Examples + + Create directories with specific mode and ownership + + screen1, + needs two directories created at boot with specific modes and ownership: + + # /usr/lib/tmpfiles.d/screen.conf +d /run/screens 1777 root screen 10d +d /run/uscreens 0755 root screen 10d12h + + + Contents of /run/screens and /run/uscreens will + cleaned up after 10 and 10½ days, respectively. + + + + Create a directory with a SMACK attribute + D /run/cups - - - - +t /run/cups - - - - security.SMACK64=printing user.attr-with-spaces="foo bar" + + + The direcory will be owned by root and have default mode. It's contents are + not subject to time based cleanup, but will be obliterated when + systemd-tmpfiles --remove runs. + + + + Create a directory and prevent its contents from cleanup + + abrt1, + needs a directory created at boot with specific mode and ownership and its content + should be preserved from the automatic cleanup applied to the contents of + /var/tmp: + + # /usr/lib/tmpfiles.d/tmp.conf +d /var/tmp 1777 root root 30d + + + # /usr/lib/tmpfiles.d/abrt.conf +d /var/tmp/abrt 0755 abrt abrt - + + + + + Apply clean up during boot and based on time + + # /usr/lib/tmpfiles.d/dnf.conf +r! /var/cache/dnf/*/*/download_lock.pid +r! /var/cache/dnf/*/*/metadata_lock.pid +r! /var/lib/dnf/rpmdb_lock.pid +e /var/chache/dnf/ - - - 30d + + + The lock files will be removed during boot. Any files and directories in + /var/chache/dnf/ will be removed after they have not been + accessed in 30 days. + + + + + See Also + + systemd1, + systemd-tmpfiles8, + systemd-delta1, + systemd.exec5, + attr5, + getfattr1, + setfattr1, + setfacl1, + getfacl1, + chattr1, + btrfs-subvolume8, + btrfs-qgroup8 + + + + diff --git a/src/grp-initprogs/systemd-update-done/systemd-update-done.service.xml b/src/grp-initprogs/systemd-update-done/systemd-update-done.service.xml new file mode 100644 index 0000000000..a2dad39f01 --- /dev/null +++ b/src/grp-initprogs/systemd-update-done/systemd-update-done.service.xml @@ -0,0 +1,97 @@ + + + + + + + + systemd-update-done.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-update-done.service + 8 + + + + systemd-update-done.service + systemd-update-done + Mark /etc and /var fully updated + + + + systemd-update-done.service + /usr/lib/systemd/systemd-update-done + + + + Description + + systemd-update-done.service is a + service that is invoked as part of the first boot after the vendor + operating system resources in /usr have been + updated. This is useful to implement offline updates of + /usr which might require updates to + /etc or /var on the + following boot. + + systemd-update-done.service updates the + file modification time (mtime) of the stamp files + /etc/.updated and + /var/.updated to the modification time of the + /usr directory, unless the stamp files are + already newer. + + Services that shall run after offline upgrades of + /usr should order themselves before + systemd-update-done.service, and use the + ConditionNeedsUpdate= (see + systemd.unit5) + condition to make sure to run when /etc or + /var are older than /usr + according to the modification times of the files described above. + This requires that updates to /usr are always + followed by an update of the modification time of + /usr, for example by invoking + touch1 + on it. + + + + + See Also + + systemd1, + systemd.unit5, + touch1 + + + + diff --git a/src/grp-initprogs/systemd-update-utmp/systemd-update-utmp.service.xml b/src/grp-initprogs/systemd-update-utmp/systemd-update-utmp.service.xml new file mode 100644 index 0000000000..c8a9cb7c90 --- /dev/null +++ b/src/grp-initprogs/systemd-update-utmp/systemd-update-utmp.service.xml @@ -0,0 +1,76 @@ + + + + + + + + systemd-update-utmp.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-update-utmp.service + 8 + + + + systemd-update-utmp.service + systemd-update-utmp-runlevel.service + systemd-update-utmp + Write audit and utmp updates at bootup, runlevel + changes and shutdown + + + + systemd-update-utmp.service + systemd-update-utmp-runlevel.service + /usr/lib/systemd/systemd-update-utmp + + + + Description + + systemd-update-utmp-runlevel.service is + a service that writes SysV runlevel changes to utmp and wtmp, as + well as the audit logs, as they occur. + systemd-update-utmp.service does the same for + system reboots and shutdown requests. + + + + See Also + + systemd1, + utmp5, + auditd8 + + + + diff --git a/src/grp-initprogs/systemd-user-sessions/systemd-user-sessions.service.xml b/src/grp-initprogs/systemd-user-sessions/systemd-user-sessions.service.xml new file mode 100644 index 0000000000..67aba54119 --- /dev/null +++ b/src/grp-initprogs/systemd-user-sessions/systemd-user-sessions.service.xml @@ -0,0 +1,75 @@ + + + + + + + + systemd-user-sessions.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-user-sessions.service + 8 + + + + systemd-user-sessions.service + systemd-user-sessions + Permit user logins after boot, prohibit user logins at shutdown + + + + systemd-user-sessions.service + /usr/lib/systemd/systemd-user-sessions + + + + Description + + systemd-user-sessions.service is a + service that controls user logins through + pam_nologin8. + After basic system initialization is complete, it removes + /run/nologin, thus permitting logins. Before + system shutdown, it creates /run/nologin, thus + prohibiting further logins. + + + + See Also + + systemd1, + systemd-logind.service8, + pam_nologin8 + + + + diff --git a/src/grp-initprogs/systemd-vconsole-setup/systemd-vconsole-setup.service.xml b/src/grp-initprogs/systemd-vconsole-setup/systemd-vconsole-setup.service.xml new file mode 100644 index 0000000000..ff079761c1 --- /dev/null +++ b/src/grp-initprogs/systemd-vconsole-setup/systemd-vconsole-setup.service.xml @@ -0,0 +1,114 @@ + + + + + + + + systemd-vconsole-setup.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-vconsole-setup.service + 8 + + + + systemd-vconsole-setup.service + systemd-vconsole-setup + Configure the virtual console at boot + + + + systemd-vconsole-setup.service + /usr/lib/systemd/systemd-vconsole-setup + + + + Description + + systemd-vconsole-setup.service is an + early boot service that configures the virtual console font and + console keymap. Internally it calls + loadkeys1 + and + setfont8. + + See + vconsole.conf5 + for information about the configuration files understood by this + service. + + + + + + Kernel Command Line + + A few configuration parameters from + vconsole.conf may be overridden on the kernel + command line: + + + + vconsole.keymap= + vconsole.keymap.toggle= + + Overrides the key mapping table for the + keyboard and the second toggle keymap. + + + + vconsole.font= + vconsole.font.map= + vconsole.font.unimap= + + Configures the console font, the console map, + and the unicode font map. + + + + See + vconsole.conf5 + for information about these settings. + + + + See Also + + systemd1, + vconsole.conf5, + loadkeys1, + setfont8, + systemd-localed.service8 + + + + diff --git a/src/grp-initprogs/systemd-vconsole-setup/vconsole.conf.xml b/src/grp-initprogs/systemd-vconsole-setup/vconsole.conf.xml new file mode 100644 index 0000000000..27196d44e9 --- /dev/null +++ b/src/grp-initprogs/systemd-vconsole-setup/vconsole.conf.xml @@ -0,0 +1,139 @@ + + + + + + + + vconsole.conf + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + vconsole.conf + 5 + + + + vconsole.conf + Configuration file for the virtual console + + + + /etc/vconsole.conf + + + + Description + + The /etc/vconsole.conf file configures + the virtual console, i.e. keyboard mapping and console font. It is + applied at boot by + systemd-vconsole-setup.service8. + + The basic file format of the + vconsole.conf is a newline-separated list of + environment-like shell-compatible variable assignments. It is + possible to source the configuration from shell scripts, however, + beyond mere variable assignments no shell features are supported, + allowing applications to read the file without implementing a + shell compatible execution engine. + + Note that the kernel command line options + vconsole.keymap=, + vconsole.keymap.toggle=, + vconsole.font=, + vconsole.font.map=, + vconsole.font.unimap= may be used + to override the console settings at boot. + + Depending on the operating system other configuration files + might be checked for configuration of the virtual console as well, + however only as fallback. + + + + Options + + The following options are understood: + + + + + KEYMAP= + KEYMAP_TOGGLE= + + Configures the key mapping table for the + keyboard. KEYMAP= defaults to + us if not set. The + KEYMAP_TOGGLE= can be used to configure a + second toggle keymap and is by default + unset. + + + + FONT= + FONT_MAP= + FONT_UNIMAP= + + Configures the console font, the console map + and the unicode font map. + + + + + + + Example + + + German keyboard and console + + /etc/vconsole.conf: + + KEYMAP=de-latin1 +FONT=eurlatgr + + + + + + See Also + + systemd1, + systemd-vconsole-setup.service8, + loadkeys1, + setfont8, + locale.conf5, + systemd-localed.service8 + + + + diff --git a/src/grp-journal/grp-remote/systemd-journal-gatewayd/systemd-journal-gatewayd.service.xml b/src/grp-journal/grp-remote/systemd-journal-gatewayd/systemd-journal-gatewayd.service.xml new file mode 100644 index 0000000000..9ed85c3950 --- /dev/null +++ b/src/grp-journal/grp-remote/systemd-journal-gatewayd/systemd-journal-gatewayd.service.xml @@ -0,0 +1,302 @@ + + + + + + + + + systemd-journal-gatewayd.service + systemd + + + + Developer + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + systemd-journal-gatewayd.service + 8 + + + + systemd-journal-gatewayd.service + systemd-journal-gatewayd.socket + systemd-journal-gatewayd + HTTP server for journal events + + + + systemd-journal-gatewayd.service + systemd-journal-gatewayd.socket + + /usr/lib/systemd/systemd-journal-gatewayd + OPTIONS + + + + + Description + + systemd-journal-gatewayd serves journal + events over the network. Clients must connect using + HTTP. The server listens on port 19531 by default. + If is specified, the server expects + HTTPS connections. + + The program is started by + systemd1 + and expects to receive a single socket. Use + systemctl start systemd-journal-gatewayd.socket to start + the service, and systemctl enable systemd-journal-gatewayd.socket + to have it started on boot. + + + + Options + + The following options are understood: + + + + + + Specify the path to a file containing a server + certificate in PEM format. This option switches + systemd-journal-gatewayd into HTTPS mode + and must be used together with + . + + + + + + Specify the path to a file containing a server + key in PEM format corresponding to the certificate specified + with . + + + + + + + + + Supported URLs + + The following URLs are recognized: + + + + /browse + + Interactive browsing. + + + + /entries[?option1&option2=value...] + + Retrieval of events in various formats. + + The part of the HTTP header + determines the format. Supported values are described below. + + + The part of the HTTP header + determines the range of events returned. Supported values are + described below. + + + GET parameters can be used to modify what events are + returned. Supported parameters are described below. + + + + + /machine + + Return a JSON structure describing the machine. + + Example: + { "machine_id" : "8cf7ed9d451ea194b77a9f118f3dc446", + "boot_id" : "3d3c9efaf556496a9b04259ee35df7f7", + "hostname" : "fedora", + "os_pretty_name" : "Fedora 19 (Rawhide)", + "virtualization" : "kvm", + ...} + + + + + + /fields/FIELD_NAME + + Return a list of values of this field present in the logs. + + + + + + + Accept header + + + + + + Recognized formats: + + + + text/plain + + The default. Plaintext syslog-like output, + one line per journal entry + (like journalctl --output short). + + + + + application/json + + Entries are formatted as JSON data structures, + one per line + (like journalctl --output json). + See Journal + JSON Format for more information. + + + + + text/event-stream + + Entries are formatted as JSON data structures, + wrapped in a format suitable for + Server-Sent Events + (like journalctl --output json-sse). + + + + + + application/vnd.fdo.journal + + Entries are serialized into a binary (but + mostly text-based) stream suitable for backups and network + transfer + (like journalctl --output export). + See Journal + Export Format for more information. + + + + + + + Range header + + + + + + where + is a cursor string, + is an integer, + is an unsigned integer. + + + Range defaults to all available events. + + + + URL GET parameters + + Following parameters can be used as part of the URL: + + + + follow + + wait for new events + (like journalctl --follow, except that + the number of events returned is not limited). + + + + + discrete + + Test that the specified cursor refers to an + entry in the journal. Returns just this entry. + + + + + boot + + Limit events to the current boot of the system + (like journalctl --this-boot). + + + + KEY=match + + Match journal fields. See + systemd.journal-fields7. + + + + + + + Examples + Retrieve events from this boot from local journal + in Journal + Export Format: + curl --silent -H'Accept: application/vnd.fdo.journal' \ + 'http://localhost:19531/entries?boot' + + + Listen for core dumps: + curl 'http://localhost:19531/entries?follow&MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1' + + + + See Also + + systemd1, + journalctl1, + systemd-journald.service8, + systemd.journal-fields7, + + + + diff --git a/src/grp-journal/grp-remote/systemd-journal-remote/journal-remote.conf.xml b/src/grp-journal/grp-remote/systemd-journal-remote/journal-remote.conf.xml new file mode 100644 index 0000000000..2d345963d9 --- /dev/null +++ b/src/grp-journal/grp-remote/systemd-journal-remote/journal-remote.conf.xml @@ -0,0 +1,121 @@ + + + + + + + + journal-remote.conf + systemd + + + + Developer + Chris + Morgan + chmorgan@gmail.com + + + + + + journal-remote.conf + 5 + + + + journal-remote.conf + journal-remote.conf.d + Journal remote service configuration files + + + + /etc/systemd/journal-remote.conf + /etc/systemd/journald.conf.d/*.conf + /run/systemd/journald.conf.d/*.conf + /usr/lib/systemd/journald.conf.d/*.conf + + + + Description + + These files configure various parameters of the systemd-remote-journal + application, + systemd-journal-remote8. + + + + + + Options + + All options are configured in the + [Remote] section: + + + + Seal= + + Periodically sign the data in the journal using Forward Secure Sealing. + + + + + + SplitMode= + + One of host or none. + + + + + ServerKeyFile= + + SSL key in PEM format. + + + + ServerCertificateFile= + + SSL CA certificate in PEM format. + + + + TrustedCertificateFile= + + SSL CA certificate. + + + + + + + + See Also + + systemd-journal-remote8, + systemd1, + systemd-journald.service8 + + + + diff --git a/src/grp-journal/grp-remote/systemd-journal-remote/systemd-journal-remote.xml b/src/grp-journal/grp-remote/systemd-journal-remote/systemd-journal-remote.xml new file mode 100644 index 0000000000..3899f175d4 --- /dev/null +++ b/src/grp-journal/grp-remote/systemd-journal-remote/systemd-journal-remote.xml @@ -0,0 +1,325 @@ + + + + + + + + + systemd-journal-remote + systemd + + + + Developer + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + systemd-journal-remote + 8 + + + + systemd-journal-remote + Receive journal messages over the network + + + + + systemd-journal-remote + OPTIONS + -o/--output=DIR|FILE + SOURCES + + + + + Description + + + systemd-journal-remote is a command to + receive serialized journal events and store them to the journal. + Input streams are in the + + Journal Export Format + , + i.e. like the output from + journalctl --output=export. For transport over + the network, this serialized stream is usually carried over an + HTTPS connection. + + + + + Sources + + + Sources can be either "active" + (systemd-journal-remote requests and pulls + the data), or "passive" + (systemd-journal-remote waits for a + connection and then receives events pushed by the other side). + + + + systemd-journal-remote can read more than one + event stream at a time. They will be interleaved in the output + file. In case of "active" connections, each "source" is one + stream, and in case of "passive" connections, each connection can + result in a separate stream. Sockets can be configured in + "accept" mode (i.e. only one connection), or "listen" mode (i.e. + multiple connections, each resulting in a stream). + + + + When there are no more connections, and no more can be created + (there are no listening sockets), then + systemd-journal-remote will exit. + + + Active sources can be specified in the following + ways: + + + + When is given as a + positional argument, events will be read from standard input. + Other positional arguments will be treated as filenames + to open and read from. + + + + + + With the + option, + events will be retrieved using HTTP from + ADDRESS. This URL should refer to the + root of a remote + systemd-journal-gatewayd8 + instance (e.g. http://some.host:19531/ or + https://some.host:19531/). + + + + Passive sources can be specified in the following + ways: + + + + + + ADDRESS must be an + address suitable for (cf. + systemd.socket5). + systemd-journal-remote will listen on this + socket for connections. Each connection is expected to be a + stream of journal events. + + + + + + + + ADDRESS must be + either a negative integer, in which case it will be + interpreted as the (negated) file descriptor number, or an + address suitable for (c.f. + systemd.socket5). + In the first case, matching file descriptor must be inherited + through + $LISTEN_FDS/$LISTEN_PID. + In the second case, an HTTP or HTTPS server will be spawned on + this port, respectively for and + . Currently, only POST requests + to /upload with Content-Type: + application/vnd.fdo.journal are supported. + + + + + $LISTEN_FDS + + systemd-journal-remote + supports the + $LISTEN_FDS/$LISTEN_PID + protocol. Open sockets inherited through socket activation + behave like those opened with + described above, unless they are specified as an argument in + + or + + above. In the latter case, an HTTP or HTTPS server will be + spawned using this descriptor and connections must be made + over the HTTP protocol. + + + + + + + + Sinks + + The location of the output journal can be specified + with or . For "active" + sources, this option is required. + + + + + + + Will write to this journal file. The filename + must end with .journal. The file will be + created if it does not exist. If necessary (journal file full, + or corrupted), the file will be renamed following normal + journald rules and a new journal file will be created in its + stead. + + + + + + Will create journal files underneath directory + DIR. The directory must exist. If + necessary (journal files over size, or corrupted), journal + files will be rotated following normal journald rules. Names + of files underneath DIR will be + generated using the rules described below. + + + + If is not used, the output + directory /var/log/journal/remote/ will be + used. In case the output file is not specified, journal files + will be created underneath the selected directory. Files will be + called + remote-hostname.journal, + where the hostname part is the + escaped hostname of the source endpoint of the connection, or the + numerical address if the hostname cannot be determined. + + In case of "active" sources, the output file name must + always be given explicitly. + + + + Options + + The following options are understood: + + + + + + One of none or + host. For the first, only one output + journal file is used. For the latter, a separate output file + is used, based on the hostname of the other endpoint of a + connection. + + In case of "active" sources, the output file name must + always be given explicitly and only none + is allowed. + + + + + + + Compress or not, respectively, the data in the + journal using XZ. + + + + + + + Periodically sign or not, respectively, the + data in the journal using Forward Secure Sealing. + + + + + + + Program to invoke to retrieve data. The journal + event stream must be generated on standard output. + + Examples: + + --getter='curl "-HAccept: application/vnd.fdo.journal" https://some.host:19531/' + + --getter='wget --header="Accept: application/vnd.fdo.journal" -O- https://some.host:19531/' + + + + + + + + + + Examples + Copy local journal events to a different journal directory: + +journalctl -o export | systemd-journal-remote -o /tmp/dir - + + + + Retrieve all available events from a remote + systemd-journal-gatewayd8 + instance and store them in + /var/log/journal/remote/remote-some.host.journal: + +systemd-journal-remote --url http://some.host:19531/ + + + + Retrieve current boot events and wait for new events from a remote + systemd-journal-gatewayd8 + instance, and store them in + /var/log/journal/remote/remote-some.host.journal: + +systemd-journal-remote --url http://some.host:19531/entries?boot&follow + + + + + + See Also + + systemd-journal-upload8, + journalctl1, + systemd-journald.service8, + systemd-journal-gatewayd.service8 + journal-remote.conf5 + + + diff --git a/src/grp-journal/grp-remote/systemd-journal-upload/systemd-journal-upload.xml b/src/grp-journal/grp-remote/systemd-journal-upload/systemd-journal-upload.xml new file mode 100644 index 0000000000..f9723dea89 --- /dev/null +++ b/src/grp-journal/grp-remote/systemd-journal-upload/systemd-journal-upload.xml @@ -0,0 +1,263 @@ + + + + + + + + + systemd-journal-upload + systemd + + + + Developer + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + systemd-journal-upload + 8 + + + + systemd-journal-upload + Send journal messages over the network + + + + + systemd-journal-upload + OPTIONS + -u/--url=URL + SOURCES + + + + + Description + + + systemd-journal-upload will upload journal + entries to the URL specified with . Unless + limited by one of the options specified below, all journal + entries accessible to the user the program is running as will be + uploaded, and then the program will wait and send new entries + as they become available. + + + + + Options + + + + + + + + Upload to the specified + address. URL may specify either + just the hostname or both the protocol and + hostname. https is the default. + + + + + + + + Limit uploaded entries to entries from system + services and the kernel, or to entries from services of + current user. This has the same meaning as + and options + for + journalctl1. If + neither is specified, all accessible entries are uploaded. + + + + + + + + Upload entries interleaved from all available + journals, including other machines. This has the same meaning + as option for + journalctl1. + + + + + + + Takes a directory path as argument. Upload + entries from the specified journal directory + DIR instead of the default runtime + and system journal paths. This has the same meaning as + option for + journalctl1. + + + + + + + Takes a file glob as an argument. Upload + entries from the specified journal files matching + GLOB instead of the default runtime + and system journal paths. May be specified multiple times, in + which case files will be suitably interleaved. This has the same meaning as + option for + journalctl1. + + + + + + + Upload entries from the location in the + journal specified by the passed cursor. This has the same + meaning as option for + journalctl1. + + + + + + Upload entries from the location in the + journal after the location specified by + the this cursor. This has the same meaning as + option for + journalctl1. + + + + + + =PATH + + Upload entries from the location in the + journal after the location specified by + the cursor saved in file at PATH + (/var/lib/systemd/journal-upload/state by default). + After an entry is successfully uploaded, update this file + with the cursor of that entry. + + + + + + + + + + Exit status + + On success, 0 is returned; otherwise, a non-zero + failure code is returned. + + + + Examples + + Setting up certificates for authentication + + Certificates signed by a trusted authority are used to + verify that the server to which messages are uploaded is + legitimate, and vice versa, that the client is trusted. + + A suitable set of certificates can be generated with + openssl: + + openssl req -newkey rsa:2048 -days 3650 -x509 -nodes \ + -out ca.pem -keyout ca.key -subj '/CN=Certificate authority/' + +cat >ca.conf <<EOF +[ ca ] +default_ca = this + +[ this ] +new_certs_dir = . +certificate = ca.pem +database = ./index +private_key = ca.key +serial = ./serial +default_days = 3650 +default_md = default +policy = policy_anything + +[ policy_anything ] +countryName = optional +stateOrProvinceName = optional +localityName = optional +organizationName = optional +organizationalUnitName = optional +commonName = supplied +emailAddress = optional +EOF + +touch index +echo 0001 >serial + +SERVER=server +CLIENT=client + +openssl req -newkey rsa:1024 -nodes -out $SERVER.csr -keyout $SERVER.key -subj "/CN=$SERVER/" +openssl ca -batch -config ca.conf -notext -in $SERVER.csr -out $SERVER.pem + +openssl req -newkey rsa:1024 -nodes -out $CLIENT.csr -keyout $CLIENT.key -subj "/CN=$CLIENT/" +openssl ca -batch -config ca.conf -notext -in $CLIENT.csr -out $CLIENT.pem + + + Generated files ca.pem, + server.pem, and + server.key should be installed on server, + and ca.pem, + client.pem, and + client.key on the client. The location of + those files can be specified using + TrustedCertificateFile=, + ServerCertificateFile=, + ServerKeyFile=, in + /etc/systemd/journal-remote.conf and + /etc/systemd/journal-upload.conf, + respectively. The default locations can be queried by using + systemd-journal-remote --help and + systemd-journal-upload --help. + + + + + See Also + + systemd-journal-remote8, + journalctl1, + systemd-journald.service8, + systemd-journal-gatewayd.service8 + + + diff --git a/src/grp-journal/journalctl/journalctl.xml b/src/grp-journal/journalctl/journalctl.xml new file mode 100644 index 0000000000..3efe6ef62a --- /dev/null +++ b/src/grp-journal/journalctl/journalctl.xml @@ -0,0 +1,914 @@ + + + + + + + + + journalctl + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + journalctl + 1 + + + + journalctl + Query the systemd journal + + + + + journalctl + OPTIONS + MATCHES + + + + + Description + + journalctl may be used to query the + contents of the + systemd1 + journal as written by + systemd-journald.service8. + + If called without parameters, it will show the full + contents of the journal, starting with the oldest entry + collected. + + If one or more match arguments are passed, the output is + filtered accordingly. A match is in the format + FIELD=VALUE, + e.g. _SYSTEMD_UNIT=httpd.service, referring + to the components of a structured journal entry. See + systemd.journal-fields7 + for a list of well-known fields. If multiple matches are + specified matching different fields, the log entries are + filtered by both, i.e. the resulting output will show only + entries matching all the specified matches of this kind. If two + matches apply to the same field, then they are automatically + matched as alternatives, i.e. the resulting output will show + entries matching any of the specified matches for the same + field. Finally, the character + may appear + as a separate word between other terms on the command line. This + causes all matches before and after to be combined in a + disjunction (i.e. logical OR). + + As shortcuts for a few types of field/value matches, file + paths may be specified. If a file path refers to an executable + file, this is equivalent to an _EXE= match + for the canonicalized binary path. Similarly, if a path refers + to a device node then match is added for the kernel name of the + device (_KERNEL_DEVICE=). Also, matches for the + kernel names of all the parent devices are added automatically. + Device node paths are not stable across reboots, therefore match + for the current boot id (_BOOT_ID=) is + always added as well. Note that only the log entries for + the existing device nodes maybe queried by providing path to + the device node. + + Additional constraints may be added using options + , , etc., to + further limit what entries will be shown (logical AND). + + Output is interleaved from all accessible journal files, + whether they are rotated or currently being written, and + regardless of whether they belong to the system itself or are + accessible user journals. + + The set of journal files which will be used can be + modified using the , + , , and + options, see below. + + All users are granted access to their private per-user + journals. However, by default, only root and users who are + members of a few special groups are granted access to the system + journal and the journals of other users. Members of the groups + systemd-journal, adm, and + wheel can read all journal files. Note + that the two latter groups traditionally have additional + privileges specified by the distribution. Members of the + wheel group can often perform administrative + tasks. + + The output is paged through less by + default, and long lines are "truncated" to screen width. The + hidden part can be viewed by using the left-arrow and + right-arrow keys. Paging can be disabled; see the + option and the "Environment" section + below. + + When outputting to a tty, lines are colored according to + priority: lines of level ERROR and higher are colored red; lines + of level NOTICE and higher are highlighted; other lines are + displayed normally. + + + + Options + + The following options are understood: + + + + + + + + Ellipsize fields when they do not fit in + available columns. The default is to show full fields, + allowing them to wrap or be truncated by the pager, if one + is used. + + The old options + / are not useful + anymore, except to undo . + + + + + + + + Show all fields in full, even if they + include unprintable characters or are very + long. + + + + + + + Show only the most recent journal entries, + and continuously print new entries as they are appended to + the journal. + + + + + + + Immediately jump to the end of the journal + inside the implied pager tool. This implies + to guarantee that the pager will not + buffer logs of unbounded size. This may be overridden with + an explicit with some other numeric + value, while will disable this cap. + Note that this option is only supported for the + less1 + pager. + + + + + + + Show the most recent journal events and + limit the number of events shown. If + is used, this option is + implied. The argument is a positive integer or + all to disable line limiting. The default + value is 10 if no argument is given. + + + + + + Show all stored output lines, even in follow + mode. Undoes the effect of . + + + + + + + + Reverse output so that the newest entries + are displayed first. + + + + + + + Controls the formatting of the journal + entries that are shown. Takes one of the following + options: + + + + + + + is the default and generates an output that is + mostly identical to the formatting of classic syslog + files, showing one line per journal entry. + + + + + + + + + is very similar, but shows ISO 8601 wallclock + timestamps. + + + + + + + + + is very similar, but shows timestamps with full + microsecond precision. + + + + + + + + + is very similar, but shows monotonic timestamps + instead of wallclock timestamps. + + + + + + + + + is very similar, but shows seconds passed since January 1st 1970 UTC instead of wallclock + timestamps ("UNIX time"). The time is shown with microsecond accuracy. + + + + + + + + + shows the full-structured entry items with all + fields. + + + + + + + + + serializes the journal into a binary (but mostly + text-based) stream suitable for backups and network + transfer (see + Journal Export Format + for more information). + + + + + + + + + formats entries as JSON data structures, one per + line (see + Journal JSON Format + for more information). + + + + + + + + + formats entries as JSON data structures, but + formats them in multiple lines in order to make them + more readable by humans. + + + + + + + + + formats entries as JSON data structures, but wraps + them in a format suitable for + Server-Sent Events. + + + + + + + + + + generates a very terse output, only showing the + actual message of each journal entry with no metadata, + not even a timestamp. + + + + + + + + + + Express time in Coordinated Universal Time + (UTC). + + + + + + Don't show the hostname field of log messages originating from the local host. This switch only + has an effect on the family of output modes (see above). + + + + + + + Augment log lines with explanation texts from + the message catalog. This will add explanatory help texts to + log messages in the output where this is available. These + short help texts will explain the context of an error or log + event, possible solutions, as well as pointers to support + forums, developer documentation, and any other relevant + manuals. Note that help texts are not available for all + messages, but only for selected ones. For more information on + the message catalog, please refer to the + Message Catalog Developer Documentation. + + Note: when attaching journalctl + output to bug reports, please do not use + . + + + + + + + + Suppresses all info messages + (i.e. "-- Logs begin at ...", "-- Reboot --"), + any warning messages regarding + inaccessible system journals when run as a normal + user. + + + + + + + Show entries interleaved from all available + journals, including remote ones. + + + + + + + Show messages from a specific boot. This will + add a match for _BOOT_ID=. + + The argument may be empty, in which case logs for the + current boot will be shown. + + If the boot ID is omitted, a positive + offset will look up the boots + starting from the beginning of the journal, and an + equal-or-less-than zero offset will + look up boots starting from the end of the journal. Thus, + 1 means the first boot found in the + journal in chronological order, 2 the + second and so on; while -0 is the last + boot, -1 the boot before last, and so + on. An empty offset is equivalent + to specifying -0, except when the current + boot is not the last boot (e.g. because + was specified to look at logs + from a different machine). + + If the 32-character ID is + specified, it may optionally be followed by + offset which identifies the boot + relative to the one given by boot + ID. Negative values mean earlier + boots and positive values mean later boots. If + offset is not specified, a value of + zero is assumed, and the logs for the boot given by + ID are shown. + + + + + + + Show a tabular list of boot numbers (relative to + the current boot), their IDs, and the timestamps of the first + and last message pertaining to the boot. + + + + + + + Show only kernel messages. This implies + and adds the match + _TRANSPORT=kernel. + + + + + + + Show messages for the specified syslog + identifier + SYSLOG_IDENTIFIER. + + This parameter can be specified multiple + times. + + + + + + + Show messages for the specified systemd unit + UNIT (such as a service unit), or + for any of the units matched by + PATTERN. If a pattern is + specified, a list of unit names found in the journal is + compared with the specified pattern and all that match are + used. For each unit name, a match is added for messages from + the unit + (_SYSTEMD_UNIT=UNIT), + along with additional matches for messages from systemd and + messages about coredumps for the specified unit. + + This parameter can be specified multiple times. + + + + + + + Show messages for the specified user session + unit. This will add a match for messages from the unit + (_SYSTEMD_USER_UNIT= and + _UID=) and additional matches for messages + from session systemd and messages about coredumps for the + specified unit. + + This parameter can be specified multiple times. + + + + + + + + Filter output by message priorities or + priority ranges. Takes either a single numeric or textual log + level (i.e. between 0/emerg and + 7/debug), or a range of numeric/text log + levels in the form FROM..TO. The log levels are the usual + syslog log levels as documented in + syslog3, + i.e. emerg (0), + alert (1), crit (2), + err (3), warning (4), + notice (5), info (6), + debug (7). If a single log level is + specified, all messages with this log level or a lower (hence + more important) log level are shown. If a range is specified, + all messages within the range are shown, including both the + start and the end value of the range. This will add + PRIORITY= matches for the specified + priorities. + + + + + + + Start showing entries from the location in the + journal specified by the passed cursor. + + + + + + Start showing entries from the location in the + journal after the location specified by + the passed cursor. The cursor is shown when the + option is used. + + + + + + + The cursor is shown after the last entry after + two dashes: + -- cursor: s=0639... + The format of the cursor is private + and subject to change. + + + + + + + + + Start showing entries on or newer than the + specified date, or on or older than the specified date, + respectively. Date specifications should be of the format + 2012-10-30 18:17:16. If the time part is + omitted, 00:00:00 is assumed. If only the + seconds component is omitted, :00 is + assumed. If the date component is omitted, the current day is + assumed. Alternatively the strings + yesterday, today, + tomorrow are understood, which refer to + 00:00:00 of the day before the current day, the current day, + or the day after the current day, + respectively. now refers to the current + time. Finally, relative times may be specified, prefixed with + - or +, referring to + times before or after the current time, respectively. For complete + time and date specification, see + systemd.time7. + + + + + + + + + Print all possible data values the specified + field can take in all entries of the journal. + + + + + + + Print all field names currently used in all entries of the journal. + + + + + + + Show messages from system services and the + kernel (with ). Show messages from + service of current user (with ). If + neither is specified, show all messages that the user can see. + + + + + + + + Show messages from a running, local + container. Specify a container name to connect to. + + + + + + + + Takes a directory path as argument. If + specified, journalctl will operate on the specified journal + directory DIR instead of the + default runtime and system journal paths. + + + + + + Takes a file glob as an argument. If + specified, journalctl will operate on the specified journal + files matching GLOB instead of the + default runtime and system journal paths. May be specified + multiple times, in which case files will be suitably + interleaved. + + + + + + Takes a directory path as an argument. If + specified, journalctl will operate on catalog file hierarchy + underneath the specified directory instead of the root + directory (e.g. will create + ROOT/var/lib/systemd/catalog/database). + + + + + + + Instead of showing journal contents, generate + a new 128-bit ID suitable for identifying messages. This is + intended for usage by developers who need a new identifier for + a new message they introduce and want to make + recognizable. This will print the new ID in three different + formats which can be copied into source code or similar. + + + + + + + Instead of showing journal contents, show + internal header information of the journal fields + accessed. + + + + + + Shows the current disk usage of all journal + files. This shows the sum of the disk usage of all archived + and active journal files. + + + + + + + + Removes archived journal files until the disk + space they use falls below the specified size (specified with + the usual K, M, + G and T suffixes), or all + archived journal files contain no data older than the specified + timespan (specified with the usual s, + m, h, + days, months, + weeks and years suffixes), + or no more than the specified number of separate journal files + remain. Note that running has + only an indirect effect on the output shown by + , as the latter includes active + journal files, while the vacuuming operation only operates + on archived journal files. Similarly, + might not actually reduce the + number of journal files to below the specified number, as it + will not remove active journal + files. , + and + may be combined in a single + invocation to enforce any combination of a size, a time and a + number of files limit on the archived journal + files. Specifying any of these three parameters as zero is + equivalent to not enforcing the specific limit, and is thus + redundant. + + + + + + List the contents of the message catalog as a + table of message IDs, plus their short description strings. + + + If any 128-bit-IDs are + specified, only those entries are shown. + + + + + + + Show the contents of the message catalog, with + entries separated by a line consisting of two dashes and the + ID (the format is the same as .catalog + files). + + If any 128-bit-IDs are + specified, only those entries are shown. + + + + + + + Update the message catalog index. This command + needs to be executed each time new catalog files are + installed, removed, or updated to rebuild the binary catalog + index. + + + + + + Instead of showing journal contents, generate + a new key pair for Forward Secure Sealing (FSS). This will + generate a sealing key and a verification key. The sealing key + is stored in the journal data directory and shall remain on + the host. The verification key should be stored + externally. Refer to the option in + journald.conf5 + for information on Forward Secure Sealing and for a link to a + refereed scholarly paper detailing the cryptographic theory it + is based on. + + + + + + When is passed + and Forward Secure Sealing (FSS) has already been configured, + recreate FSS keys. + + + + + + Specifies the change interval for the sealing + key when generating an FSS key pair with + . Shorter intervals increase CPU + consumption but shorten the time range of undetectable journal + alterations. Defaults to 15min. + + + + + + Check the journal file for internal + consistency. If the file has been generated with FSS enabled and + the FSS verification key has been specified with + , authenticity of the journal file + is verified. + + + + + + Specifies the FSS verification key to use for + the operation. + + + + + + Asks the journal daemon to write all yet + unwritten journal data to the backing file system and + synchronize all journals. This call does not return until the + synchronization operation is complete. This command guarantees + that any log messages written before its invocation are safely + stored on disk at the time it returns. + + + + + + Asks the journal daemon to flush any log data + stored in /run/log/journal into + /var/log/journal, if persistent storage + is enabled. This call does not return until the operation is + complete. Note that this call is idempotent: the data is only + flushed from /run/log/journal into + /var/log/journal once during system + runtime, and this command exits cleanly without executing any + operation if this has already has happened. This command + effectively guarantees that all data is flushed to + /var/log/journal at the time it + returns. + + + + + + Asks the journal daemon to rotate journal + files. This call does not return until the rotation operation + is complete. + + + + + + + + + + Exit status + + On success, 0 is returned; otherwise, a non-zero failure + code is returned. + + + + + + Examples + + Without arguments, all collected logs are shown + unfiltered: + + journalctl + + With one match specified, all entries with a field matching + the expression are shown: + + journalctl _SYSTEMD_UNIT=avahi-daemon.service + + If two different fields are matched, only entries matching + both expressions at the same time are shown: + + journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + + If two matches refer to the same field, all entries matching + either expression are shown: + + journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service + + If the separator + is used, two + expressions may be combined in a logical OR. The following will + show all messages from the Avahi service process with the PID + 28097 plus all messages from the D-Bus service (from any of its + processes): + + journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service + + Show all logs generated by the D-Bus executable: + + journalctl /usr/bin/dbus-daemon + + Show all kernel logs from previous boot: + + journalctl -k -b -1 + + Show a live log display from a system service + apache.service: + + journalctl -f -u apache + + + + + See Also + + systemd1, + systemd-journald.service8, + systemctl1, + coredumpctl1, + systemd.journal-fields7, + journald.conf5, + systemd.time7 + + + diff --git a/src/grp-journal/systemd-cat/systemd-cat.xml b/src/grp-journal/systemd-cat/systemd-cat.xml new file mode 100644 index 0000000000..160db9fb5c --- /dev/null +++ b/src/grp-journal/systemd-cat/systemd-cat.xml @@ -0,0 +1,178 @@ + + + + + + + + + systemd-cat + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-cat + 1 + + + + systemd-cat + Connect a pipeline or program's output with the journal + + + + + systemd-cat OPTIONS COMMAND ARGUMENTS + + + systemd-cat OPTIONS + + + + + Description + + systemd-cat may be used to connect the + standard input and output of a process to the journal, or as a + filter tool in a shell pipeline to pass the output the previous + pipeline element generates to the journal. + + If no parameter is passed, systemd-cat + will write everything it reads from standard input (stdin) to the + journal. + + If parameters are passed, they are executed as command line + with standard output (stdout) and standard error output (stderr) + connected to the journal, so that all it writes is stored in the + journal. + + + + Options + + The following options are understood: + + + + + + + + + + Specify a short string that is used to + identify the logging tool. If not specified, no identification + string is written to the journal. + + + + + + + Specify the default priority level for the + logged messages. Pass one of + emerg, + alert, + crit, + err, + warning, + notice, + info, + debug, or a + value between 0 and 7 (corresponding to the same named + levels). These priority values are the same as defined by + syslog3. + Defaults to info. Note that this simply + controls the default, individual lines may be logged with + different levels if they are prefixed accordingly. For details, + see below. + + + + + + Controls whether lines read are parsed for + syslog priority level prefixes. If enabled (the default), a + line prefixed with a priority prefix such as + <5> is logged at priority 5 + (notice), and similar for the other + priority levels. Takes a boolean argument. + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + Examples + + + Invoke a program + + This calls /bin/ls + with standard output and error connected to the journal: + + # systemd-cat ls + + + + Usage in a shell pipeline + + This builds a shell pipeline also invoking + /bin/ls and writes the output it generates + to the journal: + + # ls | systemd-cat + + + Even though the two examples have very similar effects the + first is preferable since only one process is running at a time, + and both stdout and stderr are captured while in the second + example, only stdout is captured. + + + + See Also + + systemd1, + systemctl1, + logger1 + + + + diff --git a/src/grp-journal/systemd-journald/journald.conf.xml b/src/grp-journal/systemd-journald/journald.conf.xml new file mode 100644 index 0000000000..3964cd6bc5 --- /dev/null +++ b/src/grp-journal/systemd-journald/journald.conf.xml @@ -0,0 +1,410 @@ + + + + + + + + journald.conf + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + journald.conf + 5 + + + + journald.conf + journald.conf.d + Journal service configuration files + + + + /etc/systemd/journald.conf + /etc/systemd/journald.conf.d/*.conf + /run/systemd/journald.conf.d/*.conf + /usr/lib/systemd/journald.conf.d/*.conf + + + + Description + + These files configure various parameters of the systemd + journal service, + systemd-journald.service8. + + + + + + + Options + + All options are configured in the + [Journal] section: + + + + + Storage= + + Controls where to store journal data. One of + volatile, + persistent, + auto and + none. If + volatile, journal + log data will be stored only in memory, i.e. below the + /run/log/journal hierarchy (which is + created if needed). If persistent, data + will be stored preferably on disk, i.e. below the + /var/log/journal hierarchy (which is + created if needed), with a fallback to + /run/log/journal (which is created if + needed), during early boot and if the disk is not writable. + auto is similar to + persistent but the directory + /var/log/journal is not created if + needed, so that its existence controls where log data goes. + none turns off all storage, all log data + received will be dropped. Forwarding to other targets, such as + the console, the kernel log buffer, or a syslog socket will + still work however. Defaults to + auto. + + + + Compress= + + Takes a boolean value. If enabled (the + default), data objects that shall be stored in the journal and + are larger than a certain threshold are compressed before they + are written to the file system. + + + + Seal= + + Takes a boolean value. If enabled (the + default), and a sealing key is available (as created by + journalctl1's + command), Forward Secure Sealing + (FSS) for all persistent journal files is enabled. FSS is + based on Seekable Sequential Key + Generators by G. A. Marson and B. Poettering + (doi:10.1007/978-3-642-40203-6_7) and may be used to protect + journal files from unnoticed alteration. + + + + SplitMode= + + Controls whether to split up journal files per + user. One of uid, login + and none. If uid, all + users will get each their own journal files regardless of + whether they possess a login session or not, however system + users will log into the system journal. If + login, actually logged-in users will get + each their own journal files, but users without login session + and system users will log into the system journal. If + none, journal files are not split up by + user and all messages are instead stored in the single system + journal. Note that splitting up journal files by user is only + available for journals stored persistently. If journals are + stored on volatile storage (see above), only a single journal + file for all user IDs is kept. Defaults to + uid. + + + + RateLimitIntervalSec= + RateLimitBurst= + + Configures the rate limiting that is applied + to all messages generated on the system. If, in the time + interval defined by RateLimitIntervalSec=, + more messages than specified in + RateLimitBurst= are logged by a service, + all further messages within the interval are dropped until the + interval is over. A message about the number of dropped + messages is generated. This rate limiting is applied + per-service, so that two services which log do not interfere + with each other's limits. Defaults to 1000 messages in 30s. + The time specification for + RateLimitIntervalSec= may be specified in the + following units: s, min, + h, ms, + us. To turn off any kind of rate limiting, + set either value to 0. + + + + SystemMaxUse= + SystemKeepFree= + SystemMaxFileSize= + SystemMaxFiles= + RuntimeMaxUse= + RuntimeKeepFree= + RuntimeMaxFileSize= + RuntimeMaxFiles= + + Enforce size limits on the journal files + stored. The options prefixed with System + apply to the journal files when stored on a persistent file + system, more specifically + /var/log/journal. The options prefixed + with Runtime apply to the journal files + when stored on a volatile in-memory file system, more + specifically /run/log/journal. The former + is used only when /var is mounted, + writable, and the directory + /var/log/journal exists. Otherwise, only + the latter applies. Note that this means that during early + boot and if the administrator disabled persistent logging, + only the latter options apply, while the former apply if + persistent logging is enabled and the system is fully booted + up. journalctl and + systemd-journald ignore all files with + names not ending with .journal or + .journal~, so only such files, located in + the appropriate directories, are taken into account when + calculating current disk usage. + + SystemMaxUse= and + RuntimeMaxUse= control how much disk space + the journal may use up at most. + SystemKeepFree= and + RuntimeKeepFree= control how much disk + space systemd-journald shall leave free for other uses. + systemd-journald will respect both limits + and use the smaller of the two values. + + The first pair defaults to 10% and the second to 15% of + the size of the respective file system, but each value is + capped to 4G. If the file system is nearly full and either + SystemKeepFree= or + RuntimeKeepFree= are violated when + systemd-journald is started, the limit will be raised to the + percentage that is actually free. This means that if there was + enough free space before and journal files were created, and + subsequently something else causes the file system to fill up, + journald will stop using more space, but it will not be + removing existing files to reduce the footprint again, + either. + + SystemMaxFileSize= and + RuntimeMaxFileSize= control how large + individual journal files may grow at most. This influences + the granularity in which disk space is made available through + rotation, i.e. deletion of historic data. Defaults to one + eighth of the values configured with + SystemMaxUse= and + RuntimeMaxUse=, so that usually seven + rotated journal files are kept as history. + + Specify values in bytes or use K, M, G, T, P, E as + units for the specified sizes (equal to 1024, 1024², ... bytes). + Note that size limits are enforced synchronously when journal + files are extended, and no explicit rotation step triggered by + time is needed. + + SystemMaxFiles= and + RuntimeMaxFiles= control how many + individual journal files to keep at most. Note that only + archived files are deleted to reduce the number of files until + this limit is reached; active files will stay around. This + means that, in effect, there might still be more journal files + around in total than this limit after a vacuuming operation is + complete. This setting defaults to 100. + + + + MaxFileSec= + + The maximum time to store entries in a single + journal file before rotating to the next one. Normally, + time-based rotation should not be required as size-based + rotation with options such as + SystemMaxFileSize= should be sufficient to + ensure that journal files do not grow without bounds. However, + to ensure that not too much data is lost at once when old + journal files are deleted, it might make sense to change this + value from the default of one month. Set to 0 to turn off this + feature. This setting takes time values which may be suffixed + with the units year, + month, week, + day, h or + m to override the default time unit of + seconds. + + + + MaxRetentionSec= + + The maximum time to store journal entries. + This controls whether journal files containing entries older + then the specified time span are deleted. Normally, time-based + deletion of old journal files should not be required as + size-based deletion with options such as + SystemMaxUse= should be sufficient to + ensure that journal files do not grow without bounds. However, + to enforce data retention policies, it might make sense to + change this value from the default of 0 (which turns off this + feature). This setting also takes time values which may be + suffixed with the units year, + month, week, + day, h or + m to override the default time unit of + seconds. + + + + + SyncIntervalSec= + + The timeout before synchronizing journal files + to disk. After syncing, journal files are placed in the + OFFLINE state. Note that syncing is unconditionally done + immediately after a log message of priority CRIT, ALERT or + EMERG has been logged. This setting hence applies only to + messages of the levels ERR, WARNING, NOTICE, INFO, DEBUG. The + default timeout is 5 minutes. + + + + ForwardToSyslog= + ForwardToKMsg= + ForwardToConsole= + ForwardToWall= + + Control whether log messages received by the + journal daemon shall be forwarded to a traditional syslog + daemon, to the kernel log buffer (kmsg), to the system + console, or sent as wall messages to all logged-in users. + These options take boolean arguments. If forwarding to syslog + is enabled but nothing reads messages from the socket, + forwarding to syslog has no effect. By default, only + forwarding to wall is enabled. These settings may be + overridden at boot time with the kernel command line options + systemd.journald.forward_to_syslog=, + systemd.journald.forward_to_kmsg=, + systemd.journald.forward_to_console=, and + systemd.journald.forward_to_wall=. When + forwarding to the console, the TTY to log to can be changed + with TTYPath=, described + below. + + + + MaxLevelStore= + MaxLevelSyslog= + MaxLevelKMsg= + MaxLevelConsole= + MaxLevelWall= + + Controls the maximum log level of messages + that are stored on disk, forwarded to syslog, kmsg, the + console or wall (if that is enabled, see above). As argument, + takes one of + emerg, + alert, + crit, + err, + warning, + notice, + info, + debug, + or integer values in the range of 0–7 (corresponding to the + same levels). Messages equal or below the log level specified + are stored/forwarded, messages above are dropped. Defaults to + debug for MaxLevelStore= + and MaxLevelSyslog=, to ensure that the all + messages are written to disk and forwarded to syslog. Defaults + to + notice for MaxLevelKMsg=, + info for MaxLevelConsole=, + and emerg for + MaxLevelWall=. + + + + TTYPath= + + Change the console TTY to use if + ForwardToConsole=yes is used. Defaults to + /dev/console. + + + + + + + + Forwarding to traditional syslog daemons + + + Journal events can be transferred to a different logging daemon + in two different ways. With the first method, messages are + immediately forwarded to a socket + (/run/systemd/journal/syslog), where the + traditional syslog daemon can read them. This method is + controlled by the ForwardToSyslog= option. With a + second method, a syslog daemon behaves like a normal journal + client, and reads messages from the journal files, similarly to + journalctl1. + With this, messages do not have to be read immediately, + which allows a logging daemon which is only started late in boot + to access all messages since the start of the system. In + addition, full structured meta-data is available to it. This + method of course is available only if the messages are stored in + a journal file at all. So it will not work if + Storage=none is set. It should be noted that + usually the second method is used by syslog + daemons, so the Storage= option, and not the + ForwardToSyslog= option, is relevant for them. + + + + + See Also + + systemd1, + systemd-journald.service8, + journalctl1, + systemd.journal-fields7, + systemd-system.conf5 + + + + diff --git a/src/grp-journal/systemd-journald/systemd-journald.service.xml b/src/grp-journal/systemd-journald/systemd-journald.service.xml new file mode 100644 index 0000000000..2810638bc2 --- /dev/null +++ b/src/grp-journal/systemd-journald/systemd-journald.service.xml @@ -0,0 +1,276 @@ + + + + + + + + + systemd-journald.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-journald.service + 8 + + + + systemd-journald.service + systemd-journald.socket + systemd-journald-dev-log.socket + systemd-journald-audit.socket + systemd-journald + Journal service + + + + systemd-journald.service + systemd-journald.socket + systemd-journald-dev-log.socket + systemd-journald-audit.socket + /usr/lib/systemd/systemd-journald + + + + Description + + systemd-journald is a system service + that collects and stores logging data. It creates and maintains + structured, indexed journals based on logging information that is + received from a variety of sources: + + + Kernel log messages, via kmsg + + Simple system log messages, via the libc + syslog3 + call + + Structured system log messages via the native + Journal API, see + sd_journal_print4 + + Standard output and standard error of system + services + + Audit records, via the audit + subsystem + + + The daemon will implicitly collect numerous metadata fields + for each log messages in a secure and unfakeable way. See + systemd.journal-fields7 + for more information about the collected metadata. + + + Log data collected by the journal is primarily text-based + but can also include binary data where necessary. All objects + stored in the journal can be up to 2^64-1 bytes in size. + + By default, the journal stores log data in + /run/log/journal/. Since + /run/ is volatile, log data is lost at + reboot. To make the data persistent, it is sufficient to create + /var/log/journal/ where + systemd-journald will then store the + data: + + mkdir -p /var/log/journal +systemd-tmpfiles --create --prefix /var/log/journal + + See + journald.conf5 + for information about the configuration of this service. + + + + Signals + + + + SIGUSR1 + + Request that journal data from + /run/ is flushed to + /var/ in order to make it persistent (if + this is enabled). This must be used after + /var/ is mounted, as otherwise log data + from /run is never flushed to + /var regardless of the configuration. The + journalctl --flush command uses this signal + to request flushing of the journal files, and then waits for + the operation to complete. See + journalctl1 + for details. + + + + SIGUSR2 + + Request immediate rotation of the journal + files. The journalctl --rotate command uses + this signal to request journal file + rotation. + + + + SIGRTMIN+1 + + Request that all unwritten log data is written + to disk. The journalctl --sync command uses + this signal to trigger journal synchronization, and then waits + for the operation to complete. + + + + + + Kernel Command Line + + A few configuration parameters from + journald.conf may be overridden on the kernel + command line: + + + + systemd.journald.forward_to_syslog= + systemd.journald.forward_to_kmsg= + systemd.journald.forward_to_console= + systemd.journald.forward_to_wall= + + Enables/disables forwarding of collected log + messages to syslog, the kernel log buffer, the system console + or wall. + + + See + journald.conf5 + for information about these settings. + + + + + + + + Access Control + + Journal files are, by default, owned and readable by the + systemd-journal system group but are not + writable. Adding a user to this group thus enables her/him to read + the journal files. + + By default, each logged in user will get her/his own set of + journal files in /var/log/journal/. These + files will not be owned by the user, however, in order to avoid + that the user can write to them directly. Instead, file system + ACLs are used to ensure the user gets read access only. + + Additional users and groups may be granted access to journal + files via file system access control lists (ACL). Distributions + and administrators may choose to grant read access to all members + of the wheel and adm system + groups with a command such as the following: + + # setfacl -Rnm g:wheel:rx,d:g:wheel:rx,g:adm:rx,d:g:adm:rx /var/log/journal/ + + Note that this command will update the ACLs both for + existing journal files and for future journal files created in the + /var/log/journal/ directory. + + + + Files + + + + /etc/systemd/journald.conf + + Configure + systemd-journald + behavior. See + journald.conf5. + + + + + /run/log/journal/machine-id/*.journal + /run/log/journal/machine-id/*.journal~ + /var/log/journal/machine-id/*.journal + /var/log/journal/machine-id/*.journal~ + + systemd-journald writes + entries to files in + /run/log/journal/machine-id/ + or + /var/log/journal/machine-id/ + with the .journal suffix. If the daemon is + stopped uncleanly, or if the files are found to be corrupted, + they are renamed using the .journal~ + suffix, and systemd-journald starts writing + to a new file. /run is used when + /var/log/journal is not available, or + when is set in the + journald.conf5 + configuration file. + + + + /dev/kmsg + /dev/log + /run/systemd/journal/dev-log + /run/systemd/journal/socket + /run/systemd/journal/stdout + + Sockets and other paths that + systemd-journald will listen on that are + visible in the file system. In addition to these, journald can + listen for audit events using netlink. + + + + + + See Also + + systemd1, + journalctl1, + journald.conf5, + systemd.journal-fields7, + sd-journal3, + systemd-coredump8, + setfacl1, + sd_journal_print4, + pydoc systemd.journal + + + + diff --git a/src/grp-locale/locale.conf.xml b/src/grp-locale/locale.conf.xml new file mode 100644 index 0000000000..2fe731113a --- /dev/null +++ b/src/grp-locale/locale.conf.xml @@ -0,0 +1,152 @@ + + + + + + + + locale.conf + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + locale.conf + 5 + + + + locale.conf + Configuration file for locale settings + + + + /etc/locale.conf + + + + Description + + The /etc/locale.conf file configures + system-wide locale settings. It is read at early boot by + systemd1. + + The basic file format of locale.conf is + a newline-separated list of environment-like shell-compatible + variable assignments. It is possible to source the configuration + from shell scripts, however, beyond mere variable assignments, no + shell features are supported, allowing applications to read the + file without implementing a shell compatible execution + engine. + + Note that the kernel command line options + locale.LANG=, + locale.LANGUAGE=, + locale.LC_CTYPE=, + locale.LC_NUMERIC=, + locale.LC_TIME=, + locale.LC_COLLATE=, + locale.LC_MONETARY=, + locale.LC_MESSAGES=, + locale.LC_PAPER=, + locale.LC_NAME=, + locale.LC_ADDRESS=, + locale.LC_TELEPHONE=, + locale.LC_MEASUREMENT=, + locale.LC_IDENTIFICATION= may be + used to override the locale settings at boot. + + The locale settings configured in + /etc/locale.conf are system-wide and are + inherited by every service or user, unless overridden or unset by + individual programs or individual users. + + Depending on the operating system, other configuration files + might be checked for locale configuration as well, however only as + fallback. + + localectl1 + may be used to alter the settings in this file during runtime from + the command line. Use + systemd-firstboot1 + to initialize them on mounted (but not booted) system + images. + + + + Options + + The following locale settings may be set using + /etc/locale.conf: + LANG=, + LANGUAGE=, + LC_CTYPE=, + LC_NUMERIC=, + LC_TIME=, + LC_COLLATE=, + LC_MONETARY=, + LC_MESSAGES=, + LC_PAPER=, + LC_NAME=, + LC_ADDRESS=, + LC_TELEPHONE=, + LC_MEASUREMENT=, + LC_IDENTIFICATION=. + Note that LC_ALL may not be configured in this + file. For details about the meaning and semantics of these + settings, refer to + locale7. + + + + Example + + + German locale with English messages + + /etc/locale.conf: + + LANG=de_DE.UTF-8 +LC_MESSAGES=en_US.UTF-8 + + + + + + See Also + + systemd1, + locale7, + localectl1, + systemd-localed.service8, + systemd-firstboot1 + + + + diff --git a/src/grp-locale/localectl/localectl.xml b/src/grp-locale/localectl/localectl.xml new file mode 100644 index 0000000000..7def047f62 --- /dev/null +++ b/src/grp-locale/localectl/localectl.xml @@ -0,0 +1,221 @@ + + + + + + + + + localectl + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + localectl + 1 + + + + localectl + Control the system locale and keyboard layout settings + + + + + localectl + OPTIONS + COMMAND + + + + + Description + + localectl may be used to query and change + the system locale and keyboard layout settings. + + The system locale controls the language settings of system + services and of the UI before the user logs in, such as the + display manager, as well as the default for users after + login. + + The keyboard settings control the keyboard layout used on + the text console and of the graphical UI before the user logs in, + such as the display manager, as well as the default for users + after login. + + Use + systemd-firstboot1 + to initialize the system locale for mounted (but not booted) + system images. + + + + Options + + The following options are understood: + + + + + + Do not query the user for authentication for + privileged operations. + + + + + + If set-keymap or + set-x11-keymap is invoked and this option + is passed, then the keymap will not be converted from the + console to X11, or X11 to console, + respectively. + + + + + + + + + + The following commands are understood: + + + + status + + Show current settings of the system locale and + keyboard mapping. + + + + set-locale LOCALE... + + Set the system locale. This takes one or more + assignments such as "LANG=de_DE.utf8", + "LC_MESSAGES=en_GB.utf8", and so on. See + locale7 + for details on the available settings and their meanings. Use + list-locales for a list of available + locales (see below). + + + + list-locales + + List available locales useful for + configuration with + set-locale. + + + + set-keymap MAP [TOGGLEMAP] + + Set the system keyboard mapping for the + console and X11. This takes a mapping name (such as "de" or + "us"), and possibly a second one to define a toggle keyboard + mapping. Unless is passed, the + selected setting is also applied as the default system + keyboard mapping of X11, after converting it to the closest + matching X11 keyboard mapping. Use + list-keymaps for a list of available + keyboard mappings (see below). + + + + list-keymaps + + List available keyboard mappings for the + console, useful for configuration with + set-keymap. + + + + set-x11-keymap LAYOUT [MODEL [VARIANT [OPTIONS]]] + + Set the system default keyboard mapping for + X11 and the virtual console. This takes a keyboard mapping + name (such as de or us), + and possibly a model, variant, and options, see + kbd4 + for details. Unless is passed, + the selected setting is also applied as the system console + keyboard mapping, after converting it to the closest matching + console keyboard mapping. + + + + list-x11-keymap-models + list-x11-keymap-layouts + list-x11-keymap-variants [LAYOUT] + list-x11-keymap-options + + List available X11 keymap models, layouts, + variants and options, useful for configuration with + set-keymap. The command + list-x11-keymap-variants optionally takes a + layout parameter to limit the output to the variants suitable + for the specific layout. + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + + + See Also + + systemd1, + locale7, + locale.conf5, + vconsole.conf5, + loadkeys1, + kbd4, + + The XKB Configuration Guide + , + systemctl1, + systemd-localed.service8, + systemd-firstboot1 + + + + diff --git a/src/grp-locale/systemd-localed/systemd-localed.service.xml b/src/grp-locale/systemd-localed/systemd-localed.service.xml new file mode 100644 index 0000000000..06aa78c0e4 --- /dev/null +++ b/src/grp-locale/systemd-localed/systemd-localed.service.xml @@ -0,0 +1,87 @@ + + + + + + + + + systemd-localed.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-localed.service + 8 + + + + systemd-localed.service + systemd-localed + Locale bus mechanism + + + + systemd-localed.service + /usr/lib/systemd/systemd-localed + + + + Description + + systemd-localed is a system service + that may be used as mechanism to change the system locale + settings, as well as the console key mapping and default X11 key + mapping. systemd-localed is automatically + activated on request and terminates itself when it is + unused. + + The tool + localectl1 + is a command line client to this service. + + See the + developer documentation for information about the APIs + systemd-localed provides. + + + + See Also + + systemd1, + locale.conf5, + vconsole.conf5, + localectl1, + loadkeys1 + + + + diff --git a/src/grp-login/loginctl/loginctl.xml b/src/grp-login/loginctl/loginctl.xml new file mode 100644 index 0000000000..fb51740503 --- /dev/null +++ b/src/grp-login/loginctl/loginctl.xml @@ -0,0 +1,459 @@ + + + + + + + + + loginctl + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + loginctl + 1 + + + + loginctl + Control the systemd login manager + + + + + loginctl + OPTIONS + COMMAND + NAME + + + + + Description + + loginctl may be used to introspect and + control the state of the + systemd1 + login manager + systemd-logind.service8. + + + + Options + + The following options are understood: + + + + + + Do not query the user for authentication for + privileged operations. + + + + + + + When showing session/user/seat properties, + limit display to certain properties as specified as argument. + If not specified, all set properties are shown. The argument + should be a property name, such as + Sessions. If specified more than once, all + properties with the specified names are + shown. + + + + + + + When printing properties with show, + only print the value, and skip the property name and + =. + + + + + + + + When showing session/user/seat properties, + show all properties regardless of whether they are set or + not. + + + + + + + Do not ellipsize process tree entries. + + + + + + + When used with + kill-session, choose which processes to + kill. Must be one of , or + to select whether to kill only the leader + process of the session or all processes of the session. If + omitted, defaults to . + + + + + + + When used with kill-session + or kill-user, choose which signal to send + to selected processes. Must be one of the well known signal + specifiers, such as SIGTERM, + SIGINT or SIGSTOP. + If omitted, defaults to + SIGTERM. + + + + + + + When used with user-status + and session-status, controls the number of + journal lines to show, counting from the most recent ones. + Takes a positive integer argument. Defaults to 10. + + + + + + + + When used with user-status + and session-status, controls the formatting + of the journal entries that are shown. For the available + choices, see + journalctl1. + Defaults to short. + + + + + + + + + + + + + + Commands + + The following commands are understood: + + Session Commands + + + list-sessions + + List current sessions. + + + + session-status ID... + + Show terse runtime status information about + one or more sessions, followed by the most recent log data + from the journal. Takes one or more session identifiers as + parameters. If no session identifiers are passed, the status of + the caller's session is shown. This function is intended to + generate human-readable output. If you are looking for + computer-parsable output, use show-session + instead. + + + + show-session ID... + + Show properties of one or more sessions or the + manager itself. If no argument is specified, properties of the + manager will be shown. If a session ID is specified, + properties of the session are shown. By default, empty + properties are suppressed. Use to show + those too. To select specific properties to show, use + . This command is intended to be + used whenever computer-parsable output is required. Use + session-status if you are looking for + formatted human-readable output. + + + + activate ID + + Activate a session. This brings a session into + the foreground if another session is currently in the + foreground on the respective seat. Takes a session identifier + as argument. If no argument is specified, the session of the + caller is put into foreground. + + + + lock-session ID... + unlock-session ID... + + Activates/deactivates the screen lock on one + or more sessions, if the session supports it. Takes one or + more session identifiers as arguments. If no argument is + specified, the session of the caller is locked/unlocked. + + + + + lock-sessions + unlock-sessions + + Activates/deactivates the screen lock on all + current sessions supporting it. + + + + terminate-session ID... + + Terminates a session. This kills all processes + of the session and deallocates all resources attached to the + session. + + + + kill-session ID... + + Send a signal to one or more processes of the + session. Use to select which + process to kill. Use to select the + signal to send. + + + + User Commands + + list-users + + List currently logged in users. + + + + + user-status USER... + + Show terse runtime status information about + one or more logged in users, followed by the most recent log + data from the journal. Takes one or more user names or numeric + user IDs as parameters. If no parameters are passed, the status + of the caller's user is shown. This function is intended to + generate human-readable output. If you are looking for + computer-parsable output, use show-user + instead. Users may be specified by their usernames or numeric + user IDs. + + + + show-user USER... + + Show properties of one or more users or the + manager itself. If no argument is specified, properties of the + manager will be shown. If a user is specified, properties of + the user are shown. By default, empty properties are + suppressed. Use to show those too. To + select specific properties to show, use + . This command is intended to be + used whenever computer-parsable output is required. Use + user-status if you are looking for + formatted human-readable output. + + + + enable-linger USER... + disable-linger USER... + + Enable/disable user lingering for one or more + users. If enabled for a specific user, a user manager is + spawned for the user at boot and kept around after logouts. + This allows users who are not logged in to run long-running + services. Takes one or more user names or numeric UIDs as + argument. If no argument is specified, enables/disables + lingering for the user of the session of the caller. + + See also KillUserProcesses= setting in + logind.conf5. + + + + + terminate-user USER... + + Terminates all sessions of a user. This kills + all processes of all sessions of the user and deallocates all + runtime resources attached to the user. + + + + kill-user USER... + + Send a signal to all processes of a user. Use + to select the signal to send. + + + + + Seat Commands + + list-seats + + List currently available seats on the local + system. + + + + seat-status NAME... + + Show terse runtime status information about + one or more seats. Takes one or more seat names as parameters. + If no seat names are passed the status of the caller's + session's seat is shown. This function is intended to generate + human-readable output. If you are looking for + computer-parsable output, use show-seat + instead. + + + + show-seat NAME... + + Show properties of one or more seats or the + manager itself. If no argument is specified, properties of the + manager will be shown. If a seat is specified, properties of + the seat are shown. By default, empty properties are + suppressed. Use to show those too. To + select specific properties to show, use + . This command is intended to be + used whenever computer-parsable output is required. Use + seat-status if you are looking for + formatted human-readable output. + + + + attach NAME DEVICE... + + Persistently attach one or more devices to a + seat. The devices should be specified via device paths in the + /sys file system. To create a new seat, + attach at least one graphics card to a previously unused seat + name. Seat names may consist only of a–z, A–Z, 0–9, + - and _ and must be + prefixed with seat. To drop assignment of a + device to a specific seat, just reassign it to a different + seat, or use flush-devices. + + + + + flush-devices + + Removes all device assignments previously + created with attach. After this call, only + automatically generated seats will remain, and all seat + hardware is assigned to them. + + + + terminate-seat NAME... + + Terminates all sessions on a seat. This kills + all processes of all sessions on the seat and deallocates all + runtime resources attached to them. + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + Examples + + + Querying user status + + $ loginctl user-status +fatima (1005) + Since: Sat 2016-04-09 14:23:31 EDT; 54min ago + State: active + Sessions: 5 *3 + Unit: user-1005.slice + ├─user@1005.service + ... + ├─session-3.scope + ... + └─session-5.scope + ├─3473 login -- fatima + └─3515 -zsh + +Apr 09 14:40:30 laptop login[2325]: pam_unix(login:session): + session opened for user fatima by LOGIN(uid=0) +Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima + + + There are two sessions, 3 and 5. Session 3 is a graphical session, + marked with a star. The tree of processing including the two corresponding + scope units and the user manager unit are shown. + + + + + + + See Also + + systemd1, + systemctl1, + systemd-logind.service8, + logind.conf5 + + + + diff --git a/src/grp-login/pam_systemd/pam_systemd.xml b/src/grp-login/pam_systemd/pam_systemd.xml new file mode 100644 index 0000000000..ddda81bc90 --- /dev/null +++ b/src/grp-login/pam_systemd/pam_systemd.xml @@ -0,0 +1,296 @@ + + + + + + + + + pam_systemd + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + pam_systemd + 8 + + + + pam_systemd + Register user sessions in the systemd login manager + + + + pam_systemd.so + + + + Description + + pam_systemd registers user sessions with + the systemd login manager + systemd-logind.service8, + and hence the systemd control group hierarchy. + + On login, this module ensures the following: + + + If it does not exist yet, the user runtime + directory /run/user/$USER is created and + its ownership changed to the user that is logging + in. + + The $XDG_SESSION_ID + environment variable is initialized. If auditing is available + and pam_loginuid.so was run before this + module (which is highly recommended), the variable is + initialized from the auditing session id + (/proc/self/sessionid). Otherwise, an + independent session counter is used. + + A new systemd scope unit is created for the + session. If this is the first concurrent session of the user, an + implicit slice below user.slice is + automatically created and the scope placed into it. An instance + of the system service user@.service, which + runs the systemd user manager instance, is started. + + + + On logout, this module ensures the following: + + + If enabled in + logind.conf + 5, all processes of the + session are terminated. If the last concurrent session of a user + ends, the user's systemd instance will be terminated too, and so + will the user's slice unit. + + If the last concurrent session of a user ends, + the $XDG_RUNTIME_DIR directory and all its + contents are removed, too. + + + If the system was not booted up with systemd as init system, + this module does nothing and immediately returns + PAM_SUCCESS. + + + + + Options + + The following options are understood: + + + + + + + Takes a string argument which sets the session + class. The XDG_SESSION_CLASS environmental variable takes + precedence. One of + user, + greeter, + lock-screen or + background. See + sd_session_get_class3 + for details about the session class. + + + + + + Takes a string argument which sets the session + type. The XDG_SESSION_TYPE environmental variable takes + precedence. One of + unspecified, + tty, + x11, + wayland or + mir. See + sd_session_get_type3 + for details about the session type. + + + + + + Takes an optional + boolean argument. If yes or without + the argument, the module will log + debugging information as it + operates. + + + + + + Module Types Provided + + Only is provided. + + + + Environment + + The following environment variables are set for the + processes of the user's session: + + + + $XDG_SESSION_ID + + A session identifier, suitable to be used in + filenames. The string itself should be considered opaque, + although often it is just the audit session ID as reported by + /proc/self/sessionid. Each ID will be + assigned only once during machine uptime. It may hence be used + to uniquely label files or other resources of this + session. + + + + $XDG_RUNTIME_DIR + + Path to a user-private user-writable directory + that is bound to the user login time on the machine. It is + automatically created the first time a user logs in and + removed on the user's final logout. If a user logs in twice at + the same time, both sessions will see the same + $XDG_RUNTIME_DIR and the same contents. If + a user logs in once, then logs out again, and logs in again, + the directory contents will have been lost in between, but + applications should not rely on this behavior and must be able + to deal with stale files. To store session-private data in + this directory, the user should include the value of + $XDG_SESSION_ID in the filename. This + directory shall be used for runtime file system objects such + as AF_UNIX sockets, FIFOs, PID files and + similar. It is guaranteed that this directory is local and + offers the greatest possible file system feature set the + operating system provides. For further details, see the XDG + Base Directory Specification. + + + + + The following environment variables are read by the module + and may be used by the PAM service to pass metadata to the + module: + + + + $XDG_SESSION_TYPE + + The session type. This may be used instead of + on the module parameter line, and is + usually preferred. + + + + $XDG_SESSION_CLASS + + The session class. This may be used instead of + on the module parameter line, and is + usually preferred. + + + + $XDG_SESSION_DESKTOP + + A single, short identifier string for the + desktop environment. This may be used to indicate the session + desktop used, where this applies and if this information is + available. For example: GNOME, or + KDE. It is recommended to use the same + identifiers and capitalization as for + $XDG_CURRENT_DESKTOP, as defined by the + Desktop + Entry Specification. (However, note that + $XDG_SESSION_DESKTOP only takes a single + item, and not a colon-separated list like + $XDG_CURRENT_DESKTOP.) See + sd_session_get_desktop3 + for more details. + + + + $XDG_SEAT + + The seat name the session shall be registered + for, if any. + + + + $XDG_VTNR + + The VT number the session shall be registered + for, if any. (Only applies to seats with a VT available, such + as seat0) + + + + + + + Example + + #%PAM-1.0 +auth required pam_unix.so +auth required pam_nologin.so +account required pam_unix.so +password required pam_unix.so +session required pam_unix.so +session required pam_loginuid.so +session required pam_systemd.so + + + + See Also + + systemd1, + systemd-logind.service8, + logind.conf5, + loginctl1, + pam.conf5, + pam.d5, + pam8, + pam_loginuid8, + systemd.scope5, + systemd.slice5, + systemd.service5 + + + + diff --git a/src/grp-login/systemd-inhibit/systemd-inhibit.xml b/src/grp-login/systemd-inhibit/systemd-inhibit.xml new file mode 100644 index 0000000000..9d85908f97 --- /dev/null +++ b/src/grp-login/systemd-inhibit/systemd-inhibit.xml @@ -0,0 +1,177 @@ + + + + + + + + + systemd-inhibit + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-inhibit + 1 + + + + systemd-inhibit + Execute a program with an inhibition lock taken + + + + + systemd-inhibit OPTIONS COMMAND ARGUMENTS + + + systemd-inhibit OPTIONS --list + + + + + Description + + systemd-inhibit may be used to execute a + program with a shutdown, sleep or idle inhibitor lock taken. The + lock will be acquired before the specified command line is + executed and released afterwards. + + Inhibitor locks may be used to block or delay system sleep + and shutdown requests from the user, as well as automatic idle + handling of the OS. This is useful to avoid system suspends while + an optical disc is being recorded, or similar operations that + should not be interrupted. + + For more information see the Inhibitor + Lock Developer Documentation. + + + + Options + + The following options are understood: + + + + + + Takes a colon-separated list of one or more + operations to inhibit: + shutdown, + sleep, + idle, + handle-power-key, + handle-suspend-key, + handle-hibernate-key, + handle-lid-switch, + for inhibiting reboot/power-off/halt/kexec, + suspending/hibernating, the automatic idle detection, or the + low-level handling of the power/sleep key and the lid switch, + respectively. If omitted, defaults to + idle:sleep:shutdown. + + + + + + Takes a short, human-readable descriptive + string for the program taking the lock. If not passed, + defaults to the command line string. + + + + + + Takes a short, human-readable descriptive + string for the reason for taking the lock. Defaults to + "Unknown reason". + + + + + + Takes either block or + delay and describes how the lock is + applied. If block is used (the default), + the lock prohibits any of the requested operations without + time limit, and only privileged users may override it. If + delay is used, the lock can only delay the + requested operations for a limited time. If the time elapses, + the lock is ignored and the operation executed. The time limit + may be specified in + logind.conf5. + Note that delay is only available for + sleep and + shutdown. + + + + + + Lists all active inhibition locks instead of + acquiring one. + + + + + + + + + + Exit status + + Returns the exit status of the executed program. + + + + Example + + # systemd-inhibit wodim foobar.iso + + This burns the ISO image + foobar.iso on a CD using + wodim1, + and inhibits system sleeping, shutdown and idle while + doing so. + + + + See Also + + systemd1, + logind.conf5 + + + + diff --git a/src/grp-login/systemd-logind/logind.conf.xml b/src/grp-login/systemd-logind/logind.conf.xml new file mode 100644 index 0000000000..fe92277a1f --- /dev/null +++ b/src/grp-login/systemd-logind/logind.conf.xml @@ -0,0 +1,349 @@ + + + + + + + + logind.conf + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + logind.conf + 5 + + + + logind.conf + logind.conf.d + Login manager configuration files + + + + /etc/systemd/logind.conf + /etc/systemd/logind.conf.d/*.conf + /run/systemd/logind.conf.d/*.conf + /usr/lib/systemd/logind.conf.d/*.conf + + + + Description + + These files configure various parameters of the systemd + login manager, + systemd-logind.service8. + + + + + + + Options + + All options are configured in the + [Login] section: + + + + + NAutoVTs= + + Takes a positive integer. Configures how many + virtual terminals (VTs) to allocate by default that, when + switched to and are previously unused, + autovt services are automatically spawned + on. These services are instantiated from the template unit + autovt@.service for the respective VT TTY + name, for example, autovt@tty4.service. + By default, autovt@.service is linked to + getty@.service. In other words, login + prompts are started dynamically as the user switches to unused + virtual terminals. Hence, this parameter controls how many + login gettys are available on the VTs. If a + VT is already used by some other subsystem (for example, a + graphical login), this kind of activation will not be + attempted. Note that the VT configured in + ReserveVT= is always subject to this kind + of activation, even if it is not one of the VTs configured + with the NAutoVTs= directive. Defaults to + 6. When set to 0, automatic spawning of + autovt services is + disabled. + + + + ReserveVT= + + Takes a positive integer. Identifies one + virtual terminal that shall unconditionally be reserved for + autovt@.service activation (see above). + The VT selected with this option will be marked busy + unconditionally, so that no other subsystem will allocate it. + This functionality is useful to ensure that, regardless of how + many VTs are allocated by other subsystems, one login + getty is always available. Defaults to 6 + (in other words, there will always be a + getty available on Alt-F6.). When set to 0, + VT reservation is disabled. + + + + KillUserProcesses= + + Takes a boolean argument. Configures whether the processes of a + user should be killed when the user logs out. If true, the scope unit + corresponding to the session and all processes inside that scope will be + terminated. If false, the scope is "abandoned", see + systemd.scope5, + and processes are not killed. Defaults to yes, + but see the options KillOnlyUsers= and + KillExcludeUsers= below. + + In addition to session processes, user process may run under the user + manager unit user@.service. Depending on the linger + settings, this may allow users to run processes independent of their login + sessions. See the description of enable-linger in + loginctl1. + + + Note that setting KillUserProcesses=yes + will break tools like + screen1 + and + tmux1, + unless they are moved out of the session scope. See example in + systemd-run1. + + + + + KillOnlyUsers= + KillExcludeUsers= + + These settings take space-separated lists of usernames that override + the KillUserProcesses= setting. A user name may be added to + KillExcludeUsers= to exclude the processes in the session scopes of + that user from being killed even if KillUserProcesses=yes is set. If + KillExcludeUsers= is not set, the root user is + excluded by default. KillExcludeUsers= may be set to an empty value + to override this default. If a user is not excluded, KillOnlyUsers= + is checked next. If this setting is specified, only the session scopes of those users + will be killed. Otherwise, users are subject to the + KillUserProcesses=yes setting. + + + + IdleAction= + + Configures the action to take when the system + is idle. Takes one of + ignore, + poweroff, + reboot, + halt, + kexec, + suspend, + hibernate, + hybrid-sleep, and + lock. + Defaults to ignore. + + Note that this requires that user sessions correctly + report the idle status to the system. The system will execute + the action after all sessions report that they are idle, no + idle inhibitor lock is active, and subsequently, the time + configured with IdleActionSec= (see below) + has expired. + + + + + IdleActionSec= + + Configures the delay after which the action + configured in IdleAction= (see above) is + taken after the system is idle. + + + + InhibitDelayMaxSec= + + Specifies the maximum time a system shutdown + or sleep request is delayed due to an inhibitor lock of type + delay being active before the inhibitor is + ignored and the operation executes anyway. Defaults to + 5. + + + + HandlePowerKey= + HandleSuspendKey= + HandleHibernateKey= + HandleLidSwitch= + HandleLidSwitchDocked= + + Controls whether logind shall handle the + system power and sleep keys and the lid switch to trigger + actions such as system power-off or suspend. Can be one of + ignore, + poweroff, + reboot, + halt, + kexec, + suspend, + hibernate, + hybrid-sleep, and + lock. + If ignore, logind will never handle these + keys. If lock, all running sessions will be + screen-locked; otherwise, the specified action will be taken + in the respective event. Only input devices with the + power-switch udev tag will be watched for + key/lid switch events. HandlePowerKey= + defaults to poweroff. + HandleSuspendKey= and + HandleLidSwitch= default to + suspend. + HandleLidSwitchDocked= defaults to + ignore. + HandleHibernateKey= defaults to + hibernate. If the system is inserted in a + docking station, or if more than one display is connected, the + action specified by HandleLidSwitchDocked= + occurs; otherwise the HandleLidSwitch= + action occurs. + + + + PowerKeyIgnoreInhibited= + SuspendKeyIgnoreInhibited= + HibernateKeyIgnoreInhibited= + LidSwitchIgnoreInhibited= + + Controls whether actions triggered by the + power and sleep keys and the lid switch are subject to + inhibitor locks. These settings take boolean arguments. If + no, the inhibitor locks taken by + applications in order to block the requested operation are + respected. If yes, the requested operation + is executed in any case. + PowerKeyIgnoreInhibited=, + SuspendKeyIgnoreInhibited= and + HibernateKeyIgnoreInhibited= default to + no. + LidSwitchIgnoreInhibited= defaults to + yes. This means that the lid switch does + not respect suspend blockers by default, but the power and + sleep keys do. + + + + HoldoffTimeoutSec= + + Specifies the timeout after system startup or + system resume in which systemd will hold off on reacting to + lid events. This is required for the system to properly + detect any hotplugged devices so systemd can ignore lid events + if external monitors, or docks, are connected. If set to 0, + systemd will always react immediately, possibly before the + kernel fully probed all hotplugged devices. This is safe, as + long as you do not care for systemd to account for devices + that have been plugged or unplugged while the system was off. + Defaults to 30s. + + + + RuntimeDirectorySize= + + Sets the size limit on the + $XDG_RUNTIME_DIR runtime directory for each + user who logs in. Takes a size in bytes, optionally suffixed + with the usual K, G, M, and T suffixes, to the base 1024 + (IEC). Alternatively, a numerical percentage suffixed by + % may be specified, which sets the size + limit relative to the amount of physical RAM. Defaults to 10%. + Note that this size is a safety limit only. As each runtime + directory is a tmpfs file system, it will only consume as much + memory as is needed. + + + + InhibitorsMax= + + Controls the maximum number of concurrent inhibitors to permit. Defaults to 8192 + (8K). + + + + SessionsMax= + + Controls the maximum number of concurrent user sessions to manage. Defaults to 8192 + (8K). Depending on how the pam_systemd.so module is included in the PAM stack + configuration, further login sessions will either be refused, or permitted but not tracked by + systemd-logind. + + + + UserTasksMax= + + Sets the maximum number of OS tasks each user + may run concurrently. This controls the + TasksMax= setting of the per-user slice + unit, see + systemd.resource-control5 + for details. Defaults to 12288 (12K). + + + + RemoveIPC= + + Controls whether System V and POSIX IPC objects belonging to the user shall be removed when the + user fully logs out. Takes a boolean argument. If enabled, the user may not consume IPC resources after the + last of the user's sessions terminated. This covers System V semaphores, shared memory and message queues, as + well as POSIX shared memory and message queues. Note that IPC objects of the root user and other system users + are excluded from the effect of this setting. Defaults to yes. + + + + + + + See Also + + systemd1, + systemd-logind.service8, + loginctl1, + systemd-system.conf5 + + + + diff --git a/src/grp-login/systemd-logind/systemd-logind.service.xml b/src/grp-login/systemd-logind/systemd-logind.service.xml new file mode 100644 index 0000000000..5733e42cd1 --- /dev/null +++ b/src/grp-login/systemd-logind/systemd-logind.service.xml @@ -0,0 +1,121 @@ + + + + + + + + + systemd-logind.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-logind.service + 8 + + + + systemd-logind.service + systemd-logind + Login manager + + + + systemd-logind.service + /usr/lib/systemd/systemd-logind + + + + Description + + systemd-logind is a system service that + manages user logins. It is responsible for: + + + Keeping track of users and sessions, their + processes and their idle state + + Providing PolicyKit-based access for users to + operations such as system shutdown or sleep + + Implementing a shutdown/sleep inhibition logic + for applications + + Handling of power/sleep hardware + keys + + Multi-seat management + + Session switch management + + Device access management for + users + + Automatic spawning of text logins (gettys) on + virtual console activation and user runtime directory + management + + + User sessions are registered in logind via the + pam_systemd8 + PAM module. + + See + logind.conf5 + for information about the configuration of this service. + + See Multi-Seat + on Linux for an introduction into basic concepts of logind + such as users, sessions and seats. + + See the + logind D-Bus API Documentation for information about the + APIs systemd-logind provides. + + For more information on the inhibition logic see the Inhibitor + Lock Developer Documentation. + + + + See Also + + systemd1, + systemd-user-sessions.service8, + loginctl1, + logind.conf5, + pam_systemd8 + + + + diff --git a/src/grp-machine/grp-import/systemd-importd/systemd-importd.service.xml b/src/grp-machine/grp-import/systemd-importd/systemd-importd.service.xml new file mode 100644 index 0000000000..8fdced475c --- /dev/null +++ b/src/grp-machine/grp-import/systemd-importd/systemd-importd.service.xml @@ -0,0 +1,82 @@ + + + + + + + + + systemd-importd.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-importd.service + 8 + + + + systemd-importd.service + systemd-importd + VM and container image import and export service + + + + systemd-importd.service + /usr/lib/systemd/systemd-importd + + + + Description + + systemd-importd is a system service that allows importing, exporting and downloading of + system images suitable for running as VM or containers. It is a companion service for + systemd-machined.service8, and provides the implementation for + machinectl1's + pull-raw, pull-tar, import-raw, + import-tar, export-raw, and export-tar commands. + + See the + + importd D-Bus API Documentation for information about the + APIs systemd-importd provides. + + + + See Also + + systemd1, + machinectl1, + systemd-machined.service8, + systemd-nspawn1 + + + + diff --git a/src/grp-machine/machinectl/machinectl.xml b/src/grp-machine/machinectl/machinectl.xml new file mode 100644 index 0000000000..4b7f9a0391 --- /dev/null +++ b/src/grp-machine/machinectl/machinectl.xml @@ -0,0 +1,1022 @@ + + + + + + + + + machinectl + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + machinectl + 1 + + + + machinectl + Control the systemd machine manager + + + + + machinectl + OPTIONS + COMMAND + NAME + + + + + Description + + machinectl may be used to introspect and + control the state of the + systemd1 + virtual machine and container registration manager + systemd-machined.service8. + + machinectl may be used to execute + operations on machines and images. Machines in this sense are + considered running instances of: + + + Virtual Machines (VMs) that virtualize hardware + to run full operating system (OS) instances (including their kernels) + in a virtualized environment on top of the host OS. + + Containers that share the hardware and + OS kernel with the host OS, in order to run + OS userspace instances on top the host OS. + + The host system itself + + + Machines are identified by names that follow the same rules + as UNIX and DNS host names, for details, see below. Machines are + instantiated from disk or file system images that frequently — but not + necessarily — carry the same name as machines running from + them. Images in this sense are considered: + + + Directory trees containing an OS, including its + top-level directories /usr, + /etc, and so on. + + btrfs subvolumes containing OS trees, similar to + normal directory trees. + + Binary "raw" disk images containing MBR or GPT + partition tables and Linux file system partitions. + + The file system tree of the host OS itself. + + + + + + Options + + The following options are understood: + + + + + + + When showing machine or image properties, + limit the output to certain properties as specified by the + argument. If not specified, all set properties are shown. The + argument should be a property name, such as + Name. If specified more than once, all + properties with the specified names are + shown. + + + + + + + When showing machine or image properties, show + all properties regardless of whether they are set or + not. + + When listing VM or container images, do not suppress + images beginning in a dot character + (.). + + When cleaning VM or container images, remove all images, not just hidden ones. + + + + + + When printing properties with show, only print the value, + and skip the property name and =. + + + + + + + Do not ellipsize process tree entries. + + + + + + + Do not query the user for authentication for + privileged operations. + + + + + + When used with kill, choose + which processes to kill. Must be one of + , or to select + whether to kill only the leader process of the machine or all + processes of the machine. If omitted, defaults to + . + + + + + + + When used with kill, choose + which signal to send to selected processes. Must be one of the + well-known signal specifiers, such as + SIGTERM, SIGINT or + SIGSTOP. If omitted, defaults to + SIGTERM. + + + + + + When used with the shell + command, chooses the user ID to open the interactive shell + session as. If this switch is not specified, defaults to + root. Note that this switch is not + supported for the login command (see + below). + + + + + + + When used with the shell command, sets an environment + variable to pass to the executed shell. Takes an environment variable name and value, + separated by =. This switch may be used multiple times to set multiple + environment variables. Note that this switch is not supported for the + login command (see below). + + + + + + When used with bind, creates + the destination directory before applying the bind + mount. + + + + + + When used with bind, applies + a read-only bind mount. + + When used with clone, import-raw or import-tar a + read-only container or VM image is created. + + + + + + + When used with status, + controls the number of journal lines to show, counting from + the most recent ones. Takes a positive integer argument. + Defaults to 10. + + + + + + + + When used with status, + controls the formatting of the journal entries that are shown. + For the available choices, see + journalctl1. + Defaults to short. + + + + + + When downloading a container or VM image, + specify whether the image shall be verified before it is made + available. Takes one of no, + checksum and signature. + If no, no verification is done. If + checksum is specified, the download is + checked for integrity after the transfer is complete, but no + signatures are verified. If signature is + specified, the checksum is verified and the image's signature + is checked against a local keyring of trustable vendors. It is + strongly recommended to set this option to + signature if the server and protocol + support this. Defaults to + signature. + + + + + + When downloading a container or VM image, and + a local copy by the specified local machine name already + exists, delete it first and replace it by the newly downloaded + image. + + + + + + When used with the + or commands, specifies the + compression format to use for the resulting file. Takes one of + uncompressed, xz, + gzip, bzip2. By default, + the format is determined automatically from the image file + name passed. + + + + + + + + + + + + + + Commands + + The following commands are understood: + + Machine Commands + + + list + + List currently running (online) virtual + machines and containers. To enumerate machine images that can + be started, use list-images (see + below). Note that this command hides the special + .host machine by default. Use the + switch to show it. + + + + status NAME... + + Show runtime status information about + one or more virtual machines and containers, followed by the + most recent log data from the journal. This function is + intended to generate human-readable output. If you are looking + for computer-parsable output, use show + instead. Note that the log data shown is reported by the + virtual machine or container manager, and frequently contains + console output of the machine, but not necessarily journal + contents of the machine itself. + + + + show [NAME...] + + Show properties of one or more registered + virtual machines or containers or the manager itself. If no + argument is specified, properties of the manager will be + shown. If an NAME is specified, properties of this virtual + machine or container are shown. By default, empty properties + are suppressed. Use to show those too. + To select specific properties to show, use + . This command is intended to be + used whenever computer-parsable output is required, and does + not print the cgroup tree or journal entries. Use + status if you are looking for formatted + human-readable output. + + + + start NAME... + + Start a container as a system service, using + systemd-nspawn1. + This starts systemd-nspawn@.service, + instantiated for the specified machine name, similar to the + effect of systemctl start on the service + name. systemd-nspawn looks for a container + image by the specified name in + /var/lib/machines/ (and other search + paths, see below) and runs it. Use + list-images (see below) for listing + available container images to start. + + Note that + systemd-machined.service8 + also interfaces with a variety of other container and VM + managers, systemd-nspawn is just one + implementation of it. Most of the commands available in + machinectl may be used on containers or VMs + controlled by other managers, not just + systemd-nspawn. Starting VMs and container + images on those managers requires manager-specific + tools. + + To interactively start a container on the command line + with full access to the container's console, please invoke + systemd-nspawn directly. To stop a running + container use machinectl poweroff, see + below. + + + + login [NAME] + + Open an interactive terminal login session in + a container or on the local host. If an argument is supplied, + it refers to the container machine to connect to. If none is + specified, or the container name is specified as the empty + string, or the special machine name .host + (see below) is specified, the connection is made to the local + host instead. This will create a TTY connection to a specific + container or the local host and asks for the execution of a + getty on it. Note that this is only supported for containers + running + systemd1 + as init system. + + This command will open a full login prompt on the + container or the local host, which then asks for username and + password. Use shell (see below) or + systemd-run1 + with the switch to directly invoke + a single command, either interactively or in the + background. + + + + shell [[NAME@]NAME [PATH [ARGUMENTS...]]] + + Open an interactive shell session in a + container or on the local host. The first argument refers to + the container machine to connect to. If none is specified, or + the machine name is specified as the empty string, or the + special machine name .host (see below) is + specified, the connection is made to the local host + instead. This works similar to login but + immediately invokes a user process. This command runs the + specified executable with the specified arguments, or + /bin/sh if none is specified. By default, + opens a root shell, but by using + , or by prefixing the machine name with + a username and an @ character, a different + user may be selected. Use to set + environment variables for the executed process. + + When using the shell command without + arguments, (thus invoking the executed shell or command on the + local host), it is in many ways similar to a su1 + session, but, unlike su, completely isolates + the new session from the originating session, so that it + shares no process or session properties, and is in a clean and + well-defined state. It will be tracked in a new utmp, login, + audit, security and keyring session, and will not inherit any + environment variables or resource limits, among other + properties. + + Note that + systemd-run1 + may be used in place of the shell command, + and allows more detailed, low-level configuration of the + invoked unit. However, it is frequently more privileged than + the shell command. + + + + enable NAME... + disable NAME... + + Enable or disable a container as a system + service to start at system boot, using + systemd-nspawn1. + This enables or disables + systemd-nspawn@.service, instantiated for + the specified machine name, similar to the effect of + systemctl enable or systemctl + disable on the service name. + + + + poweroff NAME... + + Power off one or more containers. This will + trigger a reboot by sending SIGRTMIN+4 to the container's init + process, which causes systemd-compatible init systems to shut + down cleanly. This operation does not work on containers that + do not run a + systemd1-compatible + init system, such as sysvinit. Use + terminate (see below) to immediately + terminate a container or VM, without cleanly shutting it + down. + + + + reboot NAME... + + Reboot one or more containers. This will + trigger a reboot by sending SIGINT to the container's init + process, which is roughly equivalent to pressing Ctrl+Alt+Del + on a non-containerized system, and is compatible with + containers running any system manager. + + + + terminate NAME... + + Immediately terminates a virtual machine or + container, without cleanly shutting it down. This kills all + processes of the virtual machine or container and deallocates + all resources attached to that instance. Use + poweroff to issue a clean shutdown + request. + + + + kill NAME... + + Send a signal to one or more processes of the + virtual machine or container. This means processes as seen by + the host, not the processes inside the virtual machine or + container. Use to select which + process to kill. Use to select the + signal to send. + + + + bind NAME PATH [PATH] + + Bind mounts a directory from the host into the + specified container. The first directory argument is the + source directory on the host, the second directory argument + is the destination directory in the container. When the + latter is omitted, the destination path in the container is + the same as the source path on the host. When combined with + the switch, a ready-only bind + mount is created. When combined with the + switch, the destination path is first + created before the mount is applied. Note that this option is + currently only supported for + systemd-nspawn1 + containers. + + + + copy-to NAME PATH [PATH] + + Copies files or directories from the host + system into a running container. Takes a container name, + followed by the source path on the host and the destination + path in the container. If the destination path is omitted, the + same as the source path is used. + + + + + copy-from NAME PATH [PATH] + + Copies files or directories from a container + into the host system. Takes a container name, followed by the + source path in the container the destination path on the host. + If the destination path is omitted, the same as the source path + is used. + + + + Image Commands + + + list-images + + Show a list of locally installed container and + VM images. This enumerates all raw disk images and container + directories and subvolumes in + /var/lib/machines/ (and other search + paths, see below). Use start (see above) to + run a container off one of the listed images. Note that, by + default, containers whose name begins with a dot + (.) are not shown. To show these too, + specify . Note that a special image + .host always implicitly exists and refers + to the image the host itself is booted from. + + + + image-status [NAME...] + + Show terse status information about one or + more container or VM images. This function is intended to + generate human-readable output. Use + show-image (see below) to generate + computer-parsable output instead. + + + + show-image [NAME...] + + Show properties of one or more registered + virtual machine or container images, or the manager itself. If + no argument is specified, properties of the manager will be + shown. If an NAME is specified, properties of this virtual + machine or container image are shown. By default, empty + properties are suppressed. Use to show + those too. To select specific properties to show, use + . This command is intended to be + used whenever computer-parsable output is required. Use + image-status if you are looking for + formatted human-readable output. + + + + clone NAME NAME + + Clones a container or VM image. The arguments specify the name of the image to clone and the + name of the newly cloned image. Note that plain directory container images are cloned into btrfs subvolume + images with this command, if the underlying file system supports this. Note that cloning a container or VM + image is optimized for btrfs file systems, and might not be efficient on others, due to file system + limitations. + + Note that this command leaves host name, machine ID and + all other settings that could identify the instance + unmodified. The original image and the cloned copy will hence + share these credentials, and it might be necessary to manually + change them in the copy. + + If combined with the switch a read-only cloned image is + created. + + + + rename NAME NAME + + Renames a container or VM image. The + arguments specify the name of the image to rename and the new + name of the image. + + + + read-only NAME [BOOL] + + Marks or (unmarks) a container or VM image + read-only. Takes a VM or container image name, followed by a + boolean as arguments. If the boolean is omitted, positive is + implied, i.e. the image is marked read-only. + + + + remove NAME... + + Removes one or more container or VM images. + The special image .host, which refers to + the host's own directory tree, may not be + removed. + + + + set-limit [NAME] BYTES + + Sets the maximum size in bytes that a specific + container or VM image, or all images, may grow up to on disk + (disk quota). Takes either one or two parameters. The first, + optional parameter refers to a container or VM image name. If + specified, the size limit of the specified image is changed. If + omitted, the overall size limit of the sum of all images stored + locally is changed. The final argument specifies the size + limit in bytes, possibly suffixed by the usual K, M, G, T + units. If the size limit shall be disabled, specify + - as size. + + Note that per-container size limits are only supported + on btrfs file systems. Also note that, if + set-limit is invoked without an image + parameter, and /var/lib/machines is + empty, and the directory is not located on btrfs, a btrfs + loopback file is implicitly created as + /var/lib/machines.raw with the given + size, and mounted to + /var/lib/machines. The size of the + loopback may later be readjusted with + set-limit, as well. If such a + loopback-mounted /var/lib/machines + directory is used, set-limit without an image + name alters both the quota setting within the file system as + well as the loopback file and file system size + itself. + + + + clean + + Remove hidden VM or container images (or all). This command removes all hidden machine images + from /var/lib/machines, i.e. those whose name begins with a dot. Use machinectl + list-images --all to see a list of all machine images, including the hidden ones. + + When combined with the switch removes all images, not just hidden ones. This + command effectively empties /var/lib/machines. + + Note that commands such as machinectl pull-tar or machinectl + pull-raw usually create hidden, read-only, unmodified machine images from the downloaded image first, + before cloning a writable working copy of it, in order to avoid duplicate downloads in case of images that are + reused multiple times. Use machinectl clean to remove old, hidden images created this + way. + + + + + Image Transfer Commands + + + pull-tar URL [NAME] + + Downloads a .tar + container image from the specified URL, and makes it available + under the specified local machine name. The URL must be of + type http:// or + https://, and must refer to a + .tar, .tar.gz, + .tar.xz or .tar.bz2 + archive file. If the local machine name is omitted, it + is automatically derived from the last component of the URL, + with its suffix removed. + + The image is verified before it is made available, + unless is specified. Verification + is done via SHA256SUMS and SHA256SUMS.gpg files that need to + be made available on the same web server, under the same URL + as the .tar file, but with the last + component (the filename) of the URL replaced. With + , only the SHA256 checksum + for the file is verified, based on the + SHA256SUMS file. With + , the SHA256SUMS file is + first verified with detached GPG signature file + SHA256SUMS.gpg. The public key for this + verification step needs to be available in + /usr/lib/systemd/import-pubring.gpg or + /etc/systemd/import-pubring.gpg. + + The container image will be downloaded and stored in a + read-only subvolume in + /var/lib/machines/ that is named after + the specified URL and its HTTP etag. A writable snapshot is + then taken from this subvolume, and named after the specified + local name. This behavior ensures that creating multiple + container instances of the same URL is efficient, as multiple + downloads are not necessary. In order to create only the + read-only image, and avoid creating its writable snapshot, + specify - as local machine name. + + Note that the read-only subvolume is prefixed with + .tar-, and is thus not shown by + list-images, unless + is passed. + + Note that pressing C-c during execution of this command + will not abort the download. Use + cancel-transfer, described + below. + + + + pull-raw URL [NAME] + + Downloads a .raw + container or VM disk image from the specified URL, and makes + it available under the specified local machine name. The URL + must be of type http:// or + https://. The container image must either + be a .qcow2 or raw disk image, optionally + compressed as .gz, + .xz, or .bz2. If the + local machine name is omitted, it is automatically + derived from the last component of the URL, with its suffix + removed. + + Image verification is identical for raw and tar images + (see above). + + If the downloaded image is in + .qcow2 format it is converted into a raw + image file before it is made available. + + Downloaded images of this type will be placed as + read-only .raw file in + /var/lib/machines/. A local, writable + (reflinked) copy is then made under the specified local + machine name. To omit creation of the local, writable copy + pass - as local machine name. + + Similar to the behavior of pull-tar, + the read-only image is prefixed with + .raw-, and thus not shown by + list-images, unless + is passed. + + Note that pressing C-c during execution of this command + will not abort the download. Use + cancel-transfer, described + below. + + + + import-tar FILE [NAME] + import-raw FILE [NAME] + Imports a TAR or RAW container or VM image, + and places it under the specified name in + /var/lib/machines/. When + import-tar is used, the file specified as + the first argument should be a tar archive, possibly compressed + with xz, gzip or bzip2. It will then be unpacked into its own + subvolume in /var/lib/machines. When + import-raw is used, the file should be a + qcow2 or raw disk image, possibly compressed with xz, gzip or + bzip2. If the second argument (the resulting image name) is + not specified, it is automatically derived from the file + name. If the file name is passed as -, the + image is read from standard input, in which case the second + argument is mandatory. + + Both pull-tar and pull-raw + will resize /var/lib/machines.raw and the + filesystem therein as necessary. Optionally, the + switch may be used to create a + read-only container or VM image. No cryptographic validation + is done when importing the images. + + Much like image downloads, ongoing imports may be listed + with list-transfers and aborted with + cancel-transfer. + + + + export-tar NAME [FILE] + export-raw NAME [FILE] + Exports a TAR or RAW container or VM image and + stores it in the specified file. The first parameter should be + a VM or container image name. The second parameter should be a + file path the TAR or RAW image is written to. If the path ends + in .gz, the file is compressed with gzip, if + it ends in .xz, with xz, and if it ends in + .bz2, with bzip2. If the path ends in + neither, the file is left uncompressed. If the second argument + is missing, the image is written to standard output. The + compression may also be explicitly selected with the + switch. This is in particular + useful if the second parameter is left unspecified. + + Much like image downloads and imports, ongoing exports + may be listed with list-transfers and + aborted with + cancel-transfer. + + Note that, currently, only directory and subvolume images + may be exported as TAR images, and only raw disk images as RAW + images. + + + + list-transfers + + Shows a list of container or VM image + downloads, imports and exports that are currently in + progress. + + + + cancel-transfers ID... + + Aborts a download, import or export of the + container or VM image with the specified ID. To list ongoing + transfers and their IDs, use + list-transfers. + + + + + + + + Machine and Image Names + + The machinectl tool operates on machines + and images whose names must be chosen following strict + rules. Machine names must be suitable for use as host names + following a conservative subset of DNS and UNIX/Linux + semantics. Specifically, they must consist of one or more + non-empty label strings, separated by dots. No leading or trailing + dots are allowed. No sequences of multiple dots are allowed. The + label strings may only consist of alphanumeric characters as well + as the dash and underscore. The maximum length of a machine name + is 64 characters. + + A special machine with the name .host + refers to the running host system itself. This is useful for execution + operations or inspecting the host system as well. Note that + machinectl list will not show this special + machine unless the switch is specified. + + Requirements on image names are less strict, however, they must be + valid UTF-8, must be suitable as file names (hence not be the + single or double dot, and not include a slash), and may not + contain control characters. Since many operations search for an + image by the name of a requested machine, it is recommended to name + images in the same strict fashion as machines. + + A special image with the name .host + refers to the image of the running host system. It hence + conceptually maps to the special .host machine + name described above. Note that machinectl + list-images will not show this special image either, unless + is specified. + + + + Files and Directories + + Machine images are preferably stored in + /var/lib/machines/, but are also searched for + in /usr/local/lib/machines/ and + /usr/lib/machines/. For compatibility reasons, + the directory /var/lib/container/ is + searched, too. Note that images stored below + /usr are always considered read-only. It is + possible to symlink machines images from other directories into + /var/lib/machines/ to make them available for + control with machinectl. + + Note that many image operations are only supported, + efficient or atomic on btrfs file systems. Due to this, if the + pull-tar, pull-raw, + import-tar, import-raw and + set-limit commands notice that + /var/lib/machines is empty and not located on + btrfs, they will implicitly set up a loopback file + /var/lib/machines.raw containing a btrfs file + system that is mounted to + /var/lib/machines. The size of this loopback + file may be controlled dynamically with + set-limit. + + Disk images are understood by + systemd-nspawn1 + and machinectl in three formats: + + + A simple directory tree, containing the files + and directories of the container to boot. + + Subvolumes (on btrfs file systems), which are + similar to the simple directories, described above. However, + they have additional benefits, such as efficient cloning and + quota reporting. + + "Raw" disk images, i.e. binary images of disks + with a GPT or MBR partition table. Images of this type are + regular files with the suffix + .raw. + + + See + systemd-nspawn1 + for more information on image formats, in particular its + and + options. + + + + Examples + + Download an Ubuntu image and open a shell in it + + # machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz +# systemd-nspawn -M trusty-server-cloudimg-amd64-root + + This downloads and verifies the specified + .tar image, and then uses + systemd-nspawn1 + to open a shell in it. + + + + Download a Fedora image, set a root password in it, start + it as service + + # machinectl pull-raw --verify=no https://dl.fedoraproject.org/pub/fedora/linux/releases/23/Cloud/x86_64/Images/Fedora-Cloud-Base-23-20151030.x86_64.raw.xz +# systemd-nspawn -M Fedora-Cloud-Base-23-20151030 +# passwd +# exit +# machinectl start Fedora-Cloud-Base-23-20151030 +# machinectl login Fedora-Cloud-Base-23-20151030 + + This downloads the specified .raw + image with verification disabled. Then, a shell is opened in it + and a root password is set. Afterwards the shell is left, and + the machine started as system service. With the last command a + login prompt into the container is requested. + + + + Exports a container image as tar file + + # machinectl export-tar fedora myfedora.tar.xz + + Exports the container fedora as an + xz-compressed tar file myfedora.tar.xz into the + current directory. + + + + Create a new shell session + + # machinectl shell --uid=lennart + + This creates a new shell session on the local host for + the user ID lennart, in a su1-like + fashion. + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + + + See Also + + systemd-machined.service8, + systemd-nspawn1, + systemd.special7, + tar1, + xz1, + gzip1, + bzip21 + + + + diff --git a/src/grp-machine/nss-mymachines/nss-mymachines.xml b/src/grp-machine/nss-mymachines/nss-mymachines.xml new file mode 100644 index 0000000000..ec047449bf --- /dev/null +++ b/src/grp-machine/nss-mymachines/nss-mymachines.xml @@ -0,0 +1,113 @@ + + + + + + + + + nss-mymachines + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + nss-mymachines + 8 + + + + nss-mymachines + libnss_mymachines.so.2 + Provide hostname resolution for local + container instances. + + + + libnss_mymachines.so.2 + + + + Description + + nss-mymachines is a plug-in module for the GNU Name Service Switch (NSS) functionality of + the GNU C Library (glibc), providing hostname resolution for the names of containers running + locally that are registered with + systemd-machined.service8. The + container names are resolved to the IP addresses of the specific container, ordered by their scope. This + functionality only applies to containers using network namespacing. + + The module also resolves user and group IDs used by containers to user and group names indicating the + container name, and back. This functionality only applies to containers using user namespacing. + + To activate the NSS module, add mymachines to the lines starting with + hosts:, passwd: and group: in + /etc/nsswitch.conf. + + It is recommended to place mymachines after the files or + compat entry of the /etc/nsswitch.conf lines to make sure that its mappings + are preferred over other resolvers such as DNS, but so that /etc/hosts, + /etc/passwd and /etc/group based mappings take precedence. + + + + Example + + Here is an example /etc/nsswitch.conf file that enables + nss-mymachines correctly: + + passwd: compat mymachines +group: compat mymachines +shadow: compat + +hosts: files mymachines resolve myhostname +networks: files + +protocols: db files +services: db files +ethers: db files +rpc: db files + +netgroup: nis + + + + + See Also + + systemd1, + systemd-machined.service8, + nss-resolve8, + nss-myhostname8, + nsswitch.conf5, + getent1 + + + + diff --git a/src/grp-machine/systemd-machined/systemd-machined.service.xml b/src/grp-machine/systemd-machined/systemd-machined.service.xml new file mode 100644 index 0000000000..999aeee1c6 --- /dev/null +++ b/src/grp-machine/systemd-machined/systemd-machined.service.xml @@ -0,0 +1,90 @@ + + + + + + + + + systemd-machined.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-machined.service + 8 + + + + systemd-machined.service + systemd-machined + Virtual machine and container registration manager + + + + systemd-machined.service + /usr/lib/systemd/systemd-machined + + + + Description + + systemd-machined is a system service that + keeps track of virtual machines and containers, and processes + belonging to them. + + See + systemd-nspawn1 + for some examples on how to run containers with OS tools. + + Use + nss-mymachines8 + to make the names of local containers known to + systemd-machined locally resolvable as host + names. + + See the + + machined D-Bus API Documentation for information about the + APIs systemd-machined provides. + + + + See Also + + systemd1, + machinectl1, + systemd-nspawn1, + nss-mymachines8, + systemd.special7 + + + + diff --git a/src/grp-network/networkctl/networkctl.xml b/src/grp-network/networkctl/networkctl.xml new file mode 100644 index 0000000000..24e1de6986 --- /dev/null +++ b/src/grp-network/networkctl/networkctl.xml @@ -0,0 +1,193 @@ + + + + + + + + + networkctl + systemd + + + + Documentation + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + networkctl + 1 + + + + networkctl + Query the status of network links + + + + + networkctl + OPTIONS + COMMAND + LINK + + + + + Description + + networkctl may be used to introspect the + state of the network links as seen by + systemd-networkd. Please refer to + systemd-networkd.service8 + for an introduction to the basic concepts, functionality, and + configuration syntax. + + + + Options + + The following options are understood: + + + + + + + + + + Show all links with status. + + + + + + + + + + + + + Commands + + The following commands are understood: + + + + + list + LINK... + + + + Show a list of existing links and their status. If no further arguments are specified shows all links, + otherwise just the specified links. Produces output similar to: + + IDX LINK TYPE OPERATIONAL SETUP + 1 lo loopback carrier unmanaged + 2 eth0 ether routable configured + 3 virbr0 ether no-carrier unmanaged + 4 virbr0-nic ether off unmanaged + +4 links listed. + + + + + + status + LINK... + + + + Show information about the specified links: type, + state, kernel module driver, hardware and IP address, + configured DNS servers, etc. + + When no links are specified, an overall network status is shown. Also see the option + . + + Produces output similar to: + +● State: routable + Address: 10.193.76.5 on eth0 + 192.168.122.1 on virbr0 + 169.254.190.105 on eth0 + fe80::5054:aa:bbbb:cccc on eth0 + Gateway: 10.193.11.1 (CISCO SYSTEMS, INC.) on eth0 + DNS: 8.8.8.8 + 8.8.4.4 + + + + + + + lldp + LINK... + + + + Show discovered LLDP (Link Layer Discovery Protocol) neighbors. If one or more link names are specified + only neighbors on those interfaces are shown. Otherwise shows discovered neighbors on all interfaces. Note + that for this feature to work, LLDP= must be turned on on the specific interface, see + systemd.network5 for + details. + + Produces output similar to: + LINK CHASSIS ID SYSTEM NAME CAPS PORT ID PORT DESCRIPTION +enp0s25 00:e0:4c:00:00:00 GS1900 ..b........ 2 Port #2 + +Capability Flags: +o - Other; p - Repeater; b - Bridge; w - WLAN Access Point; r - Router; +t - Telephone; d - DOCSIS cable device; a - Station; c - Customer VLAN; +s - Service VLAN, m - Two-port MAC Relay (TPMR) + +1 neighbors listed. + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure + code otherwise. + + + + See Also + + systemd-networkd.service8, + systemd.network5, + systemd.netdev5 + + + diff --git a/src/grp-network/systemd-networkd-wait-online/systemd-networkd-wait-online.service.xml b/src/grp-network/systemd-networkd-wait-online/systemd-networkd-wait-online.service.xml new file mode 100644 index 0000000000..e21c805342 --- /dev/null +++ b/src/grp-network/systemd-networkd-wait-online/systemd-networkd-wait-online.service.xml @@ -0,0 +1,110 @@ + + + + + + + + + systemd-networkd.service + systemd + + + + Developer + Tom + Gundersen + teg@jklm.no + + + + + + systemd-networkd-wait-online.service + 8 + + + + systemd-networkd-wait-online.service + systemd-networkd-wait-online + Wait for network to come online + + + + systemd-networkd-wait-online.service + /usr/lib/systemd/systemd-networkd-wait-online + + + + Description + + systemd-networkd-wait-online is a + one-shot system service that waits for the network to be + configured. By default, it will wait for all links it is aware of + and which are managed by + systemd-networkd.service8 + to be fully configured or failed, and for at least one link to + gain a carrier. + + + + Options + + The following options are understood: + + + + + + + Network interface to wait for before deciding + if the system is online. This is useful when a system has + several interfaces which will be configured, but a particular + one is necessary to access some network resources. This option + may be used more than once to wait for multiple network + interfaces. When used, all other interfaces are ignored. + + + + + Network interfaces to be ignored when deciding + if the system is online. By default, only the loopback + interface is ignored. This option may be used more than once + to ignore multiple network interfaces. + + + + Fail the service if the network is not online + by the time the timeout elapses. A timeout of 0 disables the + timeout. Defaults to 120 seconds. + + + + + + See Also + + systemd1, + systemd-networkd.service8 + + + + diff --git a/src/grp-network/systemd-networkd/networkd.conf.xml b/src/grp-network/systemd-networkd/networkd.conf.xml new file mode 100644 index 0000000000..4bfc4f773a --- /dev/null +++ b/src/grp-network/systemd-networkd/networkd.conf.xml @@ -0,0 +1,154 @@ + + + + + + + + networkd.conf + systemd + + + + Developer + Vinay + Kulkarni + kulkarniv@vmware.com + + + + + + networkd.conf + 5 + + + + networkd.conf + networkd.conf.d + Global Network configuration files + + + + /etc/systemd/networkd.conf + /etc/systemd/networkd.conf.d/*.conf + /usr/lib/systemd/networkd.conf.d/*.conf + + + + Description + + These configuration files control global network parameters. + Currently the DHCP Unique Identifier (DUID). + + + + + + + [DHCP] Section Options + + This section configures the DHCP Unique Identifier (DUID) value used by DHCP + protocol. DHCPv6 client protocol sends the DHCP Unique Identifier and the interface + Identity Association Identifier (IAID) to a DHCP server when acquiring a dynamic IPv6 + address. DHCPv4 client protocol sends IAID and DUID to the DHCP server when acquiring + a dynamic IPv4 address if . IAID and DUID allows + a DHCP server to uniquely identify the machine and the interface requesting a DHCP IP. + To configure IAID and ClientIdentifier, see + systemd.network5. + + + The following options are understood: + + + + DUIDType= + Specifies how the DUID should be generated. See + RFC 3315 + for a description of all the options. + + The following values are understood: + + + + If DUIDType=vendor, then the DUID value will be generated using + 43793 as the vendor identifier (systemd) and hashed contents of + machine-id5. + This is the default if DUIDType= is not specified. + + + + + + + + Those values are parsed and can be used to set the DUID type + field, but DUID contents must be provided using DUIDRawData=. + + + + + + In all cases, DUIDRawData= can be used to override the + actual DUID value that is used. + + + + DUIDRawData= + Specifies the DHCP DUID value as a single newline-terminated, hexadecimal string, with each + byte separated by :. The DUID that is sent is composed of the DUID type specified by + DUIDType= and the value configured here. + + The DUID value specified here overrides the DUID that systemd-networkd generates using the machine-id + from the /etc/machine-id file. To configure DUID per-network, see + systemd.network 5. + The configured DHCP DUID should conform to the specification in + RFC 3315, + RFC 6355. To configure IAID, see + systemd.network5 + . + + + A <option>DUIDType=vendor</option> with a custom value + + DUIDType=vendor +DUIDRawData=00:00:ab:11:f9:2a:c2:77:29:f9:5c:00 + + This specifies a 14 byte DUID, with the type DUID-EN (00:02), enterprise number + 43793 (00:00:ab:11), and identifier value f9:2a:c2:77:29:f9:5c:00. + + + + + + + + + See Also + + systemd1, + systemd.network5, + machine-id1 + + + + diff --git a/src/grp-network/systemd-networkd/systemd-networkd.service.xml b/src/grp-network/systemd-networkd/systemd-networkd.service.xml new file mode 100644 index 0000000000..0bfe5519bc --- /dev/null +++ b/src/grp-network/systemd-networkd/systemd-networkd.service.xml @@ -0,0 +1,103 @@ + + + + + + + + + systemd-networkd.service + systemd + + + + Developer + Tom + Gundersen + teg@jklm.no + + + + + + systemd-networkd.service + 8 + + + + systemd-networkd.service + systemd-networkd + Network manager + + + + systemd-networkd.service + /usr/lib/systemd/systemd-networkd + + + + Description + + systemd-networkd is a system service that + manages networks. It detects and configures network devices as + they appear, as well as creating virtual network devices. + + To configure low-level link settings independently of + networks, see + systemd.link5. + + Network configurations applied before networkd is started + are not removed, and static configuration applied by networkd is + not removed when networkd exits. Dynamic configuration applied by + networkd may also optionally be left in place on shutdown. This + ensures restarting networkd does not cut the network connection, + and, in particular, that it is safe to transition between the + initrd and the real root, and back. + + + Configuration Files + The configuration files are read from the files located in the + system network directory /usr/lib/systemd/network, + the volatile runtime network directory + /run/systemd/network and the local administration + network directory /etc/systemd/network. + + Networks are configured in .network + files, see + systemd.network5, + and virtual network devices are configured in + .netdev files, see + systemd.netdev5. + + + + + See Also + + systemd1, + systemd.link5, + systemd.network5, + systemd.netdev5, + systemd-networkd-wait-online.service8 + + + + diff --git a/src/grp-resolve/nss-resolve/nss-resolve.xml b/src/grp-resolve/nss-resolve/nss-resolve.xml new file mode 100644 index 0000000000..d9e56453e8 --- /dev/null +++ b/src/grp-resolve/nss-resolve/nss-resolve.xml @@ -0,0 +1,111 @@ + + + + + + + + + nss-resolve + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + nss-resolve + 8 + + + + nss-resolve + libnss_resolve.so.2 + Provide hostname resolution via systemd-resolved.service + + + + libnss_resolve.so.2 + + + + Description + + nss-resolve is a plug-in module for the GNU Name Service Switch (NSS) functionality of the + GNU C Library (glibc) enabling it to resolve host names via the + systemd-resolved8 local network + name resolution service. It replaces the nss-dns plug-in module that traditionally resolves + hostnames via DNS. + + To activate the NSS module, add resolve to the line starting with + hosts: in /etc/nsswitch.conf. + + It is recommended to place resolve early in /etc/nsswitch.conf' + hosts: line (but after the files or mymachines entries), + replacing the dns entry if it exists, to ensure DNS queries are always routed via + systemd-resolved8. + + Note that nss-resolve will chain-load nss-dns if + systemd-resolved.service is not running, ensuring that basic DNS resolution continues to work + if the service is down. + + + + Example + + Here is an example /etc/nsswitch.conf file that enables nss-resolve + correctly: + +passwd: compat mymachines +group: compat mymachines +shadow: compat + +hosts: files mymachines resolve myhostname +networks: files + +protocols: db files +services: db files +ethers: db files +rpc: db files + +netgroup: nis + + + + + See Also + + systemd1, + systemd-resolved8, + nss-mymachines8, + nss-myhostname8, + nsswitch.conf5 + + + + diff --git a/src/grp-resolve/systemd-resolve/systemd-resolve.xml b/src/grp-resolve/systemd-resolve/systemd-resolve.xml new file mode 100644 index 0000000000..4b66f836a2 --- /dev/null +++ b/src/grp-resolve/systemd-resolve/systemd-resolve.xml @@ -0,0 +1,375 @@ + + + + + + + + + systemd-resolve + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-resolve + 1 + + + + systemd-resolve + Resolve domain names, IPV4 and IPv6 addresses, DNS resource records, and services + + + + + systemd-resolve + OPTIONS + HOSTNAME + + + + systemd-resolve + OPTIONS + ADDRESS + + + + systemd-resolve + OPTIONS + --type=TYPE + DOMAIN + + + + systemd-resolve + OPTIONS + --service + NAME + TYPE DOMAIN + + + + systemd-resolve + OPTIONS + --openpgp + USER@DOMAIN + + + + systemd-resolve + OPTIONS + --tlsa + DOMAIN:PORT + + + + systemd-resolve + OPTIONS + --statistics + + + + systemd-resolve + OPTIONS + --reset-statistics + + + + + + Description + + systemd-resolve may be used to resolve domain names, IPv4 and IPv6 addresses, DNS resource + records and services with the + systemd-resolved.service8 + resolver service. By default, the specified list of parameters will be resolved as hostnames, retrieving their IPv4 + and IPv6 addresses. If the parameters specified are formatted as IPv4 or IPv6 operation the reverse operation is + done, and a hostname is retrieved for the specified addresses. + + The switch may be used to specify a DNS resource record type (A, AAAA, SOA, MX, ...) in + order to request a specific DNS resource record, instead of the address or reverse address lookups. + The special value help may be used to list known values. + + The switch may be used to resolve SRV and DNS-SD services (see below). In this mode, between one and three + arguments are required. If three parameters are passed the first is assumed to be the DNS-SD service name, the + second the SRV service type, and the third the domain to search in. In this case a full DNS-SD style SRV and TXT + lookup is executed. If only two parameters are specified, the first is assumed to be the SRV service type, and the + second the domain to look in. In this case no TXT RR is requested. Finally, if only one parameter is specified, it + is assumed to be a domain name, that is already prefixed with an SRV type, and an SRV lookup is done (no + TXT). + + The switch may be used to query PGP keys stored as + OPENPGPKEY resource records. + When this option is specified one or more e-mail address must be specified. + + The switch maybe be used to query TLS public + keys stored as + TLSA resource records. + When this option is specified one or more domain names must be specified. + + The switch may be used to show resolver statistics, including information about + the number of successful and failed DNSSEC validations. + + The may be used to reset various statistics counters maintained the + resolver, including those shown in the output. This operation requires root + privileges. + + + + Options + + + + + + By default, when resolving a hostname, both IPv4 and IPv6 + addresses are acquired. By specifying only IPv4 addresses are requested, by specifying + only IPv6 addresses are requested. + + + + + INTERFACE + INTERFACE + + Specifies the network interface to execute the query on. This may either be specified as numeric + interface index or as network interface string (e.g. en0). Note that this option has no + effect if system-wide DNS configuration (as configured in /etc/resolv.conf or + /etc/systemd/resolve.conf) in place of per-link configuration is used. + + + + PROTOCOL + PROTOCOL + + Specifies the network protocol for the query. May be one of dns + (i.e. classic unicast DNS), llmnr (Link-Local Multicast Name Resolution), + llmnr-ipv4, llmnr-ipv6 (LLMNR via the indicated underlying IP + protocols). By default the lookup is done via all protocols suitable for the lookup. If used, limits the set of + protocols that may be used. Use this option multiple times to enable resolving via multiple protocols at the + same time. The setting llmnr is identical to specifying this switch once with + llmnr-ipv4 and once via llmnr-ipv6. Note that this option does not force + the service to resolve the operation with the specified protocol, as that might require a suitable network + interface and configuration. + The special value help may be used to list known values. + + + + + TYPE + TYPE + CLASS + CLASS + + Specifies the DNS resource record type (e.g. A, AAAA, MX, …) and class (e.g. IN, ANY, …) to + look up. If these options are used a DNS resource record set matching the specified class and type is + requested. The class defaults to IN if only a type is specified. + The special value help may be used to list known values. + + + + + + + Enables service resolution. This enables DNS-SD and simple SRV service resolution, depending + on the specified list of parameters (see above). + + + + BOOL + + Takes a boolean parameter. If true (the default), when doing a service lookup with + the hostnames contained in the SRV resource records are resolved as well. + + + + BOOL + + Takes a boolean parameter. If true (the default), when doing a DNS-SD service lookup with + the TXT service metadata record is resolved as well. + + + + + + Enables OPENPGPKEY resource record resolution (see above). Specified e-mail + addresses are converted to the corresponding DNS domain name, and any OPENPGPKEY keys are + printed. + + + + + + Enables TLSA resource record resolution (see above). + A query will be performed for each of the specified names prefixed with + the port and family + (_port._family.domain). + The port number may be specified after a colon + (:), otherwise 443 will be used + by default. The family may be specified as an argument after + , otherwise tcp will be + used. + + + + BOOL + + Takes a boolean parameter. If true (the default), DNS CNAME or DNAME redirections are + followed. Otherwise, if a CNAME or DNAME record is encountered while resolving, an error is + returned. + + + + BOOL + + Takes a boolean parameter. If true (the default), any specified single-label hostnames will be + searched in the domains configured in the search domain list, if it is non-empty. Otherwise, the search domain + logic is disabled. + + + + =payload|packet + + Dump the answer as binary data. If there is no argument or if the argument is + payload, the payload of the packet is exported. If the argument is + packet, the whole packet is dumped in wire format, prefixed by + length specified as a little-endian 64-bit number. This format allows multiple packets + to be dumped and unambigously parsed. + + + + BOOL + + Takes a boolean parameter. If true (the default), column headers and meta information about the + query response are shown. Otherwise, this output is suppressed. + + + + + + If specified general resolver statistics are shown, including information whether DNSSEC is + enabled and available, as well as resolution and validation statistics. + + + + + + Resets the statistics counters shown in to zero. + + + + + + + + + Examples + + + Retrieve the addresses of the <literal>www.0pointer.net</literal> domain + + $ systemd-resolve www.0pointer.net +www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74 + 85.214.157.71 + +-- Information acquired via protocol DNS in 611.6ms. +-- Data is authenticated: no + + + + + Retrieve the domain of the <literal>85.214.157.71</literal> IP address + + $ systemd-resolve 85.214.157.71 +85.214.157.71: gardel.0pointer.net + +-- Information acquired via protocol DNS in 1.2997s. +-- Data is authenticated: no + + + + + Retrieve the MX record of the <literal>0pointer.net</literal> domain + + $ systemd-resolve -t MX yahoo.com --legend=no +yahoo.com. IN MX 1 mta7.am0.yahoodns.net +yahoo.com. IN MX 1 mta6.am0.yahoodns.net +yahoo.com. IN MX 1 mta5.am0.yahoodns.net + + + + + Resolve an SRV service + + $ systemd-resolve --service _xmpp-server._tcp gmail.com +_xmpp-server._tcp/gmail.com: alt1.xmpp-server.l.google.com:5269 [priority=20, weight=0] + 173.194.210.125 + alt4.xmpp-server.l.google.com:5269 [priority=20, weight=0] + 173.194.65.125 + ... + + + + + Retrieve a PGP key + + $ systemd-resolve --openpgp zbyszek@fedoraproject.org +d08ee310438ca124a6149ea5cc21b6313b390dce485576eff96f8722._openpgpkey.fedoraproject.org. IN OPENPGPKEY + mQINBFBHPMsBEACeInGYJCb+7TurKfb6wGyTottCDtiSJB310i37/6ZYoeIay/5soJjlMyf + MFQ9T2XNT/0LM6gTa0MpC1st9LnzYTMsT6tzRly1D1UbVI6xw0g0vE5y2Cjk3xUwAynCsSs + ... + + + + + Retrieve a TLS key (<literal>=tcp</literal> and + <literal>:443</literal> could be skipped) + + $ systemd-resolve --tlsa=tcp fedoraproject.org:443 +_443._tcp.fedoraproject.org IN TLSA 0 0 1 19400be5b7a31fb733917700789d2f0a2471c0c9d506c0e504c06c16d7cb17c0 + -- Cert. usage: CA constraint + -- Selector: Full Certificate + -- Matching type: SHA-256 + + + + + + See Also + + systemd1, + systemd-resolved.service8 + + + diff --git a/src/grp-resolve/systemd-resolved/dnssec-trust-anchors.d.xml b/src/grp-resolve/systemd-resolved/dnssec-trust-anchors.d.xml new file mode 100644 index 0000000000..4bdc167f79 --- /dev/null +++ b/src/grp-resolve/systemd-resolved/dnssec-trust-anchors.d.xml @@ -0,0 +1,200 @@ + + + + + + + + dnssec-trust-anchors.d + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + dnssec-trust-anchors.d + 5 + + + + dnssec-trust-anchors.d + systemd.positive + systemd.negative + DNSSEC trust anchor configuration files + + + + /etc/dnssec-trust-anchors.d/*.positive + /run/dnssec-trust-anchors.d/*.positive + /usr/lib/dnssec-trust-anchors.d/*.positive + /etc/dnssec-trust-anchors.d/*.negative + /run/dnssec-trust-anchors.d/*.negative + /usr/lib/dnssec-trust-anchors.d/*.negative + + + + Description + + The DNSSEC trust anchor configuration files define positive + and negative trust anchors + systemd-resolved.service8 + bases DNSSEC integrity proofs on. + + + + Positive Trust Anchors + + Positive trust anchor configuration files contain DNSKEY and + DS resource record definitions to use as base for DNSSEC integrity + proofs. See RFC 4035, + Section 4.4 for more information about DNSSEC trust + anchors. + + Positive trust anchors are read from files with the suffix + .positive located in + /etc/dnssec-trust-anchors.d/, + /run/dnssec-trust-anchors.d/ and + /usr/lib/dnssec-trust-anchors.d/. These + directories are searched in the specified order, and a trust + anchor file of the same name in an earlier path overrides a trust + anchor files in a later path. To disable a trust anchor file + shipped in /usr/lib/dnssec-trust-anchors.d/ + it is sufficient to provide an identically-named file in + /etc/dnssec-trust-anchors.d/ or + /run/dnssec-trust-anchors.d/ that is either + empty or a symlink to /dev/null ("masked"). + + Positive trust anchor files are simple text files resembling + DNS zone files, as documented in RFC 1035, Section + 5. One DS or DNSKEY resource record may be listed per + line. Empty lines and lines starting with a semicolon + (;) are ignored and considered comments. A DS + resource record is specified like in the following example: + + . IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5 + + The first word specifies the domain, use + . for the root domain. The domain may be + specified with or without trailing dot, which is considered + equivalent. The second word must be IN the + third word DS. The following words specify the + key tag, signature algorithm, digest algorithm, followed by the + hex-encoded key fingerprint. See RFC 4034, + Section 5 for details about the precise syntax and meaning + of these fields. + + Alternatively, DNSKEY resource records may be used to define + trust anchors, like in the following example: + + . IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0= + + The first word specifies the domain again, the second word + must be IN, followed by + DNSKEY. The subsequent words encode the DNSKEY + flags, protocol and algorithm fields, followed by the key data + encoded in Base64. See RFC 4034, + Section 2 for details about the precise syntax and meaning + of these fields. + + If multiple DS or DNSKEY records are defined for the same + domain (possibly even in different trust anchor files), all keys + are used and are considered equivalent as base for DNSSEC + proofs. + + Note that systemd-resolved will + automatically use a built-in trust anchor key for the Internet + root domain if no positive trust anchors are defined for the root + domain. In most cases it is hence unnecessary to define an + explicit key with trust anchor files. The built-in key is disabled + as soon as at least one trust anchor key for the root domain is + defined in trust anchor files. + + It is generally recommended to encode trust anchors in DS + resource records, rather than DNSKEY resource records. + + If a trust anchor specified via a DS record is found revoked + it is automatically removed from the trust anchor database for the + runtime. See RFC + 5011 for details about revoked trust anchors. Note that + systemd-resolved will not update its trust + anchor database from DNS servers automatically. Instead, it is + recommended to update the resolver software or update the new + trust anchor via adding in new trust anchor files. + + The current DNSSEC trust anchor for the Internet's root + domain is available at the IANA + Trust Anchor and Keys page. + + + + Negative Trust Anchors + + Negative trust anchors define domains where DNSSEC + validation shall be turned off. Negative trust anchor files are + found at the same location as positive trust anchor files, and + follow the same overriding rules. They are text files with the + .negative suffix. Empty lines and lines whose + first character is ; are ignored. Each line + specifies one domain name where DNSSEC validation shall be + disabled on. + + Negative trust anchors are useful to support private DNS + subtrees that are not referenced from the Internet DNS hierarchy, + and not signed. + + RFC + 7646 for details on negative trust anchors. + + If no negative trust anchor files are configured a built-in + set of well-known private DNS zone domains is used as negative + trust anchors. + + It is also possibly to define per-interface negative trust + anchors using the DNSSECNegativeTrustAnchors= + setting in + systemd.network5 + files. + + + + See Also + + systemd1, + systemd-resolved.service8, + resolved.conf5, + systemd.network5 + + + + diff --git a/src/grp-resolve/systemd-resolved/resolved.conf.xml b/src/grp-resolve/systemd-resolved/resolved.conf.xml new file mode 100644 index 0000000000..920ce9e89b --- /dev/null +++ b/src/grp-resolve/systemd-resolved/resolved.conf.xml @@ -0,0 +1,219 @@ + + + + + + + + resolved.conf + systemd + + + + Developer + Tom + Gundersen + teg@jklm.no + + + + + + resolved.conf + 5 + + + + resolved.conf + resolved.conf.d + Network Name Resolution configuration files + + + + /etc/systemd/resolved.conf + /etc/systemd/resolved.conf.d/*.conf + /run/systemd/resolved.conf.d/*.conf + /usr/lib/systemd/resolved.conf.d/*.conf + + + + Description + + These configuration files control local DNS and LLMNR + name resolution. + + + + + + + Options + + The following options are available in the [Resolve] section: + + + + + DNS= + A space-separated list of IPv4 and IPv6 addresses to use as system DNS servers. DNS requests + are sent to one of the listed DNS servers in parallel to suitable per-link DNS servers acquired from + systemd-networkd.service8 or + set at runtime by external applications. For compatibility reasons, if this setting is not specified, the DNS + servers listed in /etc/resolv.conf are used instead, if that file exists and any servers + are configured in it. This setting defaults to the empty list. + + + + FallbackDNS= + A space-separated list of IPv4 and IPv6 addresses to use as the fallback DNS servers. Any + per-link DNS servers obtained from + systemd-networkd.service8 + take precedence over this setting, as do any servers set via DNS= above or + /etc/resolv.conf. This setting is hence only used if no other DNS server information is + known. If this option is not given, a compiled-in list of DNS servers is used instead. + + + + Domains= + A space-separated list of domains. These domains are used as search suffixes when resolving + single-label host names (domain names which contain no dot), in order to qualify them into fully-qualified + domain names (FQDNs). Search domains are strictly processed in the order they are specified, until the name + with the suffix appended is found. For compatibility reasons, if this setting is not specified, the search + domains listed in /etc/resolv.conf are used instead, if that file exists and any domains + are configured in it. This setting defaults to the empty list. + + Specified domain names may optionally be prefixed with ~. In this case they do not + define a search path, but preferably direct DNS queries for the indicated domains to the DNS servers configured + with the system DNS= setting (see above), in case additional, suitable per-link DNS servers + are known. If no per-link DNS servers are known using the ~ syntax has no effect. Use the + construct ~. (which is composed of ~ to indicate a routing domain and + . to indicate the DNS root domain that is the implied suffix of all DNS domains) to use the + system DNS server defined with DNS= preferably for all domains. + + + + LLMNR= + Takes a boolean argument or + resolve. Controls Link-Local Multicast Name + Resolution support (RFC 4794) on + the local host. If true, enables full LLMNR responder and + resolver support. If false, disables both. If set to + resolve, only resolution support is enabled, + but responding is disabled. Note that + systemd-networkd.service8 + also maintains per-link LLMNR settings. LLMNR will be + enabled on a link only if the per-link and the + global setting is on. + + + + DNSSEC= + Takes a boolean argument or + allow-downgrade. If true all DNS lookups are + DNSSEC-validated locally (excluding LLMNR and Multicast + DNS). If the response to a lookup request is detected to be invalid + a lookup failure is returned to applications. Note that + this mode requires a DNS server that supports DNSSEC. If the + DNS server does not properly support DNSSEC all validations + will fail. If set to allow-downgrade DNSSEC + validation is attempted, but if the server does not support + DNSSEC properly, DNSSEC mode is automatically disabled. Note + that this mode makes DNSSEC validation vulnerable to + "downgrade" attacks, where an attacker might be able to + trigger a downgrade to non-DNSSEC mode by synthesizing a DNS + response that suggests DNSSEC was not supported. If set to + false, DNS lookups are not DNSSEC validated. + + Note that DNSSEC validation requires retrieval of + additional DNS data, and thus results in a small DNS look-up + time penalty. + + DNSSEC requires knowledge of "trust anchors" to prove + data integrity. The trust anchor for the Internet root domain + is built into the resolver, additional trust anchors may be + defined with + dnssec-trust-anchors.d5. + Trust anchors may change at regular intervals, and old trust + anchors may be revoked. In such a case DNSSEC validation is + not possible until new trust anchors are configured locally or + the resolver software package is updated with the new root + trust anchor. In effect, when the built-in trust anchor is + revoked and DNSSEC= is true, all further + lookups will fail, as it cannot be proved anymore whether + lookups are correctly signed, or validly unsigned. If + DNSSEC= is set to + allow-downgrade the resolver will + automatically turn off DNSSEC validation in such a case. + + Client programs looking up DNS data will be informed + whether lookups could be verified using DNSSEC, or whether the + returned data could not be verified (either because the data + was found unsigned in the DNS, or the DNS server did not + support DNSSEC or no appropriate trust anchors were known). In + the latter case it is assumed that client programs employ a + secondary scheme to validate the returned DNS data, should + this be required. + + It is recommended to set DNSSEC= to + true on systems where it is known that the DNS server supports + DNSSEC correctly, and where software or trust anchor updates + happen regularly. On other systems it is recommended to set + DNSSEC= to + allow-downgrade. + + In addition to this global DNSSEC setting + systemd-networkd.service8 + also maintains per-link DNSSEC settings. For system DNS + servers (see above), only the global DNSSEC setting is in + effect. For per-link DNS servers the per-link + setting is in effect, unless it is unset in which case the + global setting is used instead. + + Site-private DNS zones generally conflict with DNSSEC + operation, unless a negative (if the private zone is not + signed) or positive (if the private zone is signed) trust + anchor is configured for them. If + allow-downgrade mode is selected, it is + attempted to detect site-private DNS zones using top-level + domains (TLDs) that are not known by the DNS root server. This + logic does not work in all private zone setups. + + Defaults to off. + + + + + + + + See Also + + systemd1, + systemd-resolved.service8, + systemd-networkd.service8, + dnssec-trust-anchors.d5, + resolv.conf4 + + + + diff --git a/src/grp-resolve/systemd-resolved/systemd-resolved.service.xml b/src/grp-resolve/systemd-resolved/systemd-resolved.service.xml new file mode 100644 index 0000000000..829729ca09 --- /dev/null +++ b/src/grp-resolve/systemd-resolved/systemd-resolved.service.xml @@ -0,0 +1,163 @@ + + + + + + + + + systemd-resolved.service + systemd + + + + Developer + Tom + Gundersen + teg@jklm.no + + + + + + systemd-resolved.service + 8 + + + + systemd-resolved.service + systemd-resolved + Network Name Resolution manager + + + + systemd-resolved.service + /usr/lib/systemd/systemd-resolved + + + + Description + + systemd-resolved is a system service that provides network name resolution to local + applications. It implements a caching and validating DNS/DNSSEC stub resolver, as well as an LLMNR resolver and + responder. In addition it maintains the /run/systemd/resolve/resolv.conf file for + compatibility with traditional Linux programs. This file may be symlinked from + /etc/resolv.conf. + + The glibc NSS module + nss-resolve8 is required to + permit glibc's NSS resolver functions to resolve host names via systemd-resolved. + + The DNS servers contacted are determined from the global + settings in /etc/systemd/resolved.conf, the + per-link static settings in /etc/systemd/network/*.network files, + and the per-link dynamic settings received over DHCP. See + resolved.conf5 + and + systemd.network5 + for details. To improve compatibility, + /etc/resolv.conf is read in order to discover + configured system DNS servers, but only if it is not a symlink + to /run/systemd/resolve/resolv.conf (see above). + + systemd-resolved synthesizes DNS RRs for the following cases: + + + The local, configured hostname is resolved to + all locally configured IP addresses ordered by their scope, or + — if none are configured — the IPv4 address 127.0.0.2 (which + is on the local loopback) and the IPv6 address ::1 (which is the + local host). + + The hostnames localhost and + localhost.localdomain (as well as any hostname + ending in .localhost or .localhost.localdomain) + are resolved to the IP addresses 127.0.0.1 and ::1. + + The hostname gateway is + resolved to all current default routing gateway addresses, + ordered by their metric. This assigns a stable hostname to the + current gateway, useful for referencing it independently of the + current network configuration state. + + The mappings defined in /etc/hosts are resolved to their configured + addresses and back. + + + Lookup requests are routed to the available DNS servers + and LLMNR interfaces according to the following rules: + + + Lookups for the special hostname + localhost are never routed to the + network. (A few other, special domains are handled the same way.) + + Single-label names are routed to all local + interfaces capable of IP multicasting, using the LLMNR + protocol. Lookups for IPv4 addresses are only sent via LLMNR on + IPv4, and lookups for IPv6 addresses are only sent via LLMNR on + IPv6. Lookups for the locally configured host name and the + gateway host name are never routed to + LLMNR. + + Multi-label names are routed to all local + interfaces that have a DNS sever configured, plus the globally + configured DNS server if there is one. Address lookups from the + link-local address range are never routed to + DNS. + + + If lookups are routed to multiple interfaces, the first + successful response is returned (thus effectively merging the + lookup zones on all matching interfaces). If the lookup failed on + all interfaces, the last failing response is returned. + + Routing of lookups may be influenced by configuring + per-interface domain names. See + systemd.network5 + for details. Lookups for a hostname ending in one of the + per-interface domains are exclusively routed to the matching + interfaces. + + Note that /run/systemd/resolve/resolv.conf should not be used directly by applications, + but only through a symlink from /etc/resolv.conf. + + See the resolved D-Bus API + Documentation for information about the APIs systemd-resolved provides. + + + + + See Also + + systemd1, + resolved.conf5, + dnssec-trust-anchors.d5, + nss-resolve8, + systemd-resolve1, + resolv.conf5, + hosts5, + systemd.network5, + systemd-networkd.service8 + + + + diff --git a/src/grp-system/bootup.xml b/src/grp-system/bootup.xml new file mode 100644 index 0000000000..986996398c --- /dev/null +++ b/src/grp-system/bootup.xml @@ -0,0 +1,305 @@ + + + + + + + + + bootup + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + bootup + 7 + + + + bootup + System bootup process + + + + Description + + A number of different components are involved in the system + boot. Immediately after power-up, the system BIOS will do minimal + hardware initialization, and hand control over to a boot loader + stored on a persistent storage device. This boot loader will then + invoke an OS kernel from disk (or the network). In the Linux case, + this kernel (optionally) extracts and executes an initial RAM disk + image (initrd), such as generated by + dracut8, + which looks for the root file system (possibly using + systemd1 + for this). After the root file system is found and mounted, the + initrd hands over control to the host's system manager (such as + systemd1) + stored on the OS image, which is then responsible for probing all + remaining hardware, mounting all necessary file systems and + spawning all configured services. + + On shutdown, the system manager stops all services, unmounts + all file systems (detaching the storage technologies backing + them), and then (optionally) jumps back into the initrd code which + unmounts/detaches the root file system and the storage it resides + on. As a last step, the system is powered down. + + Additional information about the system boot process may be + found in + boot7. + + + + System Manager Bootup + + At boot, the system manager on the OS image is responsible + for initializing the required file systems, services and drivers + that are necessary for operation of the system. On + systemd1 + systems, this process is split up in various discrete steps which + are exposed as target units. (See + systemd.target5 + for detailed information about target units.) The boot-up process + is highly parallelized so that the order in which specific target + units are reached is not deterministic, but still adheres to a + limited amount of ordering structure. + + When systemd starts up the system, it will activate all + units that are dependencies of default.target + (as well as recursively all dependencies of these dependencies). + Usually, default.target is simply an alias of + graphical.target or + multi-user.target, depending on whether the + system is configured for a graphical UI or only for a text + console. To enforce minimal ordering between the units pulled in, + a number of well-known target units are available, as listed on + systemd.special7. + + The following chart is a structural overview of these + well-known units and their position in the boot-up logic. The + arrows describe which units are pulled in and ordered before which + other units. Units near the top are started before units nearer to + the bottom of the chart. + +local-fs-pre.target + | + v +(various mounts and (various swap (various cryptsetup + fsck services...) devices...) devices...) (various low-level (various low-level + | | | services: udevd, API VFS mounts: + v v v tmpfiles, random mqueue, configfs, + local-fs.target swap.target cryptsetup.target seed, sysctl, ...) debugfs, ...) + | | | | | + \__________________|_________________ | ___________________|____________________/ + \|/ + v + sysinit.target + | + ____________________________________/|\________________________________________ + / | | | \ + | | | | | + v v | v v + (various (various | (various rescue.service + timers...) paths...) | sockets...) | + | | | | v + v v | v rescue.target + timers.target paths.target | sockets.target + | | | | + v \_________________ | ___________________/ + \|/ + v + basic.target + | + ____________________________________/| emergency.service + / | | | + | | | v + v v v emergency.target + display- (various system (various system + manager.service services services) + | required for | + | graphical UIs) v + | | multi-user.target + | | | + \_________________ | _________________/ + \|/ + v + graphical.target + + Target units that are commonly used as boot targets are + emphasized. These units are good choices as + goal targets, for example by passing them to the + systemd.unit= kernel command line option (see + systemd1) + or by symlinking default.target to them. + + + timers.target is pulled-in by + basic.target asynchronously. This allows + timers units to depend on services which become only available + later in boot. + + + + Bootup in the Initial RAM Disk (initrd) + The initial RAM disk implementation (initrd) can be set up + using systemd as well. In this case, boot up inside the initrd + follows the following structure. + + The default target in the initrd is + initrd.target. The bootup process begins + identical to the system manager bootup (see above) until it + reaches basic.target. From there, systemd + approaches the special target initrd.target. + When the root device becomes available, + initd-root-device.target is reached. + If the root device can be mounted at + /sysroot, the + sysroot.mount unit becomes active and + initrd-root-fs.target is reached. The service + initrd-parse-etc.service scans + /sysroot/etc/fstab for a possible + /usr mount point and additional entries + marked with the x-initrd.mount option. All + entries found are mounted below /sysroot, and + initrd-fs.target is reached. The service + initrd-cleanup.service isolates to the + initrd-switch-root.target, where cleanup + services can run. As the very last step, the + initrd-switch-root.service is activated, + which will cause the system to switch its root to + /sysroot. + + + : (beginning identical to above) + : + v + basic.target + | emergency.service + ______________________/| | + / | v + | initrd-root-device.target emergency.target + | | + | v + | sysroot.mount + | | + | v + | initrd-root-fs.target + | | + | v + v initrd-parse-etc.service + (custom initrd | + services...) v + | (sysroot-usr.mount and + | various mounts marked + | with fstab option + | x-initrd.mount...) + | | + | v + | initrd-fs.target + \______________________ | + \| + v + initrd.target + | + v + initrd-cleanup.service + isolates to + initrd-switch-root.target + | + v + ______________________/| + / v + | initrd-udevadm-cleanup-db.service + v | + (custom initrd | + services...) | + \______________________ | + \| + v + initrd-switch-root.target + | + v + initrd-switch-root.service + | + v + Transition to Host OS + + + + System Manager Shutdown + + System shutdown with systemd also consists of various target + units with some minimal ordering structure applied: + + (conflicts with (conflicts with + all system all file system + services) mounts, swaps, + | cryptsetup + | devices, ...) + | | + v v + shutdown.target umount.target + | | + \_______ ______/ + \ / + v + (various low-level + services) + | + v + final.target + | + _____________________________________/ \_________________________________ + / | | \ + | | | | + v v v v +systemd-reboot.service systemd-poweroff.service systemd-halt.service systemd-kexec.service + | | | | + v v v v + reboot.target poweroff.target halt.target kexec.target + + Commonly used system shutdown targets are + emphasized. + + + + See Also + + systemd1, + boot7, + systemd.special7, + systemd.target5, + dracut8 + + + + diff --git a/src/grp-system/grp-utils/systemd-analyze/systemd-analyze.xml b/src/grp-system/grp-utils/systemd-analyze/systemd-analyze.xml new file mode 100644 index 0000000000..bc37765dff --- /dev/null +++ b/src/grp-system/grp-utils/systemd-analyze/systemd-analyze.xml @@ -0,0 +1,388 @@ + + + + + + + + + systemd-analyze + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + Developer + Harald + Hoyer + harald@redhat.com + + + + + + systemd-analyze + 1 + + + + systemd-analyze + Analyze system boot-up performance + + + + + systemd-analyze + OPTIONS + time + + + systemd-analyze + OPTIONS + blame + + + systemd-analyze + OPTIONS + critical-chain + UNIT + + + systemd-analyze + OPTIONS + plot + > file.svg + + + systemd-analyze + OPTIONS + dot + PATTERN + > file.dot + + + systemd-analyze + OPTIONS + dump + + + systemd-analyze + OPTIONS + set-log-level + LEVEL + + + systemd-analyze + OPTIONS + set-log-target + TARGET + + + systemd-analyze + OPTIONS + verify + FILES + + + + + Description + + systemd-analyze may be used to determine + system boot-up performance statistics and retrieve other state and + tracing information from the system and service manager, and to + verify the correctness of unit files. + + systemd-analyze time prints the time + spent in the kernel before userspace has been reached, the time + spent in the initial RAM disk (initrd) before normal system + userspace has been reached, and the time normal system userspace + took to initialize. Note that these measurements simply measure + the time passed up to the point where all system services have + been spawned, but not necessarily until they fully finished + initialization or the disk is idle. + + systemd-analyze blame prints a list of + all running units, ordered by the time they took to initialize. + This information may be used to optimize boot-up times. Note that + the output might be misleading as the initialization of one + service might be slow simply because it waits for the + initialization of another service to complete. + + systemd-analyze critical-chain + [UNIT...] prints a tree of + the time-critical chain of units (for each of the specified + UNITs or for the default target + otherwise). The time after the unit is active or started is + printed after the "@" character. The time the unit takes to start + is printed after the "+" character. Note that the output might be + misleading as the initialization of one service might depend on + socket activation and because of the parallel execution of + units. + + systemd-analyze plot prints an SVG + graphic detailing which system services have been started at what + time, highlighting the time they spent on initialization. + + systemd-analyze dot generates textual + dependency graph description in dot format for further processing + with the GraphViz + dot1 + tool. Use a command line like systemd-analyze dot | dot + -Tsvg > systemd.svg to generate a graphical dependency + tree. Unless or + is passed, the generated graph will + show both ordering and requirement dependencies. Optional pattern + globbing style specifications (e.g. *.target) + may be given at the end. A unit dependency is included in the + graph if any of these patterns match either the origin or + destination node. + + systemd-analyze dump outputs a (usually + very long) human-readable serialization of the complete server + state. Its format is subject to change without notice and should + not be parsed by applications. + + systemd-analyze set-log-level + LEVEL changes the current log + level of the systemd daemon to + LEVEL (accepts the same values as + described in + systemd1). + + systemd-analyze set-log-target + TARGET changes the current log + target of the systemd daemon to + TARGET (accepts the same values as + , described in + systemd1). + + systemd-analyze verify will load unit + files and print warnings if any errors are detected. Files + specified on the command line will be loaded, but also any other + units referenced by them. This command works by prepending the + directories for all command line arguments at the beginning of the + unit load path, which means that all units files found in those + directories will be used in preference to the unit files found in + the standard locations, even if not listed explicitly. + + If no command is passed, systemd-analyze + time is implied. + + + + + Options + + The following options are understood: + + + + + + Operates on the user systemd + instance. + + + + + + Operates on the system systemd instance. This + is the implied default. + + + + + + + When used in conjunction with the + dot command (see above), selects which + dependencies are shown in the dependency graph. If + is passed, only dependencies of type + After= or Before= are + shown. If is passed, only + dependencies of type Requires=, + Requisite=, + Wants= and Conflicts= + are shown. If neither is passed, this shows dependencies of + all these types. + + + + + + + When used in conjunction with the + dot command (see above), this selects which + relationships are shown in the dependency graph. Both options + require a + glob7 + pattern as an argument, which will be matched against the + left-hand and the right-hand, respectively, nodes of a + relationship. + + Each of these can be used more than once, in which case + the unit name must match one of the values. When tests for + both sides of the relation are present, a relation must pass + both tests to be shown. When patterns are also specified as + positional arguments, they must match at least one side of the + relation. In other words, patterns specified with those two + options will trim the list of edges matched by the positional + arguments, if any are given, and fully determine the list of + edges shown otherwise. + + + + timespan + + When used in conjunction with the + critical-chain command (see above), also + show units, which finished timespan + earlier, than the latest unit in the same level. The unit of + timespan is seconds unless + specified with a different unit, e.g. + "50ms". + + + + + + Do not invoke man to verify the existence of + man pages listed in Documentation=. + + + + + + + + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + Examples for <command>dot</command> + + + Plots all dependencies of any unit whose name starts with + <literal>avahi-daemon</literal> + + $ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg + $ eog avahi.svg + + + + Plots the dependencies between all known target units + + systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' | dot -Tsvg > targets.svg +$ eog targets.svg + + + + + Examples for <command>verify</command> + + The following errors are currently detected: + + unknown sections and directives, + + + missing dependencies which are required to start + the given unit, + + man pages listed in + Documentation= which are not found in the + system, + + commands listed in ExecStart= + and similar which are not found in the system or not + executable. + + + + Misspelt directives + + $ cat ./user.slice +[Unit] +WhatIsThis=11 +Documentation=man:nosuchfile(1) +Requires=different.service + +[Service] +Desription=x + +$ systemd-analyze verify ./user.slice +[./user.slice:9] Unknown lvalue 'WhatIsThis' in section 'Unit' +[./user.slice:13] Unknown section 'Service'. Ignoring. +Error: org.freedesktop.systemd1.LoadFailed: + Unit different.service failed to load: + No such file or directory. +Failed to create user.slice/start: Invalid argument +user.slice: man nosuchfile(1) command failed with code 16 + + + + + Missing service units + + $ tail ./a.socket ./b.socket +==> ./a.socket <== +[Socket] +ListenStream=100 + +==> ./b.socket <== +[Socket] +ListenStream=100 +Accept=yes + +$ systemd-analyze verify ./a.socket ./b.socket +Service a.service not loaded, a.socket cannot be started. +Service b@0.service not loaded, b.socket cannot be started. + + + + + + + + See Also + + systemd1, + systemctl1 + + + + diff --git a/src/grp-system/grp-utils/systemd-delta/systemd-delta.xml b/src/grp-system/grp-utils/systemd-delta/systemd-delta.xml new file mode 100644 index 0000000000..99709604aa --- /dev/null +++ b/src/grp-system/grp-utils/systemd-delta/systemd-delta.xml @@ -0,0 +1,205 @@ + + + + + + + + + systemd-delta + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-delta + 1 + + + + systemd-delta + Find overridden configuration files + + + + + systemd-delta + OPTIONS + PREFIX/SUFFIX|SUFFIX + + + + + Description + + systemd-delta may be used to identify and + compare configuration files that override other configuration + files. Files in /etc have highest priority, + files in /run have the second highest + priority, ..., files in /lib have lowest + priority. Files in a directory with higher priority override files + with the same name in directories of lower priority. In addition, + certain configuration files can have .d + directories which contain "drop-in" files with configuration + snippets which augment the main configuration file. "Drop-in" + files can be overridden in the same way by placing files with the + same name in a directory of higher priority (except that, in case + of "drop-in" files, both the "drop-in" file name and the name of + the containing directory, which corresponds to the name of the + main configuration file, must match). For a fuller explanation, + see + systemd.unit5. + + + The command line argument will be split into a prefix and a + suffix. Either is optional. The prefix must be one of the + directories containing configuration files + (/etc, /run, + /usr/lib, ...). If it is given, only + overriding files contained in this directory will be shown. + Otherwise, all overriding files will be shown. The suffix must be + a name of a subdirectory containing configuration files like + tmpfiles.d, sysctl.d or + systemd/system. If it is given, only + configuration files in this subdirectory (across all configuration + paths) will be analyzed. Otherwise, all configuration files will + be analyzed. If the command line argument is not given at all, all + configuration files will be analyzed. See below for some + examples. + + + + Options + + The following options are understood: + + + + + + + When listing the differences, only list those + that are asked for. The list itself is a comma-separated list + of desired difference types. + + Recognized types are: + + + + masked + + Show masked files + + + + equivalent + + Show overridden files that while + overridden, do not differ in content. + + + + redirected + + Show files that are redirected to + another. + + + + overridden + + Show overridden, and changed + files. + + + + extended + + Show *.conf files + in drop-in directories for units. + + + + unchanged + + Show unmodified files + too. + + + + + + + + + When showing modified files, when a file is + overridden show a diff as well. This option takes a boolean + argument. If omitted, it defaults to + . + + + + + + + + + + Examples + + To see all local configuration: + systemd-delta + + To see all runtime configuration: + systemd-delta /run + + To see all system unit configuration changes: + systemd-delta systemd/system + + To see all runtime "drop-in" changes for system units: + systemd-delta --type=extended /run/systemd/system + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + See Also + + systemd1, + systemd.unit5 + + + + diff --git a/src/grp-system/grp-utils/systemd-fstab-generator/systemd-fstab-generator.xml b/src/grp-system/grp-utils/systemd-fstab-generator/systemd-fstab-generator.xml new file mode 100644 index 0000000000..a971cb3675 --- /dev/null +++ b/src/grp-system/grp-utils/systemd-fstab-generator/systemd-fstab-generator.xml @@ -0,0 +1,183 @@ + + + + + + + + systemd-fstab-generator + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-fstab-generator + 8 + + + + systemd-fstab-generator + Unit generator for /etc/fstab + + + + /usr/lib/systemd/system-generators/systemd-fstab-generator + + + + Description + + systemd-fstab-generator is a generator + that translates /etc/fstab (see + fstab5 + for details) into native systemd units early at boot and when + configuration of the system manager is reloaded. This will + instantiate mount and swap units as necessary. + + The passno field is treated like a simple + boolean, and the ordering information is discarded. However, if + the root file system is checked, it is checked before all the + other file systems. + + See + systemd.mount5 + and + systemd.swap5 + for more information about special /etc/fstab + mount options this generator understands. + + systemd-fstab-generator implements + systemd.generator7. + + + + Kernel Command Line + + systemd-fstab-generator understands the + following kernel command line parameters: + + + + + fstab= + rd.fstab= + + Takes a boolean argument. Defaults to + yes. If no, causes the + generator to ignore any mounts or swaps configured in + /etc/fstab. rd.fstab= + is honored only by initial RAM disk (initrd) while + fstab= is honored by both the main system + and the initrd. + + + root= + + Takes the root filesystem to mount in the + initrd. root= is honored by the + initrd. + + + rootfstype= + + Takes the root filesystem type that will be + passed to the mount command. rootfstype= is + honored by the initrd. + + + rootflags= + + Takes the root filesystem mount options to + use. rootflags= is honored by the + initrd. + + + mount.usr= + + Takes the /usr filesystem + to be mounted by the initrd. If + mount.usrfstype= or + mount.usrflags= is set, then + mount.usr= will default to the value set in + root=. + + Otherwise, this parameter defaults to the + /usr entry found in + /etc/fstab on the root filesystem. + + mount.usr= is honored by the initrd. + + + + mount.usrfstype= + + Takes the /usr filesystem + type that will be passed to the mount command. If + mount.usr= or + mount.usrflags= is set, then + mount.usrfstype= will default to the value + set in rootfstype=. + + Otherwise, this value will be read from the + /usr entry in + /etc/fstab on the root filesystem. + + mount.usrfstype= is honored by the + initrd. + + + mount.usrflags= + + Takes the /usr filesystem + mount options to use. If mount.usr= or + mount.usrfstype= is set, then + mount.usrflags= will default to the value + set in rootflags=. + + Otherwise, this value will be read from the + /usr entry in + /etc/fstab on the root filesystem. + + mount.usrflags= is honored by the + initrd. + + + + + + See Also + + systemd1, + fstab5, + systemd.mount5, + systemd.swap5, + systemd-cryptsetup-generator8 + + + + diff --git a/src/grp-system/grp-utils/systemd-run/systemd-run.xml b/src/grp-system/grp-utils/systemd-run/systemd-run.xml new file mode 100644 index 0000000000..9c1a29218e --- /dev/null +++ b/src/grp-system/grp-utils/systemd-run/systemd-run.xml @@ -0,0 +1,459 @@ + + + + + + + + + systemd-run + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-run + 1 + + + + systemd-run + Run programs in transient scope or service or timer units + + + + + systemd-run + OPTIONS + COMMAND + ARGS + + + + systemd-run + OPTIONS + TIMER OPTIONS + COMMAND + ARGS + + + + + Description + + systemd-run may be used to create and + start a transient .service or + .scope unit and run the specified + COMMAND in it. It may also be used to + create and start transient .timer + units. + + If a command is run as transient service unit, it will be + started and managed by the service manager like any other service, + and thus shows up in the output of systemctl + list-units like any other unit. It will run in a clean + and detached execution environment, with the service manager as + its parent process. In this mode, systemd-run + will start the service asynchronously in the background and return + after the command has begun execution. + + If a command is run as transient scope unit, it will be + started by systemd-run itself as parent process + and will thus inherit the execution environment of the + caller. However, the processes of the command are managed by the + service manager similar to normal services, and will show up in + the output of systemctl list-units. Execution + in this case is synchronous, and will return only when the command + finishes. This mode is enabled via the + switch (see below). + + If a command is run with timer options such as + (see below), a transient timer + unit is created alongside the service unit for the specified + command. Only the transient timer unit is started immediately, the + transient service unit will be started when the transient timer + elapses. If the is specified, the + COMMAND may be omitted. In this case, + systemd-run only creates a + .timer unit that invokes the specified unit + when elapsing. + + + + Options + + The following options are understood: + + + + + + Do not query the user for authentication for + privileged operations. + + + + + + + Create a transient .scope unit instead of + the default transient .service unit. + + + + + + + + Use this unit name instead of an automatically + generated one. + + + + + + + Sets a unit property for the scope or service + unit that is created. This takes an assignment in the same + format as + systemctl1's + set-property command. + + + + + + + Provide a description for the service or scope + unit. If not specified, the command itself will be used as a + description. See Description= in + systemd.unit5. + + + + + + + Make the new .service or + .scope unit part of the specified slice, + instead of the system.slice. + + + + + + + After the service or scope process has + terminated, keep the service around until it is explicitly + stopped. This is useful to collect runtime information about + the service after it finished running. Also see + RemainAfterExit= in + systemd.service5. + + + + + + + + When terminating the scope or service unit, + send a SIGHUP immediately after SIGTERM. This is useful to + indicate to shells and shell-like processes that the + connection has been severed. Also see + SendSIGHUP= in + systemd.kill5. + + + + + + + + Sets the service type. Also see + Type= in + systemd.service5. This + option has no effect in conjunction with + . Defaults to + simple. + + + + + + + + Runs the service process under the UNIX user + and group. Also see User= and + Group= in + systemd.exec5. + + + + + + + Runs the service process with the specified + nice level. Also see Nice= in + systemd.exec5. + + + + + + + + Runs the service process with the specified environment variable set. + Also see Environment= in + systemd.exec5. + + + + + + + + When invoking a command, the service connects + its standard input and output to the invoking tty via a + pseudo TTY device. This allows invoking binaries as services + that expect interactive user input, such as interactive + command shells. + + + + + + + Suppresses additional informational output + while running. This is particularly useful in combination with + when it will suppress the initial + message explaining how to terminate the TTY connection. + + + + + + + + + + Defines monotonic timers relative to different + starting points. Also see OnActiveSec=, + OnBootSec=, + OnStartupSec=, + OnUnitActiveSec= and + OnUnitInactiveSec= in + systemd.timer5. This + options have no effect in conjunction with + . + + + + + + + Defines realtime (i.e. wallclock) timers with + calendar event expressions. Also see + OnCalendar= in + systemd.timer5. This + option has no effect in conjunction with + . + + + + + + + Sets a timer unit property for the timer unit + that is created. It is similar with + but only for created timer + unit. This option only has effect in conjunction with + , , + , + , + , + . This takes an assignment in + the same format as + systemctl1's + set-property command. + + + + + + + Do not synchronously wait for the requested operation + to finish. If this is not specified, the job will be + verified, enqueued and systemd-run will + wait until the unit's start-up is completed. By passing this + argument, it is only verified and enqueued. + + + + + + + + + + + + + All command line arguments after the first non-option + argument become part of the command line of the launched + process. If a command is run as service unit, its first argument + needs to be an absolute binary path. + + + + Exit status + + On success, 0 is returned, a non-zero failure + code otherwise. + + + + Examples + + + Logging environment variables provided by systemd to services + + # systemd-run env +Running as unit: run-19945.service +# journalctl -u run-19945.service +Sep 08 07:37:21 bupkis systemd[1]: Starting /usr/bin/env... +Sep 08 07:37:21 bupkis systemd[1]: Started /usr/bin/env. +Sep 08 07:37:21 bupkis env[19948]: PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin +Sep 08 07:37:21 bupkis env[19948]: LANG=en_US.UTF-8 +Sep 08 07:37:21 bupkis env[19948]: BOOT_IMAGE=/vmlinuz-3.11.0-0.rc5.git6.2.fc20.x86_64 + + + + Limiting resources available to a command + + # systemd-run -p BlockIOWeight=10 updatedb + + This command invokes the + updatedb8 + tool, but lowers the block I/O weight for it to 10. See + systemd.resource-control5 + for more information on the BlockIOWeight= + property. + + + + Running commands at a specified time + + The following command will touch a file after 30 seconds. + + # date; systemd-run --on-active=30 --timer-property=AccuracySec=100ms /bin/touch /tmp/foo +Mon Dec 8 20:44:24 KST 2014 +Running as unit: run-71.timer +Will run service as unit: run-71.service +# journalctl -b -u run-71.timer +-- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. -- +Dec 08 20:44:38 container systemd[1]: Starting /bin/touch /tmp/foo. +Dec 08 20:44:38 container systemd[1]: Started /bin/touch /tmp/foo. +# journalctl -b -u run-71.service +-- Logs begin at Fri 2014-12-05 19:09:21 KST, end at Mon 2014-12-08 20:44:54 KST. -- +Dec 08 20:44:48 container systemd[1]: Starting /bin/touch /tmp/foo... +Dec 08 20:44:48 container systemd[1]: Started /bin/touch /tmp/foo. + + + + Allowing access to the tty + + The following command invokes /bin/bash as a service + passing its standard input, output and error to the calling TTY. + + # systemd-run -t --send-sighup /bin/bash + + + + Start <command>screen</command> as a user service + + $ systemd-run --scope --user screen +Running scope as unit run-r14b0047ab6df45bfb45e7786cc839e76.scope. + +$ screen -ls +There is a screen on: + 492..laptop (Detached) +1 Socket in /var/run/screen/S-fatima. + + + This starts the screen process as a child of the + systemd --user process that was started by + user@.service, in a scope unit. A + systemd.scope5 + unit is used instead of a + systemd.service5 + unit, because screen will exit when detaching from the terminal, + and a service unit would be terminated. Running screen + as a user unit has the advantage that it is not part of the session scope. + If KillUserProcesses=yes is configured in + logind.conf5, + the default, the session scope will be terminated when the user logs + out of that session. + + The user@.service is started automatically + when the user first logs in, and stays around as long as at least one + login session is open. After the user logs out of the last session, + user@.service and all services underneath it + are terminated. This behaviour is the default, when "lingering" is + not enabled for that user. Enabling lingering means that + user@.service is started automatically during + boot, even if the user is not logged in, and that the service is + not terminated when the user logs out. + + Enabling lingering allows the user to run processes without being logged in, + for example to allow screen to persist after the user logs out, + even if the session scope is terminated. In the default configuration, users can + enable lingering for themselves: + + $ loginctl enable-linger + + + + + See Also + + systemd1, + systemctl1, + systemd.unit5, + systemd.service5, + systemd.scope5, + systemd.slice5, + systemd.exec5, + systemd.resource-control5, + systemd.timer5, + machinectl1 + + + + diff --git a/src/grp-system/grp-utils/systemd-sysv-generator/systemd-sysv-generator.xml b/src/grp-system/grp-utils/systemd-sysv-generator/systemd-sysv-generator.xml new file mode 100644 index 0000000000..2353eb3efe --- /dev/null +++ b/src/grp-system/grp-utils/systemd-sysv-generator/systemd-sysv-generator.xml @@ -0,0 +1,97 @@ + + + + + + + + systemd-sysv-generator + systemd + + + + Documentation + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + systemd-sysv-generator + 8 + + + + systemd-sysv-generator + Unit generator for SysV init scripts + + + + /usr/lib/systemd/system-generators/systemd-sysv-generator + + + + Description + + systemd-sysv-generator is a generator + that creates wrapper .service units for + SysV init + scripts in /etc/init.d/* at boot and when + configuration of the system manager is reloaded. This will allow + systemd1 + to support them similarly to native units. + + LSB headers + in SysV init scripts are interpreted, and the ordering specified + in the header is turned into dependencies between the generated + unit and other units. The LSB facilities + $remote_fs, $network, + $named, $portmap, + $time are supported and will be turned into + dependencies on specific native systemd targets. See + systemd.special5 + for more details. + + SysV runlevels have corresponding systemd targets + (runlevelX.target). + The wrapper unit that is generated will be wanted by those targets + which correspond to runlevels for which the script is + enabled. + + systemd does not support SysV scripts as + part of early boot, so all wrapper units are ordered after + basic.target. + + systemd-sysv-generator implements + systemd.generator7. + + + + See Also + + systemd1, + systemd.service5, + systemd.target5 + + + + diff --git a/src/grp-system/kernel-command-line.xml b/src/grp-system/kernel-command-line.xml new file mode 100644 index 0000000000..9c04849f66 --- /dev/null +++ b/src/grp-system/kernel-command-line.xml @@ -0,0 +1,382 @@ + + + + + + + + + kernel-command-line + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + kernel-command-line + 7 + + + + kernel-command-line + Kernel command line parameters + + + + /proc/cmdline + + + + Description + + The kernel, the initial RAM disk (initrd) and + basic userspace functionality may be configured at boot via + kernel command line arguments. + + For command line parameters understood by the kernel, please + see kernel-parameters.txt + and + bootparam7. + + For command line parameters understood by the initial RAM + disk, please see + dracut.cmdline7, + or the documentation of the specific initrd implementation of your + installation. + + + + Core OS Command Line Arguments + + + + systemd.unit= + rd.systemd.unit= + systemd.dump_core= + systemd.crash_chvt= + systemd.crash_shell= + systemd.crash_reboot= + systemd.confirm_spawn= + systemd.show_status= + systemd.log_target= + systemd.log_level= + systemd.log_color= + systemd.log_location= + systemd.default_standard_output= + systemd.default_standard_error= + systemd.setenv= + systemd.machine_id= + + Parameters understood by the system and service + manager to control system behavior. For details, see + systemd1. + + + + + systemd.mask= + systemd.wants= + systemd.debug-shell + + Additional parameters understood by + systemd-debug-generator8, + to mask or start specific units at boot, or invoke a debug + shell on tty9. + + + + + systemd.restore_state= + + This parameter is understood by several system tools + to control whether or not they should restore system state + from the previous boot. For details, see + systemd-backlight@.service8 + and + systemd-rfkill.service8. + + + + + + quiet + + Parameter understood by both the kernel and the system + and service manager to control console log verbosity. For + details, see + systemd1. + + + + + debug + + Parameter understood by both the kernel and the system + and service manager to control console log verbosity. For + details, see + systemd1. + + + + + -b + emergency + rescue + single + s + S + 1 + 2 + 3 + 4 + 5 + + Parameters understood by the system and service + manager, as compatibility options. For details, see + systemd1. + + + + + locale.LANG= + locale.LANGUAGE= + locale.LC_CTYPE= + locale.LC_NUMERIC= + locale.LC_TIME= + locale.LC_COLLATE= + locale.LC_MONETARY= + locale.LC_MESSAGES= + locale.LC_PAPER= + locale.LC_NAME= + locale.LC_ADDRESS= + locale.LC_TELEPHONE= + locale.LC_MEASUREMENT= + locale.LC_IDENTIFICATION= + + Parameters understood by the system and service + manager to control locale and language settings. For + details, see + systemd1. + + + + + fsck.mode= + fsck.repair= + + + Parameters understood by the file system checker + services. For details, see + systemd-fsck@.service8. + + + + + quotacheck.mode= + + + Parameter understood by the file quota checker + service. For details, see + systemd-quotacheck.service8. + + + + + systemd.journald.forward_to_syslog= + systemd.journald.forward_to_kmsg= + systemd.journald.forward_to_console= + systemd.journald.forward_to_wall= + + + Parameters understood by the journal service. For + details, see + systemd-journald.service8. + + + + + vconsole.keymap= + vconsole.keymap.toggle= + vconsole.font= + vconsole.font.map= + vconsole.font.unimap= + + + Parameters understood by the virtual console setup + logic. For details, see + systemd-vconsole-setup.service8. + + + + + udev.log-priority= + rd.udev.log-priority= + udev.children-max= + rd.udev.children-max= + udev.exec-delay= + rd.udev.exec-delay= + udev.event-timeout= + rd.udev.event-timeout= + net.ifnames= + + + Parameters understood by the device event managing + daemon. For details, see + systemd-udevd.service8. + + + + + plymouth.enable= + + + May be used to disable the Plymouth boot splash. For + details, see + plymouth8. + + + + + luks= + rd.luks= + luks.crypttab= + rd.luks.crypttab= + luks.name= + rd.luks.name= + luks.uuid= + rd.luks.uuid= + luks.options= + rd.luks.options= + luks.key= + rd.luks.key= + + + Configures the LUKS full-disk encryption logic at + boot. For details, see + systemd-cryptsetup-generator8. + + + + + fstab= + rd.fstab= + + + Configures the /etc/fstab logic + at boot. For details, see + systemd-fstab-generator8. + + + + + root= + rootfstype= + rootflags= + ro + rw + + + Configures the root file system and its file system + type and mount options, as well as whether it shall be + mounted read-only or read-writable initially. For details, + see + systemd-fstab-generator8. + + + + + systemd.gpt_auto= + rd.systemd.gpt_auto= + + + Configures whether GPT based partition auto-discovery + shall be attempted. For details, see + systemd-gpt-auto-generator8. + + + + + systemd.default_timeout_start_sec= + + + Overwrites the default start job timeout DefaultTimeoutStartSec= at boot. For details, + see systemd-system.conf5. + + + + + modules-load= + rd.modules-load= + + + Load a specific kernel module early at boot. For + details, see + systemd-modules-load.service8. + + + + + resume= + + + Enables resume from hibernation using the specified + device. All + fstab5-like + paths are supported. For details, see + systemd-hibernate-resume-generator8. + + + + + + + + See Also + + systemd1, + bootparam7, + dracut.cmdline7, + systemd-debug-generator8, + systemd-fsck@.service8, + systemd-quotacheck.service8, + systemd-journald.service8, + systemd-vconsole-setup.service8, + systemd-udevd.service8, + plymouth8, + systemd-cryptsetup-generator8, + systemd-fstab-generator8, + systemd-gpt-auto-generator8, + systemd-modules-load.service8, + systemd-backlight@.service8, + systemd-rfkill.service8, + systemd-hibernate-resume-generator8 + + + + diff --git a/src/grp-system/systemctl/halt.xml b/src/grp-system/systemctl/halt.xml new file mode 100644 index 0000000000..e3fa60a915 --- /dev/null +++ b/src/grp-system/systemctl/halt.xml @@ -0,0 +1,176 @@ + + + + + + + + + halt + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + halt + 8 + + + + halt + poweroff + reboot + Halt, power-off or reboot the machine + + + + + halt + OPTIONS + + + poweroff + OPTIONS + + + reboot + OPTIONS + + + + + Description + + halt, poweroff, + reboot may be used to halt, power-off or reboot + the machine. + + + + + Options + + The following options are understood: + + + + + + + + + + + + Halt the machine, regardless of which one of + the three commands is invoked. + + + + + + + Power-off the machine, regardless of which one + of the three commands is invoked. + + + + + + Reboot the machine, regardless of which one of + the three commands is invoked. + + + + + + + Force immediate halt, power-off, reboot. Do + not contact the init system. + + + + + + + Only write wtmp shutdown entry, do not + actually halt, power-off, reboot. + + + + + + + Do not write wtmp shutdown + entry. + + + + + + + Don't sync hard disks/storage media before + halt, power-off, reboot. + + + + + + Do not send wall message before halt, + power-off, reboot. + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + Notes + + These are legacy commands available for compatibility + only. + + + + See Also + + systemd1, + systemctl1, + shutdown8, + wall1 + + + + diff --git a/src/grp-system/systemctl/runlevel.xml b/src/grp-system/systemctl/runlevel.xml new file mode 100644 index 0000000000..ca29c7c22c --- /dev/null +++ b/src/grp-system/systemctl/runlevel.xml @@ -0,0 +1,192 @@ + + + + + + + + + runlevel + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + runlevel + 8 + + + + runlevel + Print previous and current SysV runlevel + + + + + runlevel + options + + + + + Overview + + "Runlevels" are an obsolete way to start and stop groups of + services used in SysV init. systemd provides a compatibility layer + that maps runlevels to targets, and associated binaries like + runlevel. Nevertheless, only one runlevel can + be "active" at a given time, while systemd can activate multiple + targets concurrently, so the mapping to runlevels is confusing + and only approximate. Runlevels should not be used in new code, + and are mostly useful as a shorthand way to refer the matching + systemd targets in kernel boot parameters. + + + Mapping between runlevels and systemd targets + + + + + + Runlevel + Target + + + + + 0 + poweroff.target + + + 1 + rescue.target + + + 2, 3, 4 + multi-user.target + + + 5 + graphical.target + + + 6 + reboot.target + + + +
+ + + + Description + + runlevel prints the previous and current + SysV runlevel if they are known. + + The two runlevel characters are separated by a single space + character. If a runlevel cannot be determined, N is printed + instead. If neither can be determined, the word "unknown" is + printed. + + Unless overridden in the environment, this will check the + utmp database for recent runlevel changes. + + + + Options + + The following option is understood: + + + + + + + + + + + + + Exit status + + If one or both runlevels could be determined, 0 is returned, + a non-zero failure code otherwise. + + + + + Environment + + + + $RUNLEVEL + + If $RUNLEVEL is set, + runlevel will print this value as current + runlevel and ignore utmp. + + + + $PREVLEVEL + + If $PREVLEVEL is set, + runlevel will print this value as previous + runlevel and ignore utmp. + + + + + + Files + + + + /var/run/utmp + + The utmp database runlevel + reads the previous and current runlevel + from. + + + + + + See Also + + systemd1, + systemd.target5, + systemctl1 + + + + diff --git a/src/grp-system/systemctl/shutdown.xml b/src/grp-system/systemctl/shutdown.xml new file mode 100644 index 0000000000..a8af387c67 --- /dev/null +++ b/src/grp-system/systemctl/shutdown.xml @@ -0,0 +1,175 @@ + + + + + + + + + shutdown + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + shutdown + 8 + + + + shutdown + Halt, power-off or reboot the machine + + + + + shutdown + OPTIONS + TIME + WALL + + + + + Description + + shutdown may be used to halt, power-off + or reboot the machine. + + The first argument may be a time string (which is usually + now). Optionally, this may be followed by a + wall message to be sent to all logged-in users before going + down. + + The time string may either be in the format + hh:mm for hour/minutes specifying the time to + execute the shutdown at, specified in 24h clock format. + Alternatively it may be in the syntax +m + referring to the specified number of minutes m from now. + now is an alias for +0, i.e. + for triggering an immediate shutdown. If no time argument is + specified, +1 is implied. + + Note that to specify a wall message you must specify a time + argument, too. + + If the time argument is used, 5 minutes before the system + goes down the /run/nologin file is created to + ensure that further logins shall not be allowed. + + + + Options + + The following options are understood: + + + + + + + + + + + + + Halt the machine. + + + + + + + Power-off the machine (the + default). + + + + + + + Reboot the + machine. + + + + + + Equivalent to , + unless is specified. + + + + + + Do not halt, power-off, reboot, just write + wall message. + + + + + + Do not send wall + message before + halt, power-off, reboot. + + + + + + Cancel a pending shutdown. This may be used + cancel the effect of an invocation of + shutdown with a time argument that is not + +0 or + now. + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + See Also + + systemd1, + systemctl1, + halt8, + wall1 + + + + diff --git a/src/grp-system/systemctl/systemctl.xml b/src/grp-system/systemctl/systemctl.xml new file mode 100644 index 0000000000..991e9bafaf --- /dev/null +++ b/src/grp-system/systemctl/systemctl.xml @@ -0,0 +1,1838 @@ + + +%entities; +]> + + + + + + + systemctl + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemctl + 1 + + + + systemctl + Control the systemd system and service manager + + + + + systemctl + OPTIONS + COMMAND + NAME + + + + + Description + + systemctl may be used to introspect and + control the state of the systemd system and + service manager. Please refer to + systemd1 + for an introduction into the basic concepts and functionality this + tool manages. + + + + Options + + The following options are understood: + + + + + + + + The argument should be a comma-separated list of unit + types such as and + . + + + If one of the arguments is a unit type, when listing + units, limit display to certain unit types. Otherwise, units + of all types will be shown. + + As a special case, if one of the arguments is + , a list of allowed values will be + printed and the program will exit. + + + + + + + + The argument should be a comma-separated list of unit + LOAD, SUB, or ACTIVE states. When listing units, show only + those in the specified states. Use + to show only failed units. + + As a special case, if one of the arguments is + , a list of allowed values will be + printed and the program will exit. + + + + + + + + + When showing unit/job/manager properties with the + show command, limit display to properties + specified in the argument. The argument should be a + comma-separated list of property names, such as + MainPID. Unless specified, all known + properties are shown. If specified more than once, all + properties with the specified names are shown. Shell + completion is implemented for property names. + + For the manager itself, + systemctl show will show all available + properties. Those properties are documented in + systemd-system.conf5. + + + Properties for units vary by unit type, so showing any + unit (even a non-existent one) is a way to list properties + pertaining to this type. Similarly, showing any job will list + properties pertaining to all jobs. Properties for units are + documented in + systemd.unit5, + and the pages for individual unit types + systemd.service5, + systemd.socket5, + etc. + + + + + + + + + When listing units, show all loaded units, regardless + of their state, including inactive units. When showing + unit/job/manager properties, show all properties regardless + whether they are set or not. + To list all units installed on the system, use the + list-unit-files command instead. + + + + + + + + + When listing units, also show units of local + containers. Units of local containers will be prefixed with + the container name, separated by a single colon character + (:). + + + + + + + + Show reverse dependencies between units with + list-dependencies, i.e. follow + dependencies of type WantedBy=, + RequiredBy=, + PartOf=, BoundBy=, + instead of Wants= and similar. + + + + + + + + + With list-dependencies, show the + units that are ordered before the specified unit. In other + words, recursively list units following the + After= dependency. + + Note that any After= dependency is + automatically mirrored to create a + Before= dependency. Temporal dependencies + may be specified explicitly, but are also created implicitly + for units which are WantedBy= targets + (see + systemd.target5), + and as a result of other directives (for example + RequiresMountsFor=). Both explicitly + and implicitly introduced dependencies are shown with + list-dependencies. + + + + + + + + With list-dependencies, show the + units that are ordered after the specified unit. In other + words, recursively list units following the + Before= dependency. + + + + + + + + + Do not ellipsize unit names, process tree entries, + journal output, or truncate unit descriptions in the output + of status, list-units, + list-jobs, and + list-timers. + + + + + + + + When printing properties with show, + only print the value, and skip the property name and + =. + + + + + + + + When showing sockets, show the type of the socket. + + + + + + + + When queuing a new job, this option controls how to deal with + already queued jobs. It takes one of fail, + replace, + replace-irreversibly, + isolate, + ignore-dependencies, + ignore-requirements or + flush. Defaults to + replace, except when the + isolate command is used which implies the + isolate job mode. + + If fail is specified and a requested + operation conflicts with a pending job (more specifically: + causes an already pending start job to be reversed into a stop + job or vice versa), cause the operation to fail. + + If replace (the default) is + specified, any conflicting pending job will be replaced, as + necessary. + + If replace-irreversibly is specified, + operate like replace, but also mark the new + jobs as irreversible. This prevents future conflicting + transactions from replacing these jobs (or even being enqueued + while the irreversible jobs are still pending). Irreversible + jobs can still be cancelled using the cancel + command. + + isolate is only valid for start + operations and causes all other units to be stopped when the + specified unit is started. This mode is always used when the + isolate command is used. + + flush will cause all queued jobs to + be canceled when the new job is enqueued. + + If ignore-dependencies is specified, + then all unit dependencies are ignored for this new job and + the operation is executed immediately. If passed, no required + units of the unit passed will be pulled in, and no ordering + dependencies will be honored. This is mostly a debugging and + rescue tool for the administrator and should not be used by + applications. + + ignore-requirements is similar to + ignore-dependencies, but only causes the + requirement dependencies to be ignored, the ordering + dependencies will still be honoured. + + + + + + + + + Shorthand for fail. + When used with the kill command, + if no units were killed, the operation results in an error. + + + + + + + + + + When system shutdown or a sleep state is requested, + ignore inhibitor locks. Applications can establish inhibitor + locks to avoid that certain important operations (such as CD + burning or suchlike) are interrupted by system shutdown or a + sleep state. Any user may take these locks and privileged + users may override these locks. If any locks are taken, + shutdown and sleep state requests will normally fail + (regardless of whether privileged or not) and a list of active locks + is printed. However, if + is specified, the locks are ignored and not printed, and the + operation attempted anyway, possibly requiring additional + privileges. + + + + + + + + + Suppress printing of the results of various commands + and also the hints about truncated log lines. This does not + suppress output of commands for which the printed output is + the only result (like show). Errors are + always printed. + + + + + + + + Do not synchronously wait for the requested operation + to finish. If this is not specified, the job will be + verified, enqueued and systemctl will + wait until the unit's start-up is completed. By passing this + argument, it is only verified and enqueued. + + + + + + + + + + + + + Do not send wall message before halt, power-off, + reboot. + + + + + + + + When used with enable and + disable, operate on the global user + configuration directory, thus enabling or disabling a unit + file globally for all future logins of all users. + + + + + + + + When used with enable and + disable, do not implicitly reload daemon + configuration after executing the changes. + + + + + + + + When used with start and related + commands, disables asking for passwords. Background services + may require input of a password or passphrase string, for + example to unlock system hard disks or cryptographic + certificates. Unless this option is specified and the + command is invoked from a terminal, + systemctl will query the user on the + terminal for the necessary secrets. Use this option to + switch this behavior off. In this case, the password must be + supplied by some other means (for example graphical password + agents) or the service might fail. This also disables + querying the user for authentication for privileged + operations. + + + + + + + + When used with kill, choose which + processes to send a signal to. Must be one of + , or + to select whether to kill only the main + process, the control process or all processes of the + unit. The main process of the unit is the one that defines + the life-time of it. A control process of a unit is one that + is invoked by the manager to induce state changes of it. For + example, all processes started due to the + ExecStartPre=, + ExecStop= or + ExecReload= settings of service units are + control processes. Note that there is only one control + process per unit at a time, as only one state change is + executed at a time. For services of type + Type=forking, the initial process started + by the manager for ExecStart= is a + control process, while the process ultimately forked off by + that one is then considered the main process of the unit (if + it can be determined). This is different for service units + of other types, where the process forked off by the manager + for ExecStart= is always the main process + itself. A service unit consists of zero or one main process, + zero or one control process plus any number of additional + processes. Not all unit types manage processes of these + types however. For example, for mount units, control processes + are defined (which are the invocations of + &MOUNT_PATH; and + &UMOUNT_PATH;), but no main process + is defined. If omitted, defaults to + . + + + + + + + + + + When used with kill, choose which + signal to send to selected processes. Must be one of the + well-known signal specifiers such as SIGTERM, SIGINT or + SIGSTOP. If omitted, defaults to + . + + + + + + + + + When used with enable, overwrite + any existing conflicting symlinks. + + When used with halt, + poweroff, reboot or + kexec, execute the selected operation + without shutting down all units. However, all processes will + be killed forcibly and all file systems are unmounted or + remounted read-only. This is hence a drastic but relatively + safe option to request an immediate reboot. If + is specified twice for these + operations, they will be executed immediately without + terminating any processes or unmounting any file + systems. Warning: specifying twice + with any of these operations might result in data + loss. + + + + + + + + When used with halt, + poweroff, reboot or + kexec, set a short message explaining the reason + for the operation. The message will be logged together with the + default shutdown message. + + + + + + + + When used with enable, the units + will also be started. When used with disable or + mask, the units will also be stopped. The start + or stop operation is only carried out when the respective enable or + disable operation has been successful. + + + + + + + + When used with + enable/disable/is-enabled + (and related commands), use an alternate root path when + looking for unit files. + + + + + + + + + When used with enable, + disable, edit, + (and related commands), make changes only temporarily, so + that they are lost on the next reboot. This will have the + effect that changes are not made in subdirectories of + /etc but in /run, + with identical immediate effects, however, since the latter + is lost on reboot, the changes are lost too. + + Similarly, when used with + set-property, make changes only + temporarily, so that they are lost on the next + reboot. + + + + + + + + Takes one of full (the default), + enable-only, + disable-only. When used with the + preset or preset-all + commands, controls whether units shall be disabled and + enabled according to the preset rules, or only enabled, or + only disabled. + + + + + + + + + When used with status, controls the + number of journal lines to show, counting from the most + recent ones. Takes a positive integer argument. Defaults to + 10. + + + + + + + + + When used with status, controls the + formatting of the journal entries that are shown. For the + available choices, see + journalctl1. + Defaults to short. + + + + + + + + When used with the reboot command, + indicate to the system's firmware to boot into setup + mode. Note that this is currently only supported on some EFI + systems and only if the system was booted in EFI + mode. + + + + + + + + When used with list-dependencies, + list-units or list-machines, the + the output is printed as a list instead of a tree, and the bullet + circles are omitted. + + + + + + + + + + + + + + + Commands + + The following commands are understood: + + + Unit Commands + + + + list-units PATTERN... + + + List known units (subject to limitations specified + with ). If one or more + PATTERNs are specified, only + units matching one of them are shown. + + This is the default command. + + + + + list-sockets PATTERN... + + + List socket units ordered by listening address. + If one or more PATTERNs are + specified, only socket units matching one of them are + shown. Produces output similar to + +LISTEN UNIT ACTIVATES +/dev/initctl systemd-initctl.socket systemd-initctl.service +... +[::]:22 sshd.socket sshd.service +kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service + +5 sockets listed. + Note: because the addresses might contains spaces, this output + is not suitable for programmatic consumption. + + + See also the options , + , and . + + + + + list-timers PATTERN... + + + List timer units ordered by the time they elapse + next. If one or more PATTERNs + are specified, only units matching one of them are shown. + + + See also the options and + . + + + + + start PATTERN... + + + Start (activate) one or more units specified on the + command line. + + Note that glob patterns operate on the set of primary names of currently loaded units. Units which + are not active and are not in a failed state usually are not loaded, and will not be matched by any + pattern. In addition, in case of instantiated units, systemd is often unaware of the instance name until + the instance has been started. Therefore, using glob patterns with start has limited + usefulness. Also, secondary alias names of units are not considered. + + + + stop PATTERN... + + + Stop (deactivate) one or more units specified on the + command line. + + + + reload PATTERN... + + + Asks all units listed on the command line to reload + their configuration. Note that this will reload the + service-specific configuration, not the unit configuration + file of systemd. If you want systemd to reload the + configuration file of a unit, use the + daemon-reload command. In other words: + for the example case of Apache, this will reload Apache's + httpd.conf in the web server, not the + apache.service systemd unit + file. + + This command should not be confused with the + daemon-reload command. + + + + + restart PATTERN... + + + Restart one or more units specified on the command + line. If the units are not running yet, they will be + started. + + + + try-restart PATTERN... + + + Restart one or more units specified on the command + line if the units are running. This does nothing if units are not + running. + + + + + reload-or-restart PATTERN... + + + Reload one or more units if they support it. If not, + restart them instead. If the units are not running yet, they + will be started. + + + + try-reload-or-restart PATTERN... + + + Reload one or more units if they support it. If not, + restart them instead. This does nothing if the units are not + running. + + + + + isolate NAME + + + Start the unit specified on the command line and its + dependencies and stop all others. If a unit name with no + extension is given, an extension of + .target will be assumed. + + This is similar to changing the runlevel in a + traditional init system. The isolate + command will immediately stop processes that are not enabled + in the new unit, possibly including the graphical + environment or terminal you are currently using. + + Note that this is allowed only on units where + is enabled. See + systemd.unit5 + for details. + + + + kill PATTERN... + + + Send a signal to one or more processes of the + unit. Use to select which + process to kill. Use to select + the signal to send. + + + + is-active PATTERN... + + + Check whether any of the specified units are active + (i.e. running). Returns an exit code + 0 if at least one is active, or + non-zero otherwise. Unless is + specified, this will also print the current unit state to + standard output. + + + + is-failed PATTERN... + + + Check whether any of the specified units are in a + "failed" state. Returns an exit code + 0 if at least one has failed, + non-zero otherwise. Unless is + specified, this will also print the current unit state to + standard output. + + + + status PATTERN...|PID...] + + + Show terse runtime status information about one or + more units, followed by most recent log data from the + journal. If no units are specified, show system status. If + combined with , also show the status of + all units (subject to limitations specified with + ). If a PID is passed, show information + about the unit the process belongs to. + + This function is intended to generate human-readable + output. If you are looking for computer-parsable output, + use show instead. By default, this + function only shows 10 lines of output and ellipsizes + lines to fit in the terminal window. This can be changed + with and , + see above. In addition, journalctl + --unit=NAME or + journalctl + --user-unit=NAME use + a similar filter for messages and might be more + convenient. + + + + + show PATTERN...|JOB... + + + Show properties of one or more units, jobs, or the + manager itself. If no argument is specified, properties of + the manager will be shown. If a unit name is specified, + properties of the unit is shown, and if a job ID is + specified, properties of the job is shown. By default, empty + properties are suppressed. Use to + show those too. To select specific properties to show, use + . This command is intended to be + used whenever computer-parsable output is required. Use + status if you are looking for formatted + human-readable output. + + + + cat PATTERN... + + + Show backing files of one or more units. Prints the + "fragment" and "drop-ins" (source files) of units. Each + file is preceded by a comment which includes the file + name. + + + + set-property NAME ASSIGNMENT... + + + Set the specified unit properties at runtime where + this is supported. This allows changing configuration + parameter properties such as resource control settings at + runtime. Not all properties may be changed at runtime, but + many resource control settings (primarily those in + systemd.resource-control5) + may. The changes are applied instantly, and stored on disk + for future boots, unless is + passed, in which case the settings only apply until the + next reboot. The syntax of the property assignment follows + closely the syntax of assignments in unit files. + + Example: systemctl set-property foobar.service CPUShares=777 + + If the specified unit appears to be inactive, the + changes will be only stored on disk as described + previously hence they will be effective when the unit will + be started. + + Note that this command allows changing multiple + properties at the same time, which is preferable over + setting them individually. Like unit file configuration + settings, assigning the empty list to list parameters will + reset the list. + + + + + help PATTERN...|PID... + + + Show manual pages for one or more units, if + available. If a PID is given, the manual pages for the unit + the process belongs to are shown. + + + + + reset-failed [PATTERN...] + + + Reset the failed state of the + specified units, or if no unit name is passed, reset the state of all + units. When a unit fails in some way (i.e. process exiting + with non-zero error code, terminating abnormally or timing + out), it will automatically enter the + failed state and its exit code and status + is recorded for introspection by the administrator until the + service is restarted or reset with this command. + + + + + + list-dependencies + NAME + + + + Shows units required and wanted by the specified + unit. This recursively lists units following the + Requires=, + Requisite=, + ConsistsOf=, + Wants=, BindsTo= + dependencies. If no unit is specified, + default.target is implied. + + By default, only target units are recursively + expanded. When is passed, all other + units are recursively expanded as well. + + Options , + , + may be used to change what types of dependencies + are shown. + + + + + + + Unit File Commands + + + + list-unit-files PATTERN... + + + List installed unit files and their enablement state + (as reported by is-enabled). If one or + more PATTERNs are specified, + only units whose filename (just the last component of the + path) matches one of them are shown. + + + + + enable NAME... + + + Enable one or more unit files or unit file instances, + as specified on the command line. This will create a number + of symlinks as encoded in the [Install] + sections of the unit files. After the symlinks have been + created, the systemd configuration is reloaded (in a way that + is equivalent to daemon-reload) to ensure + the changes are taken into account immediately. Note that + this does not have the effect of also + starting any of the units being enabled. If this + is desired, either should be used + together with this command, or an additional start + command must be invoked for the unit. Also note that, in case of + instance enablement, symlinks named the same as instances + are created in the install location, however they all point to the + same template unit file. + + This command will print the actions executed. This + output may be suppressed by passing . + + + Note that this operation creates only the suggested + symlinks for the units. While this command is the + recommended way to manipulate the unit configuration + directory, the administrator is free to make additional + changes manually by placing or removing symlinks in the + directory. This is particularly useful to create + configurations that deviate from the suggested default + installation. In this case, the administrator must make sure + to invoke daemon-reload manually as + necessary to ensure the changes are taken into account. + + + Enabling units should not be confused with starting + (activating) units, as done by the start + command. Enabling and starting units is orthogonal: units + may be enabled without being started and started without + being enabled. Enabling simply hooks the unit into various + suggested places (for example, so that the unit is + automatically started on boot or when a particular kind of + hardware is plugged in). Starting actually spawns the daemon + process (in case of service units), or binds the socket (in + case of socket units), and so on. + + Depending on whether , + , , + or is specified, this enables the unit + for the system, for the calling user only, for only this boot of + the system, or for all future logins of all users, or only this + boot. Note that in the last case, no systemd daemon + configuration is reloaded. + + Using enable on masked units + results in an error. + + + + + disable NAME... + + + Disables one or more units. This removes all symlinks + to the specified unit files from the unit configuration + directory, and hence undoes the changes made by + enable. Note however that this removes + all symlinks to the unit files (i.e. including manual + additions), not just those actually created by + enable. This call implicitly reloads the + systemd daemon configuration after completing the disabling + of the units. Note that this command does not implicitly + stop the units that are being disabled. If this is desired, either + should be used together with this command, or + an additional stop command should be executed + afterwards. + + This command will print the actions executed. This + output may be suppressed by passing . + + + This command honors , + , and + in a similar way as + enable. + + + + + reenable NAME... + + + Reenable one or more unit files, as specified on the + command line. This is a combination of + disable and enable and + is useful to reset the symlinks a unit is enabled with to + the defaults configured in the [Install] + section of the unit file. + + + + + preset NAME... + + + Reset the enable/disable status one or more unit files, as specified on + the command line, to the defaults configured in the preset policy files. This + has the same effect as disable or + enable, depending how the unit is listed in the preset + files. + + Use to control whether units shall be + enabled and disabled, or only enabled, or only disabled. + + If the unit carries no install information, it will be silently ignored + by this command. + + For more information on the preset policy format, see + systemd.preset5. + For more information on the concept of presets, please consult the + Preset + document. + + + + + preset-all + + + Resets all installed unit files to the defaults + configured in the preset policy file (see above). + + Use to control + whether units shall be enabled and disabled, or only + enabled, or only disabled. + + + + + is-enabled NAME... + + + Checks whether any of the specified unit files are + enabled (as with enable). Returns an + exit code of 0 if at least one is enabled, non-zero + otherwise. Prints the current enable status (see table). + To suppress this output, use . + + + + + <command>is-enabled</command> output + + + + + + Name + Description + Exit Code + + + + + enabled + Enabled via .wants/, .requires/ or alias symlinks (permanently in /etc/systemd/system/, or transiently in /run/systemd/system/). + 0 + + + enabled-runtime + + + linked + Made available through one or more symlinks to the unit file (permanently in /etc/systemd/system/ or transiently in /run/systemd/system/), even though the unit file might reside outside of the unit file search path. + > 0 + + + linked-runtime + + + masked + Completely disabled, so that any start operation on it fails (permanently in /etc/systemd/system/ or transiently in /run/systemd/systemd/). + > 0 + + + masked-runtime + + + static + The unit file is not enabled, and has no provisions for enabling in the [Install] unit file section. + 0 + + + indirect + The unit file itself is not enabled, but it has a non-empty Also= setting in the [Install] unit file section, listing other unit files that might be enabled. + 0 + + + disabled + The unit file is not enabled, but contains an [Install] section with installation instructions. + > 0 + + + generated + The unit file was generated dynamically via a generator tool. See systemd.generator7. Generated unit files may not be enabled, they are enabled implicitly by their generator. + 0 + + + transient + The unit file has been created dynamically with the runtime API. Transient units may not be enabled. + 0 + + + bad + The unit file is invalid or another error occurred. Note that is-enabled will not actually return this state, but print an error message instead. However the unit file listing printed by list-unit-files might show it. + > 0 + + + +
+ + + + + + mask NAME... + + + Mask one or more unit files, as specified on the + command line. This will link these units to + /dev/null, making it impossible to + start them. This is a stronger version of + disable, since it prohibits all kinds of + activation of the unit, including enablement and manual + activation. Use this option with care. This honors the + option to only mask temporarily + until the next reboot of the system. The + option can be used to ensure that the units are also stopped. + + + + + unmask NAME... + + + Unmask one or more unit files, as specified on the + command line. This will undo the effect of + mask. + + + + + link FILENAME... + + + Link a unit file that is not in the unit file search + paths into the unit file search path. This requires an + absolute path to a unit file. The effect of this can be + undone with disable. The effect of this + command is that a unit file is available for + start and other commands although it + is not installed directly in the unit search path. + + + + + revert NAME... + + + Revert one or more unit files to their vendor versions. This command removes drop-in configuration + files that modify the specified units, as well as any user-configured unit file that overrides a matching + vendor supplied unit file. Specifically, for a unit foo.service the matching directories + foo.service.d/ with all their contained files are removed, both below the persistent and + runtime configuration directories (i.e. below /etc/systemd/system and + /run/systemd/system); if the unit file has a vendor-supplied version (i.e. a unit file + located below /usr) any matching peristent or runtime unit file that overrides it is + removed, too. Note that if a unit file has no vendor-supplied version (i.e. is only defined below + /etc/systemd/system or /run/systemd/system, but not in a unit + file stored below /usr), then it is not removed. Also, if a unit is masked, it is + unmasked. + + Effectively, this command may be used to undo all changes made with systemctl + edit, systemctl set-property and systemctl mask and puts + the original unit file with its settings back in effect. + + + + + add-wants TARGET + NAME... + add-requires TARGET + NAME... + + + Adds Wants= or Requires= + dependencies, respectively, to the specified + TARGET for one or more units. + + This command honors , + , and + in a way similar to + enable. + + + + + + edit NAME... + + + Edit a drop-in snippet or a whole replacement file if + is specified, to extend or override the + specified unit. + + Depending on whether (the default), + , or is specified, + this command creates a drop-in file for each unit either for the system, + for the calling user, or for all futures logins of all users. Then, + the editor (see the "Environment" section below) is invoked on + temporary files which will be written to the real location if the + editor exits successfully. + + If is specified, this will copy the + original units instead of creating drop-in files. + + If is specified, the changes will + be made temporarily in /run and they will be + lost on the next reboot. + + If the temporary file is empty upon exit, the modification of + the related unit is canceled. + + After the units have been edited, systemd configuration is + reloaded (in a way that is equivalent to daemon-reload). + + + Note that this command cannot be used to remotely edit units + and that you cannot temporarily edit units which are in + /etc, since they take precedence over + /run. + + + + + get-default + + + Return the default target to boot into. This returns + the target unit name default.target + is aliased (symlinked) to. + + + + + set-default NAME + + + Set the default target to boot into. This sets + (symlinks) the default.target alias + to the given target unit. + + + + + + + + Machine Commands + + + + list-machines PATTERN... + + + List the host and all running local containers with + their state. If one or more + PATTERNs are specified, only + containers matching one of them are shown. + + + + + + + + Job Commands + + + + list-jobs PATTERN... + + + List jobs that are in progress. If one or more + PATTERNs are specified, only + jobs for units matching one of them are shown. + + + + cancel JOB... + + + Cancel one or more jobs specified on the command line + by their numeric job IDs. If no job ID is specified, cancel + all pending jobs. + + + + + + + Environment Commands + + + + show-environment + + + Dump the systemd manager environment block. The + environment block will be dumped in straight-forward form + suitable for sourcing into a shell script. This environment + block will be passed to all processes the manager + spawns. + + + + set-environment VARIABLE=VALUE... + + + Set one or more systemd manager environment variables, + as specified on the command line. + + + + unset-environment VARIABLE... + + + Unset one or more systemd manager environment + variables. If only a variable name is specified, it will be + removed regardless of its value. If a variable and a value + are specified, the variable is only removed if it has the + specified value. + + + + + import-environment + VARIABLE... + + + + Import all, one or more environment variables set on + the client into the systemd manager environment block. If + no arguments are passed, the entire environment block is + imported. Otherwise, a list of one or more environment + variable names should be passed, whose client-side values + are then imported into the manager's environment + block. + + + + + + + Manager Lifecycle Commands + + + + daemon-reload + + + Reload the systemd manager configuration. This will + rerun all generators (see + systemd.generator7), + reload all unit files, and recreate the entire dependency + tree. While the daemon is being reloaded, all sockets + systemd listens on behalf of user configuration will stay + accessible. + + This command should not be confused with the + reload command. + + + + daemon-reexec + + + Reexecute the systemd manager. This will serialize the + manager state, reexecute the process and deserialize the + state again. This command is of little use except for + debugging and package upgrades. Sometimes, it might be + helpful as a heavy-weight daemon-reload. + While the daemon is being reexecuted, all sockets systemd listening + on behalf of user configuration will stay accessible. + + + + + + + + System Commands + + + + is-system-running + + + Checks whether the system is operational. This + returns success (exit code 0) when the system is fully up + and running, specifically not in startup, shutdown or + maintenance mode, and with no failed services. Failure is + returned otherwise (exit code non-zero). In addition, the + current state is printed in a short string to standard + output, see the table below. Use to + suppress this output. + + + <command>is-system-running</command> output + + + + + + + Name + Description + Exit Code + + + + + initializing + Early bootup, before + basic.target is reached + or the maintenance state entered. + + > 0 + + + starting + Late bootup, before the job queue + becomes idle for the first time, or one of the + rescue targets are reached. + > 0 + + + running + The system is fully + operational. + 0 + + + degraded + The system is operational but one or more + units failed. + > 0 + + + maintenance + The rescue or emergency target is + active. + > 0 + + + stopping + The manager is shutting + down. + > 0 + + + offline + The manager is not + running. Specifically, this is the operational + state if an incompatible program is running as + system manager (PID 1). + > 0 + + + unknown + The operational state could not be + determined, due to lack of resources or another + error cause. + > 0 + + + +
+ + + + + default + + + Enter default mode. This is mostly equivalent to + isolate default.target. + + + + + rescue + + + Enter rescue mode. This is mostly equivalent to + isolate rescue.target, but also prints a + wall message to all users. + + + + emergency + + + Enter emergency mode. This is mostly equivalent to + isolate emergency.target, but also prints + a wall message to all users. + + + + halt + + + Shut down and halt the system. This is mostly equivalent to + start halt.target --job-mode=replace-irreversibly, but also + prints a wall message to all users. If combined with + , shutdown of all running services is + skipped, however all processes are killed and all file + systems are unmounted or mounted read-only, immediately + followed by the system halt. If is + specified twice, the operation is immediately executed + without terminating any processes or unmounting any file + systems. This may result in data loss. + + + + poweroff + + + Shut down and power-off the system. This is mostly + equivalent to start poweroff.target --job-mode=replace-irreversibly, + but also prints a wall message to all users. If combined with + , shutdown of all running services is + skipped, however all processes are killed and all file + systems are unmounted or mounted read-only, immediately + followed by the powering off. If is + specified twice, the operation is immediately executed + without terminating any processes or unmounting any file + systems. This may result in data loss. + + + + reboot arg + + + Shut down and reboot the system. This is mostly + equivalent to start reboot.target --job-mode=replace-irreversibly, + but also prints a wall message to all users. If combined with + , shutdown of all running services is + skipped, however all processes are killed and all file + systems are unmounted or mounted read-only, immediately + followed by the reboot. If is + specified twice, the operation is immediately executed + without terminating any processes or unmounting any file + systems. This may result in data loss. + + If the optional argument + arg is given, it will be passed + as the optional argument to the + reboot2 + system call. The value is architecture and firmware + specific. As an example, recovery might + be used to trigger system recovery, and + fota might be used to trigger a + firmware over the air update. + + + + + kexec + + + Shut down and reboot the system via kexec. This is + mostly equivalent to start kexec.target --job-mode=replace-irreversibly, + but also prints a wall message to all users. If combined + with , shutdown of all running + services is skipped, however all processes are killed and + all file systems are unmounted or mounted read-only, + immediately followed by the reboot. + + + + + exit EXIT_CODE + + + Ask the systemd manager to quit. This is only + supported for user service managers (i.e. in conjunction + with the option) or in containers + and is equivalent to poweroff otherwise. + + The systemd manager can exit with a non-zero exit + code if the optional argument + EXIT_CODE is given. + + + + + switch-root ROOT INIT + + + Switches to a different root directory and executes a + new system manager process below it. This is intended for + usage in initial RAM disks ("initrd"), and will transition + from the initrd's system manager process (a.k.a. "init" + process) to the main system manager process. This call takes two + arguments: the directory that is to become the new root directory, and + the path to the new system manager binary below it to + execute as PID 1. If the latter is omitted or the empty + string, a systemd binary will automatically be searched for + and used as init. If the system manager path is omitted or + equal to the empty string, the state of the initrd's system + manager process is passed to the main system manager, which + allows later introspection of the state of the services + involved in the initrd boot. + + + + + suspend + + + Suspend the system. This will trigger activation of + the special suspend.target target. + + + + + + hibernate + + + Hibernate the system. This will trigger activation of + the special hibernate.target target. + + + + + + hybrid-sleep + + + Hibernate and suspend the system. This will trigger + activation of the special + hybrid-sleep.target target. + + + + + + + Parameter Syntax + + Unit commands listed above take either a single unit name (designated as NAME), + or multiple unit specifications (designated as PATTERN...). In the first case, the + unit name with or without a suffix must be given. If the suffix is not specified (unit name is "abbreviated"), + systemctl will append a suitable suffix, .service by default, and a type-specific suffix in + case of commands which operate only on specific unit types. For example, + # systemctl start sshd and + # systemctl start sshd.service + are equivalent, as are + # systemctl isolate default + and + # systemctl isolate default.target + Note that (absolute) paths to device nodes are automatically converted to device unit names, and other (absolute) + paths to mount unit names. + # systemctl status /dev/sda +# systemctl status /home + are equivalent to: + # systemctl status dev-sda.device +# systemctl status home.mount + In the second case, shell-style globs will be matched against the primary names of all currently loaded units; + literal unit names, with or without a suffix, will be treated as in the first case. This means that literal unit + names always refer to exactly one unit, but globs may match zero units and this is not considered an + error. + + Glob patterns use + fnmatch3, + so normal shell-style globbing rules are used, and + *, ?, + [] may be used. See + glob7 + for more details. The patterns are matched against the primary names of + currently loaded units, and patterns which do not match anything + are silently skipped. For example: + # systemctl stop sshd@*.service + will stop all sshd@.service instances. Note that alias names of units, and units that aren't + loaded are not considered for glob expansion. + + + For unit file commands, the specified NAME should be the name of the unit file + (possibly abbreviated, see above), or the absolute path to the unit file: + # systemctl enable foo.service + or + # systemctl link /path/to/foo.service + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure + code otherwise. + + + + Environment + + + + $SYSTEMD_EDITOR + + Editor to use when editing units; overrides + $EDITOR and $VISUAL. If neither + $SYSTEMD_EDITOR nor $EDITOR nor + $VISUAL are present or if it is set to an empty + string or if their execution failed, systemctl will try to execute well + known editors in this order: + editor1, + nano1, + vim1, + vi1. + + + + + + + + + See Also + + systemd1, + journalctl1, + loginctl1, + machinectl1, + systemd.unit5, + systemd.resource-control5, + systemd.special7, + wall1, + systemd.preset5, + systemd.generator7, + glob7 + + + + diff --git a/src/grp-system/systemctl/systemd-halt.service.xml b/src/grp-system/systemctl/systemd-halt.service.xml new file mode 100644 index 0000000000..c94e2a1820 --- /dev/null +++ b/src/grp-system/systemctl/systemd-halt.service.xml @@ -0,0 +1,118 @@ + + + + + + + + + systemd-halt.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-halt.service + 8 + + + + systemd-halt.service + systemd-poweroff.service + systemd-reboot.service + systemd-kexec.service + systemd-shutdown + System shutdown logic + + + + systemd-halt.service + systemd-poweroff.service + systemd-reboot.service + systemd-kexec.service + /usr/lib/systemd/systemd-shutdown + + + + Description + + systemd-halt.service is a system + service that is pulled in by halt.target and + is responsible for the actual system halt. Similarly, + systemd-poweroff.service is pulled in by + poweroff.target, + systemd-reboot.service by + reboot.target and + systemd-kexec.service by + kexec.target to execute the respective + actions. + + When these services are run, they ensure that PID 1 is + replaced by the + /usr/lib/systemd/systemd-shutdown tool which + is then responsible for the actual shutdown. Before shutting down, + this binary will try to unmount all remaining file systems, + disable all remaining swap devices, detach all remaining storage + devices and kill all remaining processes. + + It is necessary to have this code in a separate binary + because otherwise rebooting after an upgrade might be broken — the + running PID 1 could still depend on libraries which are not + available any more, thus keeping the file system busy, which then + cannot be re-mounted read-only. + + Immediately before executing the actual system + halt/poweroff/reboot/kexec systemd-shutdown + will run all executables in + /usr/lib/systemd/system-shutdown/ and pass + one arguments to them: either halt, + poweroff, reboot or + kexec, depending on the chosen action. All + executables in this directory are executed in parallel, and + execution of the action is not continued before all executables + finished. + + Note that systemd-halt.service (and the + related units) should never be executed directly. Instead, trigger + system shutdown with a command such as systemctl + halt or suchlike. + + + + See Also + + systemd1, + systemctl1, + systemd.special7, + reboot2, + systemd-suspend.service8 + + + + diff --git a/src/grp-system/systemctl/telinit.xml b/src/grp-system/systemctl/telinit.xml new file mode 100644 index 0000000000..02d31fbd46 --- /dev/null +++ b/src/grp-system/systemctl/telinit.xml @@ -0,0 +1,179 @@ + + + + + + + + + telinit + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + telinit + 8 + + + + telinit + Change SysV runlevel + + + + + telinit OPTIONS COMMAND + + + + + Description + + telinit may be used to change the SysV + system runlevel. Since the concept of SysV runlevels is obsolete + the runlevel requests will be transparently translated into + systemd unit activation requests. + + + + + Options + + The following options are understood: + + + + + + + + + + + + Do not send wall message before + reboot/halt/power-off. + + + + The following commands are understood: + + + + 0 + + Power-off the machine. This is translated into + an activation request for poweroff.target + and is equivalent to systemctl + poweroff. + + + + 6 + + Reboot the machine. This is translated into an + activation request for reboot.target and + is equivalent to systemctl + reboot. + + + + 2 + 3 + 4 + 5 + + Change the SysV runlevel. This is translated + into an activation request for + runlevel2.target, + runlevel3.target, ... and is equivalent + to systemctl isolate runlevel2.target, + systemctl isolate runlevel3.target, + ... + + + + 1 + s + S + + Change into system rescue mode. This is + translated into an activation request for + rescue.target and is equivalent to + systemctl rescue. + + + + q + Q + + Reload daemon configuration. This is + equivalent to systemctl + daemon-reload. + + + + u + U + + Serialize state, reexecute daemon and + deserialize state again. This is equivalent to + systemctl daemon-reexec. + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure + code otherwise. + + + + Notes + + This is a legacy command available for compatibility only. + It should not be used anymore, as the concept of runlevels is + obsolete. + + + + See Also + + systemd1, + systemctl1, + wall1 + + + + 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..8833e73c72 --- /dev/null +++ b/src/grp-system/systemd/systemd-system.conf.xml @@ -0,0 +1,394 @@ + + + + + + + + systemd-system.conf + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-system.conf + 5 + + + + systemd-system.conf + system.conf.d + systemd-user.conf + user.conf.d + System and session service manager configuration files + + + + /etc/systemd/system.conf, + /etc/systemd/system.conf.d/*.conf, + /run/systemd/system.conf.d/*.conf, + /usr/lib/systemd/system.conf.d/*.conf + /etc/systemd/user.conf, + /etc/systemd/user.conf.d/*.conf, + /run/systemd/user.conf.d/*.conf, + /usr/lib/systemd/user.conf.d/*.conf + + + + Description + + When run as a system instance, systemd interprets the + configuration file system.conf and the files + in system.conf.d directories; when run as a + user instance, systemd interprets the configuration file + user.conf and the files in + user.conf.d directories. These configuration + files contain a few settings controlling basic manager + operations. + + + + + + Options + + All options are configured in the + [Manager] section: + + + + + LogLevel= + LogTarget= + LogColor= + LogLocation= + DumpCore=yes + CrashChangeVT=no + CrashShell=no + CrashReboot=no + ShowStatus=yes + DefaultStandardOutput=journal + DefaultStandardError=inherit + + Configures various parameters of basic manager + operation. These options may be overridden by the respective + command line arguments. See + systemd1 + for details about these command line + arguments. + + + + CPUAffinity= + + 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. + + + + JoinControllers=cpu,cpuacct net_cls,netprio + + 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. + + 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. + + + + RuntimeWatchdogSec= + ShutdownWatchdogSec= + + Configure the hardware watchdog at runtime and + at reboot. Takes a timeout value in seconds (or in other time + units if suffixed with ms, + min, h, + d, w). If + RuntimeWatchdogSec= is set to a non-zero + value, the watchdog hardware + (/dev/watchdog) 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. ShutdownWatchdogSec= 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 RuntimeWatchdogSec= defaults to 0 + (off), and ShutdownWatchdogSec= to 10min. + These settings have no effect if a hardware watchdog is not + available. + + + + CapabilityBoundingSet= + + Controls which capabilities to include in the + capability bounding set for PID 1 and its children. See + capabilities7 + for details. Takes a whitespace-separated list of capability + names as read by + cap_from_name3. + 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 CapabilityBoundingSet= directive + for units, but note that capabilities dropped for PID 1 cannot + be regained in individual units, they are lost for + good. + + + + SystemCallArchitectures= + + 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 + SystemCallArchitectures= setting of unit + files, see + systemd.exec5 + 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 + x86, x86-64, + x32, arm and the special + identifier native. 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 native 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. + + + + TimerSlackNSec= + + Sets the timer slack in nanoseconds for PID 1, + which is inherited by all executed processes, unless + overridden individually, for example with the + TimerSlackNSec= setting in service units + (for details see + systemd.exec5). + The timer slack controls the accuracy of wake-ups triggered by + system timers. See + prctl2 + 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. + + + + DefaultTimerAccuracySec= + + Sets the default accuracy of timer units. This + controls the global default for the + AccuracySec= setting of timer units, see + systemd.timer5 + for details. AccuracySec= 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 + TimerSlackNSec= above. + + + + DefaultTimeoutStartSec= + DefaultTimeoutStopSec= + DefaultRestartSec= + + 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 + TimeoutStartSec=, + TimeoutStopSec= and + RestartSec= (for services, see + systemd.service5 + for details on the per-unit settings). For non-service units, + DefaultTimeoutStartSec= sets the default + TimeoutSec= + value. DefaultTimeoutStartSec= and + DefaultTimeoutStopSec= default to + 90s. DefaultRestartSec= defaults to + 100ms. + + + + DefaultStartLimitIntervalSec= + DefaultStartLimitBurst= + + Configure the default unit start rate + limiting, as configured per-service by + StartLimitIntervalSec= and + StartLimitBurst=. See + systemd.service5 + for details on the per-service settings. + DefaultStartLimitIntervalSec= defaults to + 10s. DefaultStartLimitBurst= defaults to + 5. + + + + DefaultEnvironment= + + Sets manager environment variables passed to + all executed processes. Takes a space-separated list of + variable assignments. See + environ7 + for details about environment variables. + + Example: + + DefaultEnvironment="VAR1=word1 word2" VAR2=word3 "VAR3=word 5 6" + + Sets three variables + VAR1, + VAR2, + VAR3. + + + + DefaultCPUAccounting= + DefaultBlockIOAccounting= + DefaultMemoryAccounting= + DefaultTasksAccounting= + + Configure the default resource accounting + settings, as configured per-unit by + CPUAccounting=, + BlockIOAccounting=, + MemoryAccounting= and + TasksAccounting=. See + systemd.resource-control5 + for details on the per-unit + settings. DefaulTasksAccounting= defaults + to on, the other three settings to off. + + + + DefaultTasksMax= + + Configure the default value for the per-unit + TasksMax= setting. See + systemd.resource-control5 + for details. This setting applies to all unit types that + support resource control settings, with the exception of slice + units. Defaults to 512. + + + + DefaultLimitCPU= + DefaultLimitFSIZE= + DefaultLimitDATA= + DefaultLimitSTACK= + DefaultLimitCORE= + DefaultLimitRSS= + DefaultLimitNOFILE= + DefaultLimitAS= + DefaultLimitNPROC= + DefaultLimitMEMLOCK= + DefaultLimitLOCKS= + DefaultLimitSIGPENDING= + DefaultLimitMSGQUEUE= + DefaultLimitNICE= + DefaultLimitRTPRIO= + DefaultLimitRTTIME= + + These settings control various default + resource limits for units. See + setrlimit2 + for details. The resource limit is possible to specify in two formats, + to set soft and hard limits to the same value, + or to set both limits individually (e.g. DefaultLimitAS=4G:16G). + Use the string infinity 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 + systemd.time7 + for details). Note that if no time unit is specified for + DefaultLimitCPU= the default unit of seconds is + implied, while for DefaultLimitRTTIME= 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 + DefaultLimitCPU= 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. + + + + + + See Also + + systemd1, + systemd.directives7, + systemd.exec5, + systemd.service5, + environ7, + capabilities7 + + + + 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 @@ + + + + + + + + systemd.automount + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.automount + 5 + + + + systemd.automount + Automount unit configuration + + + + automount.automount + + + + Description + + A unit configuration file whose name ends in + .automount encodes information about a file + system automount point controlled and supervised by + systemd. + + This man page lists the configuration options specific to + this unit type. See + systemd.unit5 + 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. + + Automount units must be named after the automount directories they control. Example: the automount point + /home/lennart must be configured in a unit file + home-lennart.automount. For details about the escaping logic used to convert a file system + path to a unit name see + systemd.unit5. 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. + + For each automount unit file a matching mount unit file (see + systemd.mount5 + for details) must exist which is activated when the automount path + is accessed. Example: if an automount unit + home-lennart.automount is active and the user + accesses /home/lennart the mount unit + home-lennart.mount will be activated. + + Automount units may be used to implement on-demand mounting + as well as parallelized mounting of file systems. + + + + Automatic Dependencies + + 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. + + An implicit Before= dependency is created + between an automount unit and the mount unit it activates. + + Automount units acquire automatic Before= and Conflicts= on + umount.target in order to be stopped during shutdown, unless + DefaultDependencies=no is set in the [Unit] section. + + + + + <filename>fstab</filename> + + Automount units may either be configured via unit files, or + via /etc/fstab (see + fstab5 + for details). + + For details how systemd parses + /etc/fstab see + systemd.mount5. + + If an automount point is configured in both + /etc/fstab and a unit file, the configuration + in the latter takes precedence. + + + + Options + + 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: + + + + + Where= + 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. + + + + DirectoryMode= + 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. + + + TimeoutIdleSec= + 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. + + + + + + See Also + + systemd1, + systemctl1, + systemd.unit5, + systemd.mount5, + mount8, + automount8, + systemd.directives7 + + + + 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 @@ + + + + + + + + systemd.device + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.device + 5 + + + + systemd.device + Device unit configuration + + + + device.device + + + + Description + + A unit configuration file whose name ends in + .device encodes information about a device unit + as exposed in the + sysfs/udev7 + device tree. + + This unit type has no specific options. See + systemd.unit5 + for the common options of all unit configuration files. The common + configuration items are configured in the generic + [Unit] and [Install] + sections. A separate [Device] section does not + exist, since no device-specific options may be configured. + + 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 TAG+="systemd" in the udev + rules file, see + udev7 + for details. + + Device units are named after the /sys + and /dev paths they control. Example: the + device /dev/sda5 is exposed in + systemd as dev-sda5.device. For details about + the escaping logic used to convert a file system path to a unit + name see + systemd.unit5. + + + + Automatic Dependencies + + Many unit types automatically acquire dependencies on device + units of devices they require. For example, + .socket unit acquire dependencies on the + device units of the network interface specified in + BindToDevice=. Similar, swap and mount units + acquire dependencies on the units encapsulating their backing + block devices. + + + + The udev Database + + 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: + + + + SYSTEMD_WANTS= + SYSTEMD_USER_WANTS= + Adds dependencies of type + Wants 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. + + Note that this and the other tags are not taken into + account unless the device is tagged with the + systemd string in the udev database, + because otherwise the device is not exposed as a systemd unit + (see above). + + Note that systemd will only act on + Wants dependencies when a device first + becomes active. It will not act on them if they are added to + devices that are already active. Use + SYSTEMD_READY= (see below) to influence on + which udev event to trigger the dependencies. + + + + + SYSTEMD_ALIAS= + 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.) + + + + SYSTEMD_READY= + 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. + + This option is useful to support devices that initially + show up in an uninitialized state in the tree, and for which a + changed event is generated the moment they + are fully set up. Note that SYSTEMD_WANTS= + (see above) is not acted on as long as + SYSTEMD_READY=0 is set for a + device. + + + + ID_MODEL_FROM_DATABASE= + ID_MODEL= + + If set, this property is used as description + string for the device unit. + + + + + + + + See Also + + systemd1, + systemctl1, + systemd.unit5, + udev7, + systemd.directives7 + + + + diff --git a/src/grp-system/systemd/systemd.exec.xml b/src/grp-system/systemd/systemd.exec.xml new file mode 100644 index 0000000000..3cf6de8256 --- /dev/null +++ b/src/grp-system/systemd/systemd.exec.xml @@ -0,0 +1,1475 @@ + + + + + + + + systemd.exec + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.exec + 5 + + + + systemd.exec + Execution environment configuration + + + + service.service, + socket.socket, + mount.mount, + swap.swap + + + + Description + + 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. + + This man page lists the configuration options shared by + these four unit types. See + systemd.unit5 + for the common options of all unit configuration files, and + systemd.service5, + systemd.socket5, + systemd.swap5, + and + systemd.mount5 + 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. + + + + Automatic Dependencies + + A few execution parameters result in additional, automatic + dependencies to be added. + + Units with WorkingDirectory= or + RootDirectory= set automatically gain + dependencies of type Requires= and + After= on all mount units required to access + the specified paths. This is equivalent to having them listed + explicitly in RequiresMountsFor=. + + Similar, units with PrivateTmp= enabled + automatically get mount unit dependencies for all mounts + required to access /tmp and + /var/tmp. + + Units whose standard output or error output is connected to , + or (or their combinations with console output, see below) automatically acquire dependencies + of type After= on systemd-journald.socket. + + + + Options + + + + + WorkingDirectory= + + Takes an absolute directory path, or the + special value ~. Sets the working directory + for executed processes. If set to ~, the + home directory of the user specified in + User= 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 - + character, a missing working directory is not considered + fatal. Note that setting this parameter might result in + additional dependencies to be added to the unit (see + above). + + + + RootDirectory= + + Takes an absolute directory path. Sets the + root directory for executed processes, with the chroot2 + system call. If this is used, it must be ensured that the + process binary and all its auxiliary files are available in + the chroot() jail. Note that setting this + parameter might result in additional dependencies to be added + to the unit (see above). + + + + User= + Group= + + Sets the Unix user or group that the processes + are executed as, respectively. Takes a single user or group + name or ID as argument. If no group is set, the default group + of the user is chosen. + + + + SupplementaryGroups= + + 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. + + + + Nice= + + Sets the default nice level (scheduling + priority) for executed processes. Takes an integer between -20 + (highest priority) and 19 (lowest priority). See + setpriority2 + for details. + + + + OOMScoreAdjust= + + 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 proc.txt + for details. + + + + IOSchedulingClass= + + Sets the I/O scheduling class for executed + processes. Takes an integer between 0 and 3 or one of the + strings , , + or . See + ioprio_set2 + for details. + + + + IOSchedulingPriority= + + 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 + ioprio_set2 + for details. + + + + CPUSchedulingPolicy= + + Sets the CPU scheduling policy for executed + processes. Takes one of + , + , + , + or + . See + sched_setscheduler2 + for details. + + + + CPUSchedulingPriority= + + 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 + sched_setscheduler2 + for details. + + + + CPUSchedulingResetOnFork= + + 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 + sched_setscheduler2 + for details. Defaults to false. + + + + CPUAffinity= + + 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 + sched_setaffinity2 + for details. + + + + UMask= + + Controls the file mode creation mask. Takes an + access mode in octal notation. See + umask2 + for details. Defaults to 0022. + + + + Environment= + + 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. + + Example: + Environment="VAR1=word1 word2" VAR2=word3 "VAR3=$word 5 6" + gives three variables VAR1, + VAR2, VAR3 + with the values word1 word2, + word3, $word 5 6. + + + + See + environ7 + for details about environment variables. + + + EnvironmentFile= + Similar to Environment= but + reads the environment variables from a text file. The text + file should contain new-line-separated variable assignments. + Empty lines, lines without an = 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 ("). + + The argument passed should be an absolute filename or + wildcard expression, optionally prefixed with + -, 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. + + 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). + + Settings from these + files override settings made with + Environment=. 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. + + + + PassEnvironment= + + 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. + + Variables passed from this setting are overridden by those passed + from Environment= or + EnvironmentFile=. + + Example: + PassEnvironment=VAR1 VAR2 VAR3 + passes three variables VAR1, + VAR2, VAR3 + with the values set for those variables in PID1. + + + See + environ7 + for details about environment variables. + + + + StandardInput= + Controls where file descriptor 0 (STDIN) of + the executed processes is connected to. Takes one of + , + , + , + or + . + + If is selected, standard input + will be connected to /dev/null, i.e. all + read attempts by the process will result in immediate + EOF. + + If is selected, standard input is + connected to a TTY (as configured by + TTYPath=, 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. + + is similar to + , but the executed process is forcefully + and immediately made the controlling process of the terminal, + potentially removing previous controlling processes from the + terminal. + + is similar to + but if the terminal already has a + controlling process start-up of the executed process + fails. + + The option is only valid in + socket-activated services, and only when the socket + configuration file (see + systemd.socket5 + 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 + inetd8 + daemon. + + This setting defaults to + . + + + + StandardOutput= + Controls where file descriptor 1 (STDOUT) of + the executed processes is connected to. Takes one of + , + , + , + , + , + , + , + , + or + . + + duplicates the file descriptor + of standard input for standard output. + + connects standard output to + /dev/null, i.e. everything written to it + will be lost. + + connects standard output to a tty + (as configured via TTYPath=, 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. + + connects standard output with + the journal which is accessible via + journalctl1. + 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. + + connects standard output to the + syslog3 + 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 . + + connects standard output with the + kernel log buffer which is accessible via + dmesg1, + 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 . + + , + and + work in a similar way as the + three options above but copy the output to the system console + as well. + + connects standard output to a + socket acquired via socket activation. The semantics are + similar to the same option of + StandardInput=. + + 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 After= on + systemd-journald.socket (also see the automatic dependencies section above). + + This setting defaults to the value set with + in + systemd-system.conf5, + which defaults to . Note that setting + this parameter might result in additional dependencies to be + added to the unit (see above). + + + + StandardError= + Controls where file descriptor 2 (STDERR) of + the executed processes is connected to. The available options + are identical to those of StandardOutput=, + with one exception: if set to the + file descriptor used for standard output is duplicated for + standard error. This setting defaults to the value set with + in + systemd-system.conf5, + which defaults to . Note that setting + this parameter might result in additional dependencies to be + added to the unit (see above). + + + + TTYPath= + Sets the terminal device node to use if + standard input, output, or error are connected to a TTY (see + above). Defaults to + /dev/console. + + + TTYReset= + Reset the terminal device specified with + TTYPath= before and after execution. + Defaults to no. + + + TTYVHangup= + Disconnect all clients which have opened the + terminal device specified with TTYPath= + before and after execution. Defaults to + no. + + + TTYVTDisallocate= + If the terminal device specified with + TTYPath= 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 + no. + + + SyslogIdentifier= + 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 + StandardOutput= or + StandardError= are set to + , or + (or to the same settings in combination + with ). + + + SyslogFacility= + Sets the syslog facility to use when logging + to syslog. One of , + , , + , , + , , + , , + , , + , , + , , + , , + , or + . See + syslog3 + for details. This option is only useful when + StandardOutput= or + StandardError= are set to + . Defaults to + . + + + SyslogLevel= + The default syslog level to use when logging to + syslog or the kernel log buffer. One of + , + , + , + , + , + , + , + . See + syslog3 + for details. This option is only useful when + StandardOutput= or + StandardError= are set to + or . 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 SyslogLevelPrefix=, + see below. For details, see + sd-daemon3. + + Defaults to + . + + + + SyslogLevelPrefix= + Takes a boolean argument. If true and + StandardOutput= or + StandardError= are set to + , or + , 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 + sd-daemon3. + Defaults to true. + + + + TimerSlackNSec= + Sets the timer slack in nanoseconds for the + executed processes. The timer slack controls the accuracy of + wake-ups triggered by timers. See + prctl2 + 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. + + + + LimitCPU= + LimitFSIZE= + LimitDATA= + LimitSTACK= + LimitCORE= + LimitRSS= + LimitNOFILE= + LimitAS= + LimitNPROC= + LimitMEMLOCK= + LimitLOCKS= + LimitSIGPENDING= + LimitMSGQUEUE= + LimitNICE= + LimitRTPRIO= + LimitRTTIME= + Set soft and hard limits on various resources for executed processes. See + setrlimit2 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 to set + both limits individually (e.g. LimitAS=4G:16G). Use the string infinity + 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 + systemd.time7 for + details). Note that if no time unit is specified for LimitCPU= the default unit of seconds + is implied, while for LimitRTTIME= 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 LimitCPU= will be rounded up implicitly to multiples of 1s. For + LimitNICE= the value may be specified in two syntaxes: if prefixed with + + or -, 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). + + 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 LimitRSS= is not + implemented on Linux, and setting it has no effect. Often it + is advisable to prefer the resource controls listed in + systemd.resource-control5 + 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, + MemoryLimit= is a more powerful (and + working) replacement for LimitRSS=. + + + Limit directives and their equivalent with ulimit + + + + + + + + Directive + ulimit equivalent + Unit + + + + + LimitCPU= + ulimit -t + Seconds + + + LimitFSIZE= + ulimit -f + Bytes + + + LimitDATA= + ulimit -d + Bytes + + + LimitSTACK= + ulimit -s + Bytes + + + LimitCORE= + ulimit -c + Bytes + + + LimitRSS= + ulimit -m + Bytes + + + LimitNOFILE= + ulimit -n + Number of File Descriptors + + + LimitAS= + ulimit -v + Bytes + + + LimitNPROC= + ulimit -u + Number of Processes + + + LimitMEMLOCK= + ulimit -l + Bytes + + + LimitLOCKS= + ulimit -x + Number of Locks + + + LimitSIGPENDING= + ulimit -i + Number of Queued Signals + + + LimitMSGQUEUE= + ulimit -q + Bytes + + + LimitNICE= + ulimit -e + Nice Level + + + LimitRTPRIO= + ulimit -r + Realtime Priority + + + LimitRTTIME= + No equivalent + Microseconds + + + +
+ + + + PAMName= + 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 User= setting. If + not set, no PAM session will be opened for the executed + processes. See + pam8 + for details. + + + + CapabilityBoundingSet= + + Controls which capabilities to include in the capability bounding set for the executed + process. See capabilities7 for + details. Takes a whitespace-separated list of capability names as read by cap_from_name3, + e.g. CAP_SYS_ADMIN, CAP_DAC_OVERRIDE, + CAP_SYS_PTRACE. 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. 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 ~ (without any further argument), the bounding set is + reset to the full set of available capabilities, also undoing any previous settings. + + + + AmbientCapabilities= + + Controls which capabilities to include in the + ambient capability set for the executed process. Takes a + whitespace-separated list of capability names as read by + cap_from_name3, + e.g. CAP_SYS_ADMIN, + CAP_DAC_OVERRIDE, + CAP_SYS_PTRACE. This option may appear more than + once in which case the ambient capability sets are merged. + If the list of capabilities is prefixed with ~, 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 ~ (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. + + 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 keep-caps is + automatically added to SecureBits= to retain the + capabilities over the user change. + + + + SecureBits= + Controls the secure bits set for the executed + process. Takes a space-separated combination of options from + the following list: + , + , + , + , + , and + . + 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. See + capabilities7 + for details. + + + + ReadWriteDirectories= + ReadOnlyDirectories= + InaccessibleDirectories= + + Sets up a new file system namespace for + executed processes. These options may be used to limit access + a process might have to the main file system hierarchy. Each + setting takes a space-separated list of absolute directory + paths. Directories listed in + ReadWriteDirectories= are accessible from + within the namespace with the same access rights as from + outside. Directories listed in + ReadOnlyDirectories= are accessible for + reading only, writing will be refused even if the usual file + access controls would permit this. Directories listed in + InaccessibleDirectories= will be made + inaccessible for processes inside the namespace, and may not + countain any other mountpoints, including those specified by + ReadWriteDirectories= or + ReadOnlyDirectories=. + Note that restricting access with these options does not extend + to submounts of a directory that are created later on. These + options may be specified more than once, in which case all + directories 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. + Paths in + ReadOnlyDirectories= + and + InaccessibleDirectories= + may be prefixed with + -, 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. + + + + PrivateTmp= + + Takes a boolean argument. If true, sets up a + new file system namespace for the executed processes and + mounts private /tmp and + /var/tmp 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 /tmp + or /var/tmp 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 /tmp and + /var/tmp namespace by using the + JoinsNamespaceOf= directive, see + systemd.unit5 + 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. + + + + PrivateDevices= + + Takes a boolean argument. If true, sets up a + new /dev namespace for the executed processes and only adds + API pseudo devices such as /dev/null, + /dev/zero or + /dev/random (as well as the pseudo TTY + subsystem) to it, but no physical devices such as + /dev/sda. This is useful to securely turn + off physical device access by the executed process. Defaults + to false. Enabling this option will also remove + CAP_MKNOD from the capability bounding + set for the unit (see above), and set + DevicePolicy=closed (see + systemd.resource-control5 + 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 mmap2 + of /dev/zero instead of using MAP_ANON. + + + + PrivateNetwork= + + Takes a boolean argument. If true, sets up a + new network namespace for the executed processes and + configures only the loopback network device + lo 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 + JoinsNamespaceOf= directive, see + systemd.unit5 + 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). + + + + ProtectSystem= + + Takes a boolean argument or + full. If true, mounts the + /usr and /boot + directories read-only for processes invoked by this unit. If + set to full, the /etc + directory is mounted read-only, too. This setting ensures that + any modification of the vendor-supplied operating system (and + optionally its configuration) 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. Note however + that processes retaining the CAP_SYS_ADMIN capability can undo + the effect of this setting. This setting is hence particularly + useful for daemons which have this capability removed, for + example with CapabilityBoundingSet=. + Defaults to off. + + + + ProtectHome= + + Takes a boolean argument or + read-only. If true, the directories + /home, /root and + /run/user + are made inaccessible and empty for processes invoked by this + unit. If set to read-only, 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. Note however that + processes retaining the CAP_SYS_ADMIN capability can undo the + effect of this setting. This setting is hence particularly + useful for daemons which have this capability removed, for + example with CapabilityBoundingSet=. + Defaults to off. + + + + MountFlags= + + Takes a mount propagation flag: + , or + , which control whether mounts in the + file system namespace set up for this unit's processes will + receive or propagate mounts or unmounts. See + mount2 + for details. Defaults to . Use + to ensure that mounts and unmounts are + propagated from the host to the container and vice versa. Use + to run processes so that none of their + mounts and unmounts will propagate to the host. Use + to also ensure that no mounts and + unmounts from the host will propagate into the unit processes' + namespace. Note that 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 + (PrivateTmp=, + PrivateDevices=, + ProtectSystem=, + ProtectHome=, + ReadOnlyDirectories=, + InaccessibleDirectories= and + ReadWriteDirectories=) require that mount + and unmount propagation from the unit's file system namespace + is disabled, and hence downgrade to + . + + + + UtmpIdentifier= + + Takes a four character identifier string for + an utmp5 + and wtmp entry for this service. This should only be + set for services such as getty + implementations (such as agetty8) + 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 getty 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. + + + + UtmpMode= + + Takes one of init, + login or user. If + UtmpIdentifier= is set, controls which + type of utmp5/wtmp + entries for this service are generated. This setting has no + effect unless UtmpIdentifier= is set + too. If init is set, only an + INIT_PROCESS entry is generated and the + invoked process must implement a + getty-compatible utmp/wtmp logic. If + login is set, first an + INIT_PROCESS entry, followed by a + LOGIN_PROCESS entry is generated. In + this case, the invoked process must implement a login1-compatible + utmp/wtmp logic. If user is set, first an + INIT_PROCESS entry, then a + LOGIN_PROCESS entry and finally a + USER_PROCESS entry is generated. In this + case, the invoked process may be any process that is suitable + to be run as session leader. Defaults to + init. + + + + SELinuxContext= + + 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 -, all errors + will be ignored. See + setexeccon3 + for details. + + + + AppArmorProfile= + + 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 -, all errors will + be ignored. + + + + SmackProcessLabel= + + Takes a 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 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. + + The value may be prefixed by -, in + which case all errors will be ignored. An empty value may be + specified to unset previous assignments. + + + + + IgnoreSIGPIPE= + + Takes a boolean argument. If true, causes + SIGPIPE to be ignored in the executed + process. Defaults to true because SIGPIPE + generally is useful only in shell pipelines. + + + + NoNewPrivileges= + + 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, most effective + way to ensure that a process and its children can never + elevate privileges again. + + + + SystemCallFilter= + + 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 + SIGSYS signal (whitelisting). If the + first character of the list is ~, 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 + CAP_SYS_ADMIN capabiblity (e.g. setting + User=nobody), + NoNewPrivileges=yes 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 + execve, + rt_sigreturn, + sigreturn, + exit_group, exit + system calls 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. + + 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 + read and write, and + right after it add a blacklisting of + write, then write + will be removed from the set.) + + + + SystemCallErrorNumber= + + Takes an errno error number + name to return when the system call filter configured with + SystemCallFilter= is triggered, instead of + terminating the process immediately. Takes an error name such + as EPERM, EACCES or + EUCLEAN. When this setting is not used, + or when the empty string is assigned, the process will be + terminated immediately when the filter is + triggered. + + + + SystemCallArchitectures= + + Takes a space-separated list of architecture + identifiers to include in the system call filter. The known + architecture identifiers are x86, + x86-64, x32, + arm as well as the special identifier + native. 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 native 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 CAP_SYS_ADMIN + capabiblity (e.g. setting User=nobody), + NoNewPrivileges=yes is implied. Note + that setting this option to a non-empty list implies that + native is included too. By default, this + option is set to the empty list, i.e. no architecture system + call filtering is applied. + + + + RestrictAddressFamilies= + + 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 + AF_UNIX, + AF_INET or + AF_INET6. When + prefixed with ~ the listed address + families will be applied as blacklist, otherwise as whitelist. + Note that this restricts access to the + socket2 + system call only. Sockets passed into the process by other + means (for example, by using socket activation with socket + units, see + systemd.socket5) + are unaffected. Also, sockets created with + socketpair() (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 CAP_SYS_ADMIN + capabiblity (e.g. setting User=nobody), + NoNewPrivileges=yes 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. + + Use this option to limit exposure of processes to remote + systems, in particular via exotic network protocols. Note that + in most cases, the local AF_UNIX address + family should be included in the configured whitelist as it is + frequently used for local communication, including for + syslog2 + logging. + + + + Personality= + + Controls which kernel architecture uname2 shall report, + when invoked by unit processes. Takes one of the architecture identifiers x86, + x86-64, ppc, ppc-le, ppc64, + ppc64-le, s390 or s390x. 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, x86-64 systems support the x86-64 and + x86 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. + + + + RuntimeDirectory= + RuntimeDirectoryMode= + + Takes a list of directory names. If set, one + or more directories by the specified names will be created + below /run (for system services) or below + $XDG_RUNTIME_DIR (for user services) when + the unit is started, and removed when the unit is stopped. The + directories will have the access mode specified in + RuntimeDirectoryMode=, and will be owned by + the user and group specified in User= and + Group=. 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 /, i.e. + must refer to simple directories to create or remove. This is + particularly useful for unprivileged daemons that cannot + create runtime directories in /run 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 + tmpfiles.d5. + + + + + + + Environment variables in spawned processes + + 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. + + + + + $PATH + + Colon-separated list of directories to use + when launching executables. Systemd uses a fixed value of + /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin. + + + + + $LANG + + Locale. Can be set in + locale.conf5 + or on the kernel command line (see + systemd1 + and + kernel-command-line7). + + + + + $USER + $LOGNAME + $HOME + $SHELL + + User name (twice), home directory, and the + login shell. The variables are set for the units that have + User= set, which includes user + systemd instances. See + passwd5. + + + + + $XDG_RUNTIME_DIR + + The directory for volatile state. Set for the + user systemd instance, and also in user + sessions. See + pam_systemd8. + + + + + $XDG_SESSION_ID + $XDG_SEAT + $XDG_VTNR + + The identifier of the session, the seat name, + and virtual terminal of the session. Set by + pam_systemd8 + for login sessions. $XDG_SEAT and + $XDG_VTNR will only be set when attached to + a seat and a tty. + + + + $MAINPID + + The PID of the units main process if it is + known. This is only set for control processes as invoked by + ExecReload= and similar. + + + + $MANAGERPID + + The PID of the user systemd + instance, set for processes spawned by it. + + + + $LISTEN_FDS + $LISTEN_PID + $LISTEN_FDNAMES + + Information about file descriptors passed to a + service for socket activation. See + sd_listen_fds3. + + + + + $NOTIFY_SOCKET + + The socket + sd_notify() talks to. See + sd_notify3. + + + + + $WATCHDOG_PID + $WATCHDOG_USEC + + Information about watchdog keep-alive notifications. See + sd_watchdog_enabled3. + + + + + $TERM + + Terminal type, set only for units connected to + a terminal (StandardInput=tty, + StandardOutput=tty, or + StandardError=tty). See + termcap5. + + + + + Additional variables may be configured by the following + means: for processes spawned in specific units, use the + Environment=, EnvironmentFile= + and PassEnvironment= options above; to specify + variables globally, use DefaultEnvironment= + (see + systemd-system.conf5) + or the kernel option systemd.setenv= (see + systemd1). + Additional variables may also be set through PAM, + cf. pam_env8. + + + + See Also + + systemd1, + systemctl1, + journalctl8, + systemd.unit5, + systemd.service5, + systemd.socket5, + systemd.swap5, + systemd.mount5, + systemd.kill5, + systemd.resource-control5, + systemd.time7, + systemd.directives7, + tmpfiles.d5, + exec3 + + + + diff --git a/src/grp-system/systemd/systemd.generator.xml b/src/grp-system/systemd/systemd.generator.xml new file mode 100644 index 0000000000..4b80dab108 --- /dev/null +++ b/src/grp-system/systemd/systemd.generator.xml @@ -0,0 +1,348 @@ + + +%entities; +]> + + + + + + systemd.generator + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.generator + 7 + + + + systemd.generator + Systemd unit generators + + + + + /path/to/generator + normal-dir + early-dir + late-dir + + + + /run/systemd/system-generators/* +/etc/systemd/system-generators/* +/usr/local/lib/systemd/system-generators/* +&systemgeneratordir;/* + + + + /run/systemd/user-generators/* +/etc/systemd/user-generators/* +/usr/local/lib/systemd/user-generators/* +&usergeneratordir;/* + + + + + Description + Generators are small binaries that live in + &usergeneratordir;/ and other directories + listed above. + systemd1 + 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. + + 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 + system-generators/ and + user-generators/, respectively. Generators + found in directories listed earlier override the ones with the + same name in directories lower in the list. A symlink to + /dev/null 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 + /run overwrite those in + /etc. + + After installing new generators or updating the + configuration, systemctl daemon-reload may be + executed. This will delete the previous configuration created by + generators, re-run all generators, and cause + systemd to reload units from disk. See + systemctl1 + for more information. + + + + + Writing generators + + Generators are invoked with three arguments: paths to + runtime directories where generators can place their generated + unit files or symlinks. + + + + normal-dir + argv[1] may be used to override unit files in + /usr, but not those in + /etc. This means that unit files placed + in this directory take precedence over vendor unit + configuration but not over native user/administrator unit + configuration. + + + + early-dir + argv[2] may be used to override unit files in + /usr and in + /etc. This means that unit files placed + in this directory take precedence over all configuration, + both vendor and user/administrator. + + + + late-dir + 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. + + + + + + Notes + + + + + 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. + + + + + + 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 + syslog3, + or systemd itself (this means: no + systemctl1)!. + Non-essential file systems like + /var and /home + are mounted after generators have run. Generators + can however rely on the most basic kernel functionality to be + available, including a mounted /sys, + /proc, /dev, + /usr. + + + + + + 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 + systemd itself. + + + + + + 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. + + + + + + Since + syslog3 + is not available (see above), log messages have to be + written to /dev/kmsg instead. + + + + + + It is a good idea to use the + SourcePath= 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. + + + + + + Generators may write out dynamic unit files or just hook + unit files into other units with the usual + .wants/ or + .requires/ symlinks. Often, it is + nicer to simply instantiate a template unit file from + /usr with a generator instead of + writing out entirely dynamic unit files. Of course, this + works only if a single parameter is to be used. + + + + + + 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. + + + + + Regarding overriding semantics: there are two rules we + try to follow when thinking about the overriding semantics: + + + + + User configuration should override vendor + configuration. This (mostly) means that stuff from + /etc should override stuff from + /usr. + + + + Native configuration should override non-native + configuration. This (mostly) means that stuff you + generate should never override native unit files for the + same purpose. + + + + 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]. + + + + + 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. + + + + + + + + Examples + + systemd-fstab-generator + + systemd-fstab-generator8 + converts /etc/fstab into native mount + units. It uses argv[1] as location to place the generated unit + files in order to allow the user to override + /etc/fstab with her own native unit files, + but also to ensure that /etc/fstab + overrides any vendor default from /usr. + + + After editing /etc/fstab, the user + should invoke systemctl daemon-reload. This + will re-run all generators and cause systemd + to reload units from disk. To actually mount new directories + added to fstab, systemctl start + /path/to/mountpoint or + systemctl start local-fs.target may be used. + + + + + systemd-system-update-generator + + systemd-system-update-generator8 + temporarily redirects default.target to + system-update.target if a system update is + scheduled. Since this needs to override the default user + configuration for default.target, it uses + argv[2]. For details about this logic, see + Implementing + Offline System Updates. + + + + Debugging a generator + + dir=$(mktemp -d) +SYSTEMD_LOG_LEVEL=debug &systemgeneratordir;/systemd-fstab-generator \ + "$dir" "$dir" "$dir" +find $dir + + + + + See also + + + systemd1, + systemd-cryptsetup-generator8, + systemd-debug-generator8, + systemd-fstab-generator8, + fstab5, + systemd-getty-generator8, + systemd-gpt-auto-generator8, + systemd-hibernate-resume-generator8, + systemd-system-update-generator8, + systemd-sysv-generator8, + systemd.unit5, + systemctl1 + + + 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 @@ + + + + + + + + + systemd.journal-fields + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.journal-fields + 7 + + + + systemd.journal-fields + Special journal fields + + + + Description + + 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. + + + + User Journal Fields + + User fields are fields that are directly passed from clients + and stored in the journal. + + + + MESSAGE= + + 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. + + + + + MESSAGE_ID= + + 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 journalctl + . + + + + + + PRIORITY= + + A priority value between 0 (emerg) + and 7 (debug) formatted as a decimal + string. This field is compatible with syslog's priority + concept. + + + + + CODE_FILE= + CODE_LINE= + CODE_FUNC= + + The code location generating this message, if known. + Contains the source filename, the line number and the + function name. + + + + + ERRNO= + + The low-level Unix error number causing this entry, if + any. Contains the numeric value of + errno3 + formatted as a decimal string. + + + + + SYSLOG_FACILITY= + SYSLOG_IDENTIFIER= + SYSLOG_PID= + + 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 + program_invocation_short_name variable, + see + program_invocation_short_name3.) + + + + + + + + Trusted Journal Fields + + 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. + + + + _PID= + _UID= + _GID= + + The process, user, and group ID of the process the + journal entry originates from formatted as a decimal + string. + + + + + _COMM= + _EXE= + _CMDLINE= + + The name, the executable path, and the command line of + the process the journal entry originates from. + + + + + _CAP_EFFECTIVE= + + The effective + capabilities7 + of the process the journal entry originates from. + + + + + _AUDIT_SESSION= + _AUDIT_LOGINUID= + + The session and login UID of the process the journal + entry originates from, as maintained by the kernel audit + subsystem. + + + + + _SYSTEMD_CGROUP= + _SYSTEMD_SESSION= + _SYSTEMD_UNIT= + _SYSTEMD_USER_UNIT= + _SYSTEMD_OWNER_UID= + _SYSTEMD_SLICE= + + + 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. + + + + + _SELINUX_CONTEXT= + + The SELinux security context (label) of the process + the journal entry originates from. + + + + + _SOURCE_REALTIME_TIMESTAMP= + + 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. + + + + + _BOOT_ID= + + The kernel boot ID for the boot the message was + generated in, formatted as a 128-bit hexadecimal + string. + + + + + _MACHINE_ID= + + The machine ID of the originating host, as available + in + machine-id5. + + + + + _HOSTNAME= + + The name of the originating host. + + + + + _TRANSPORT= + + How the entry was received by the journal service. + Valid transports are: + + + + + + + + for those read from the kernel audit subsystem + + + + + + + + + + for internally generated messages + + + + + + + + + + for those received via the local syslog socket + with the syslog protocol + + + + + + + + + + for those received via the native journal + protocol + + + + + + + + + + for those read from a service's standard output + or error output + + + + + + + + + + for those read from the kernel + + + + + + + + + + + Kernel Journal Fields + + Kernel fields are fields that are used by messages + originating in the kernel and stored in the journal. + + + + _KERNEL_DEVICE= + + The kernel device name. If the entry is associated to + a block device, the major and minor of the device node, + separated by : and prefixed by + b. Similar for character devices but + prefixed by c. For network devices, this + is the interface index prefixed by n. For + all other devices, this is the subsystem name prefixed by + +, followed by :, + followed by the kernel device name. + + + + _KERNEL_SUBSYSTEM= + + The kernel subsystem name. + + + + _UDEV_SYSNAME= + + The kernel device name as it shows up in the device + tree below /sys. + + + + _UDEV_DEVNODE= + + The device node path of this device in + /dev. + + + + _UDEV_DEVLINK= + + Additional symlink names pointing to the device node + in /dev. This field is frequently set + more than once per entry. + + + + + + + Fields to log on behalf of a different program + + Fields in this section are used by programs to specify that + they are logging on behalf of another program or unit. + + + Fields used by the systemd-coredump + coredump kernel helper: + + + + + COREDUMP_UNIT= + COREDUMP_USER_UNIT= + + Used to annotate messages containing coredumps from + system and session units. See + coredumpctl1. + + + + + + Privileged programs (currently UID 0) may attach + OBJECT_PID= to a message. This will instruct + systemd-journald to attach additional fields on + behalf of the caller: + + + + OBJECT_PID=PID + + PID of the program that this message pertains to. + + + + + + OBJECT_UID= + OBJECT_GID= + OBJECT_COMM= + OBJECT_EXE= + OBJECT_CMDLINE= + OBJECT_AUDIT_SESSION= + OBJECT_AUDIT_LOGINUID= + OBJECT_SYSTEMD_CGROUP= + OBJECT_SYSTEMD_SESSION= + OBJECT_SYSTEMD_OWNER_UID= + OBJECT_SYSTEMD_UNIT= + OBJECT_SYSTEMD_USER_UNIT= + + These are additional fields added automatically by + systemd-journald. Their meaning is the + same as + _UID=, + _GID=, + _COMM=, + _EXE=, + _CMDLINE=, + _AUDIT_SESSION=, + _AUDIT_LOGINUID=, + _SYSTEMD_CGROUP=, + _SYSTEMD_SESSION=, + _SYSTEMD_UNIT=, + _SYSTEMD_USER_UNIT=, and + _SYSTEMD_OWNER_UID= + as described above, except that the process identified by + PID is described, instead of the + process which logged the message. + + + + + + + + Address Fields + + During serialization into external formats, such as the + Journal + Export Format or the Journal + JSON Format, 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 + sd_journal_send3. + They may also not be used as matches for + sd_journal_add_match3 + + + + __CURSOR= + + 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. + + + + + + __REALTIME_TIMESTAMP= + + The wallclock time + (CLOCK_REALTIME) 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 + _SOURCE_REALTIME_TIMESTAMP=, as it is + usually a bit later but more likely to be monotonic. + + + + + + __MONOTONIC_TIMESTAMP= + + The monotonic time + (CLOCK_MONOTONIC) 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 + _BOOT_ID=. + + + + + + + + See Also + + systemd1, + journalctl1, + journald.conf5, + sd-journal3, + coredumpctl1, + systemd.directives7 + + + + 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 @@ + + + + + + + + systemd.kill + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.kill + 5 + + + + systemd.kill + Process killing procedure + configuration + + + + service.service, + socket.socket, + mount.mount, + swap.swap, + scope.scope + + + + Description + + 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. + + This man page lists the configuration options shared by + these five unit types. See + systemd.unit5 + for the common options shared by all unit configuration files, and + systemd.service5, + systemd.socket5, + systemd.swap5, + systemd.mount5 + and + systemd.scope5 + for more information on the configuration file options specific to + each unit type. + + The kill procedure configuration options are configured in + the [Service], [Socket], [Mount] or [Swap] section, depending on + the unit type. + + + + Options + + + + + KillMode= + Specifies how processes of this unit shall be + killed. One of + , + , + , + . + + If set to , 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 ExecStop=). If set to + , only the main process itself is + killed. If set to , the + SIGTERM signal (see below) is sent to the + main process while the subsequent SIGKILL + signal (see below) is sent to all remaining processes of the + unit's control group. If set to , 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. + + Processes will first be terminated via + SIGTERM (unless the signal to send is + changed via KillSignal=). Optionally, this + is immediately followed by a SIGHUP (if + enabled with SendSIGHUP=). If then, after a + delay (configured via the TimeoutStopSec= + option), processes still remain, the termination request is + repeated with the SIGKILL signal (unless + this is disabled via the SendSIGKILL= + option). See + kill2 + for more information. + + Defaults to + . + + + + KillSignal= + 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 SIGKILL (see above and below). For a + list of valid signals, see + signal7. + Defaults to SIGTERM. + + Note that, right after sending the signal specified in + this setting, systemd will always send + SIGCONT, to ensure that even suspended + tasks can be terminated cleanly. + + + + + SendSIGHUP= + Specifies whether to send + SIGHUP to remaining processes immediately + after sending the signal configured with + KillSignal=. This is useful to indicate to + shells and shell-like programs that their connection has been + severed. Takes a boolean value. Defaults to "no". + + + + + SendSIGKILL= + Specifies whether to send + SIGKILL to remaining processes after a + timeout, if the normal shutdown procedure left processes of + the service around. Takes a boolean value. Defaults to "yes". + + + + + + + + See Also + + systemd1, + systemctl1, + journalctl8, + systemd.unit5, + systemd.service5, + systemd.socket5, + systemd.swap5, + systemd.mount5, + systemd.exec5, + systemd.directives7, + kill2, + signal7 + + + + diff --git a/src/grp-system/systemd/systemd.link.xml b/src/grp-system/systemd/systemd.link.xml new file mode 100644 index 0000000000..d5b4d1038d --- /dev/null +++ b/src/grp-system/systemd/systemd.link.xml @@ -0,0 +1,477 @@ + + + + + + + + systemd.link + systemd + + + + Developer + Tom + Gundersen + + + + + + systemd.link + 5 + + + + systemd.link + Network device configuration + + + + link.link + + + + Description + + Network link configuration is performed by the + net_setup_link udev builtin. + + The link files are read from the files located in the system + network directory /usr/lib/systemd/network, + the volatile runtime network directory + /run/systemd/network, and the local + administration network directory + /etc/systemd/network. Link files must have + the extension .link; 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 /etc have the highest priority, files in + /run take precedence over files with the same + name in /usr/lib. 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 /dev/null disables the + configuration file entirely (it is "masked"). + + The link file contains a [Match] section, + which determines if a given link file may be applied to a given + device, as well as a [Link] 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 99-default.link is + shipped by the system, any user-supplied + .link should hence have a lexically earlier + name to be considered at all. + + See + udevadm8 + for diagnosing problems with .link files. + + + + [Match] Section Options + + A link file is said to match a device if each of the entries + in the [Match] section matches, or if the + section is empty. The following keys are accepted: + + + + MACAddress= + + The hardware address. + + + + OriginalName= + + A whitespace-separated list of shell-style globs matching + the device name, as exposed by the udev property + "INTERFACE". This can not 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. + + + + Path= + + A whitespace-separated list of shell-style globs matching + the persistent path, as exposed by the udev property + ID_PATH. + + + + Driver= + + A whitespace-separated list of shell-style globs matching + the driver currently bound to the device, + as exposed by the udev property DRIVER + of its parent device, or if that is not set, the + driver as exposed by ethtool -i + of the device itself. + + + + Type= + + A whitespace-separated list of shell-style globs matching + the device type, as exposed by the udev + property DEVTYPE. + + + + Host= + + Matches against the hostname or machine + ID of the host. See ConditionHost= in + systemd.unit5 + for details. + + + + Virtualization= + + Checks whether the system is executed in + a virtualized environment and optionally test + whether it is a specific implementation. See + ConditionVirtualization= in + systemd.unit5 + for details. + + + + KernelCommandLine= + + Checks whether a specific kernel command line option + is set (or if prefixed with the exclamation mark unset). See + ConditionKernelCommandLine= in + systemd.unit5 + for details. + + + + Architecture= + + Checks whether the system is running on a specific + architecture. See ConditionArchitecture= + in + systemd.unit5 + for details. + + + + + + + + [Link] Section Options + + The [Link] section accepts the following + keys: + + + + Description= + + A description of the device. + + + + Alias= + + The ifalias is set to this + value. + + + + MACAddressPolicy= + + The policy by which the MAC address should be set. The + available policies are: + + + + + persistent + + 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. + + + + random + + 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 + unicast and + locally administered bits set. + + + + none + + Keeps the MAC address assigned by the kernel. + + + + + + + MACAddress= + + The MAC address to use, if no + MACAddressPolicy= + is specified. + + + + NamePolicy= + + An ordered, space-separated list of policies by which + the interface name should be set. + NamePolicy may be disabled by specifying + net.ifnames=0 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 ID_NET_NAME, which + is, by default, used by a udev rule to set + NAME. If the name has already been set by + userspace, no renaming is performed. The available policies + are: + + + + kernel + + If the kernel claims that the name it has set + for a device is predictable, then no renaming is + performed. + + + + database + + The name is set based on entries in the udev's + Hardware Database with the key + ID_NET_NAME_FROM_DATABASE. + + + + + onboard + + The name is set based on information given by + the firmware for on-board devices, as exported by the + udev property ID_NET_NAME_ONBOARD. + + + + + slot + + The name is set based on information given by + the firmware for hot-plug devices, as exported by the + udev property ID_NET_NAME_SLOT. + + + + + path + + The name is set based on the device's physical + location, as exported by the udev property + ID_NET_NAME_PATH. + + + + mac + + The name is set based on the device's persistent + MAC address, as exported by the udev property + ID_NET_NAME_MAC. + + + + + + + Name= + + The interface name to use in case all the + policies specified in + NamePolicy= fail, or in case + NamePolicy= is missing or + disabled. + + + + MTUBytes= + + 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. + + + + BitsPerSecond= + + 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. + + + + Duplex= + + The duplex mode to set for the device. The accepted + values are half and + full. + + + + WakeOnLan= + + The Wake-on-LAN policy to set for the device. The + supported values are: + + + + phy + + Wake on PHY activity. + + + + magic + + Wake on receipt of a magic packet. + + + + + off + + Never wake. + + + + + + + + + + Examples + + + /usr/lib/systemd/network/99-default.link + + The link file 99-default.link that is + shipped with systemd defines the default naming policy for + links. + + [Link] +NamePolicy=kernel database onboard slot path +MACAddressPolicy=persistent + + + + /etc/systemd/network/10-dmz.link + + This example assigns the fixed name + dmz0 to the interface with the MAC address + 00:a0:de:63:7a:e6: + + [Match] +MACAddress=00:a0:de:63:7a:e6 + +[Link] +Name=dmz0 + + + + /etc/systemd/network/10-internet.link + + This example assigns the fixed name + internet0 to the interface with the device + path pci-0000:00:1a.0-*: + + [Match] +Path=pci-0000:00:1a.0-* + +[Link] +Name=internet0 + + + + /etc/systemd/network/25-wireless.link + + Here's an overly complex example that shows the use of a large number of [Match] and [Link] settings. + + [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 + + + + + See Also + + + systemd-udevd.service8 + , + + udevadm8 + , + + systemd.netdev5 + , + + systemd.network5 + + + + + diff --git a/src/grp-system/systemd/systemd.mount.xml b/src/grp-system/systemd/systemd.mount.xml new file mode 100644 index 0000000000..66cddd72e0 --- /dev/null +++ b/src/grp-system/systemd/systemd.mount.xml @@ -0,0 +1,406 @@ + + + + + + + + systemd.mount + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.mount + 5 + + + + systemd.mount + Mount unit configuration + + + + mount.mount + + + + Description + + A unit configuration file whose name ends in + .mount encodes information about a file system + mount point controlled and supervised by systemd. + + This man page lists the configuration options specific to + this unit type. See + systemd.unit5 + 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. + + Additional options are listed in + systemd.exec5, + which define the execution environment the + mount8 + binary is executed in, and in + systemd.kill5, + which define the way the processes are terminated, and in + systemd.resource-control5, + 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 + Type= option or using configuration not + specified in /etc/fstab; + mount8 + will refuse options that are not listed in + /etc/fstab if it is not run as UID 0. + + Mount units must be named after the mount point directories they control. Example: the mount point /home/lennart must be configured in a unit file home-lennart.mount. + For details about the escaping logic used to convert a file system path to a unit name, see + systemd.unit5. Note that mount + units cannot be templated, nor is possible to add multiple names to a mount unit by creating additional symlinks to + it. + + Optionally, a mount unit may be accompanied by an automount + unit, to allow on-demand or parallelized mounting. See + systemd.automount5. + + Mount points created at runtime (independently of unit files + or /etc/fstab) will be monitored by systemd + and appear like any other mount unit in systemd. See + /proc/self/mountinfo description in + proc5. + + + 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 API + File Systems. + + + + Automatic Dependencies + + 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. + + Block device backed file systems automatically gain + BindsTo= and After= type + dependencies on the device unit encapsulating the block + device (see below). + + If traditional file system quota is enabled for a mount + unit, automatic Wants= and + Before= dependencies on + systemd-quotacheck.service and + quotaon.service are added. + + For mount units with DefaultDependencies=yes in the [Unit] section (the + default) a couple additional dependencies are added. Mount units referring to local file systems automatically gain + an After= dependency on local-fs-pre.target. Network mount units + automatically acquire After= dependencies on remote-fs-pre.target, + network.target and network-online.target. Towards the latter a + Wants= 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 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 Before= and Conflicts= on + umount.target in order to be stopped during shutdown. + + Additional implicit dependencies may be added as result of + execution and resource control parameters as documented in + systemd.exec5 + and + systemd.resource-control5. + + + + <filename>fstab</filename> + + Mount units may either be configured via unit files, or via + /etc/fstab (see + fstab5 + for details). Mounts listed in /etc/fstab + 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 /etc/fstab + is the preferred approach. See + systemd-fstab-generator8 + for details about the conversion. + + The NFS mount option for NFS background mounts + as documented in nfs5 + is not supported in /etc/fstab entries. The systemd mount option + provides similar functionality and should be used instead. + + When reading /etc/fstab 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 Wants= or + (see option + below), from either local-fs.target or + remote-fs.target, depending whether the file + system is local or remote. + + + + + + + Configures a Requires= and + an After= 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 + After= and Requires= in + systemd.unit5 + for details. + + + + + + Configures a + RequiresMountsFor= 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 RequiresMountsFor= in + systemd.unit5 + for details. + + + + + + An automount unit will be created for the file + system. See + systemd.automount5 + for details. + + + + + + Configures the idle timeout of the + automount unit. See TimeoutIdleSec= in + systemd.automount5 + for details. + + + + + + Configure how long systemd should wait for a + device to show up before giving up on an entry from + /etc/fstab. Specify a time in seconds or + explicitly append a unit such as s, + min, h, + ms. + + Note that this option can only be used in + /etc/fstab, and will be + ignored when part of the Options= + setting in a unit file. + + + + + + + + With , this mount will + not be added as a dependency for + local-fs.target or + remote-fs.target. This means that it will + not be mounted automatically during boot, unless it is pulled + in by some other unit. The option has the + opposite meaning and is the default. + + + + + + + With , this mount will + be only wanted, not required, by + local-fs.target or + remote-fs.target. This means that the + boot will continue even if this mount point is not mounted + successfully. + + + + + + + An additional filesystem to be mounted in the + initramfs. See initrd-fs.target + description in + systemd.special7. + + + + + If a mount point is configured in both + /etc/fstab and a unit file that is stored + below /usr, the former will take precedence. + If the unit file is stored below /etc, 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 + /etc will always take precedence over + configuration in /usr. + + + + Options + + 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 + systemd.exec5 + and + systemd.kill5. + The options specific to the [Mount] section of mount units are the + following: + + + + + What= + Takes an absolute path of a device node, file + or other resource to mount. See + mount8 + for details. If this refers to a device node, a dependency on + the respective device unit is automatically created. (See + systemd.device5 + for more information.) This option is + mandatory. + + + + Where= + 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. + + + + Type= + Takes a string for the file system type. See + mount8 + for details. This setting is optional. + + + + Options= + + Mount options to use when mounting. This takes + a comma-separated list of options. This setting is + optional. + + + + SloppyOptions= + + Takes a boolean argument. If true, parsing of + the options specified in Options= is + relaxed, and unknown mount options are tolerated. This + corresponds with + mount8's + -s switch. Defaults to + off. + + + + DirectoryMode= + 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. + + + + TimeoutSec= + 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 SIGTERM, and after another + delay of this time with SIGKILL. (See + in + systemd.kill5.) + 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 + DefaultTimeoutStart= + variable. + + + + Check + systemd.exec5 + and + systemd.kill5 + for more settings. + + + + See Also + + systemd1, + systemctl1, + systemd.unit5, + systemd.exec5, + systemd.kill5, + systemd.resource-control5, + systemd.service5, + systemd.device5, + proc5, + mount8, + systemd-fstab-generator8, + systemd.directives7 + + + + diff --git a/src/grp-system/systemd/systemd.netdev.xml b/src/grp-system/systemd/systemd.netdev.xml new file mode 100644 index 0000000000..8d12c305d2 --- /dev/null +++ b/src/grp-system/systemd/systemd.netdev.xml @@ -0,0 +1,1116 @@ + + + + + + + + + systemd.network + systemd + + + + Developer + Tom + Gundersen + teg@jklm.no + + + + + + systemd.netdev + 5 + + + + systemd.netdev + Virtual Network Device configuration + + + + netdev.netdev + + + + Description + + Network setup is performed by + systemd-networkd8. + + + Virtual Network Device files must have the extension + .netdev; 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. + + The .netdev files are read from the + files located in the system network directory + /usr/lib/systemd/network, the volatile + runtime network directory + /run/systemd/network and the local + administration network directory + /etc/systemd/network. 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 + /etc have the highest priority, files in + /run take precedence over files with the same + name in /usr/lib. 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 /dev/null + disables the configuration file entirely (it is "masked"). + + + + Supported netdev kinds + + The following kinds of virtual network devices may be + configured in .netdev files: + + + Supported kinds of virtual network devices + + + + + + Kind + Description + + + bond + A bond device is an aggregation of all its slave devices. See Linux Ethernet Bonding Driver HOWTO for details.Local configuration + + bridge + A bridge device is a software switch, and each of its slave devices and the bridge itself are ports of the switch. + + dummy + A dummy device drops all packets sent to it. + + gre + A Level 3 GRE tunnel over IPv4. See RFC 2784 for details. + + gretap + A Level 2 GRE tunnel over IPv4. + + ip6gre + A Level 3 GRE tunnel over IPv6. + + ip6tnl + An IPv4 or IPv6 tunnel over IPv6 + + ip6gretap + An Level 2 GRE tunnel over IPv6. + + ipip + An IPv4 over IPv4 tunnel. + + ipvlan + An ipvlan device is a stacked device which receives packets from its underlying device based on IP address filtering. + + macvlan + A macvlan device is a stacked device which receives packets from its underlying device based on MAC address filtering. + + macvtap + A macvtap device is a stacked device which receives packets from its underlying device based on MAC address filtering. + + sit + An IPv6 over IPv4 tunnel. + + tap + A persistent Level 2 tunnel between a network device and a device node. + + tun + A persistent Level 3 tunnel between a network device and a device node. + + veth + An Ethernet tunnel between a pair of network devices. + + vlan + A VLAN is a stacked device which receives packets from its underlying device based on VLAN tagging. See IEEE 802.1Q for details. + + vti + An IPv4 over IPSec tunnel. + + vti6 + An IPv6 over IPSec tunnel. + + vxlan + A virtual extensible LAN (vxlan), for connecting Cloud computing deployments. + + +
+ + + + + [Match] Section Options + + A virtual network device is only created if the + [Match] section matches the current + environment, or if the section is empty. The following keys are + accepted: + + + + Host= + + Matches against the hostname or machine ID of the + host. See ConditionHost= in + systemd.unit5 + for details. + + + + + Virtualization= + + Checks whether the system is executed in a virtualized + environment and optionally test whether it is a specific + implementation. See + ConditionVirtualization= in + systemd.unit5 + for details. + + + + + KernelCommandLine= + + Checks whether a specific kernel command line option + is set (or if prefixed with the exclamation mark unset). See + ConditionKernelCommandLine= in + systemd.unit5 + for details. + + + + + Architecture= + + Checks whether the system is running on a specific + architecture. See ConditionArchitecture= in + systemd.unit5 + for details. + + + + + + + + + [NetDev] Section Options + + The [NetDev] section accepts the + following keys: + + + + Description= + + A free-form description of the netdev. + + + + Name= + + The interface name used when creating the netdev. + This option is compulsory. + + + + Kind= + + The netdev kind. This option is compulsory. See the + Supported netdev kinds section for the + valid keys. + + + + MTUBytes= + + 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 tun or + tap devices. + + + + + MACAddress= + + The MAC address to use for the device. If none is + given, one is generated based on the interface name and + the + machine-id5. + This key is not currently supported for + tun or tap devices. + + + + + + + + [Bridge] Section Options + + The [Bridge] section only applies for + netdevs of kind bridge, and accepts the + following keys: + + + + HelloTimeSec= + + 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. + + + + MaxAgeSec= + + 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. + + + + ForwardDelaySec= + + ForwardDelaySec specifies the number of seconds spent in each + of the Listening and Learning states before the Forwarding state is entered. + + + + MulticastQuerier= + + 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. + + + + + MulticastSnooping= + + 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. + + + + + + + + + [VLAN] Section Options + + The [VLAN] section only applies for + netdevs of kind vlan, and accepts the + following key: + + + + Id= + + The VLAN ID to use. An integer in the range 0–4094. + This option is compulsory. + + + + + + + + [MACVLAN] Section Options + + The [MACVLAN] section only applies for + netdevs of kind macvlan, and accepts the + following key: + + + + Mode= + + The MACVLAN mode to use. The supported options are + private, + vepa, + bridge, and + passthru. + + + + + + + + + [MACVTAP] Section Options + + The [MACVTAP] section applies for + netdevs of kind macvtap and accepts the + same key as [MACVLAN]. + + + + + [IPVLAN] Section Options + + The [IPVLAN] section only applies for + netdevs of kind ipvlan, and accepts the + following key: + + + + Mode= + + The IPVLAN mode to use. The supported options are + L2 and L3. + + + + + + + + + [VXLAN] Section Options + The [VXLAN] section only applies for + netdevs of kind vxlan, and accepts the + following keys: + + + + Id= + + The VXLAN ID to use. + + + + Group= + + An assigned multicast group IP address. + + + + TOS= + + The Type Of Service byte value for a vxlan interface. + + + + TTL= + + 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. + + + + MacLearning= + + A boolean. When true, enables dynamic MAC learning + to discover remote MAC addresses. + + + + FDBAgeingSec= + + The lifetime of Forwarding Database entry learnt by + the kernel, in seconds. + + + + MaximumFDBEntries= + + Configures maximum number of FDB entries. + + + + ARPProxy= + + A boolean. When true, enables ARP proxying. + + + + L2MissNotification= + + A boolean. When true, enables netlink LLADDR miss + notifications. + + + + L3MissNotification= + + A boolean. When true, enables netlink IP address miss + notifications. + + + + RouteShortCircuit= + + A boolean. When true, route short circuiting is turned + on. + + + + UDPCheckSum= + + A boolean. When true, transmitting UDP checksums when doing VXLAN/IPv4 is turned on. + + + + UDP6ZeroChecksumTx= + + A boolean. When true, sending zero checksums in VXLAN/IPv6 is turned on. + + + + UDP6ZeroCheckSumRx= + + A boolean. When true, receiving zero checksums in VXLAN/IPv6 is turned on. + + + + GroupPolicyExtension= + + 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 + + VXLAN Group Policy document. Defaults to false. + + + + DestinationPort= + + 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. + + + + PortRange= + + 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. + + + + + + [Tunnel] Section Options + + The [Tunnel] section only applies for + netdevs of kind + ipip, + sit, + gre, + gretap, + ip6gre, + ip6gretap, + vti, + vti6, and + ip6tnl and accepts + the following keys: + + + + Local= + + A static local address for tunneled packets. It must + be an address on another interface of this host. + + + + Remote= + + The remote endpoint of the tunnel. + + + + TOS= + + The Type Of Service byte value for a tunnel interface. + For details about the TOS, see the + Type of + Service in the Internet Protocol Suite document. + + + + + TTL= + + 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. + + + + DiscoverPathMTU= + + A boolean. When true, enables Path MTU Discovery on + the tunnel. + + + + IPv6FlowLabel= + + Configures the 20-bit flow label (see + RFC 6437) field in the IPv6 header (see + RFC 2460), 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 inherit, in which case the original flowlabel is used. + + + + CopyDSCP= + + 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 no. + + + + + EncapsulationLimit= + + 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 RFC 2473). + The valid range is 0–255 and none. Defaults to 4. + + + + + Mode= + + An ip6tnl tunnel can be in one of three + modes + ip6ip6 for IPv6 over IPv6, + ipip6 for IPv4 over IPv6 or + any for either. + + + + + + + [Peer] Section Options + + The [Peer] section only applies for + netdevs of kind veth and accepts the + following keys: + + + + Name= + + The interface name used when creating the netdev. + This option is compulsory. + + + + MACAddress= + + The peer MACAddress, if not set, it is generated in + the same way as the MAC address of the main + interface. + + + + + + [Tun] Section Options + + The [Tun] section only applies for + netdevs of kind tun, and accepts the following + keys: + + + + OneQueue= + 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 + qdisc. Defaults to + no. + + + + MultiQueue= + Takes a boolean argument. Configures whether + to use multiple file descriptors (queues) to parallelize + packets sending and receiving. Defaults to + no. + + + + PacketInfo= + 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 + no. + + + + VNetHeader= + 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 + no. + + + + User= + User to grant access to the + /dev/net/tun device. + + + + Group= + Group to grant access to the + /dev/net/tun device. + + + + + + + + + [Tap] Section Options + + The [Tap] section only applies for + netdevs of kind tap, and accepts the same keys + as the [Tun] section. + + + + [Bond] Section Options + + The [Bond] section accepts the following + key: + + + + Mode= + + Specifies one of the bonding policies. The default is + balance-rr (round robin). Possible values are + balance-rr, + active-backup, + balance-xor, + broadcast, + 802.3ad, + balance-tlb, and + balance-alb. + + + + + + TransmitHashPolicy= + + Selects the transmit hash policy to use for slave + selection in balance-xor, 802.3ad, and tlb modes. Possible + values are + layer2, + layer3+4, + layer2+3, + encap2+3, + 802.3ad, and + encap3+4. + + + + + + LACPTransmitRate= + + Specifies the rate with which link partner transmits + Link Aggregation Control Protocol Data Unit packets in + 802.3ad mode. Possible values are slow, + which requests partner to transmit LACPDUs every 30 seconds, + and fast, which requests partner to + transmit LACPDUs every second. The default value is + slow. + + + + + MIIMonitorSec= + + 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. + + + + + UpDelaySec= + + 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. + + + + + DownDelaySec= + + 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. + + + + + LearnPacketIntervalSec= + + 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. + + + + + AdSelect= + + Specifies the 802.3ad aggregation selection logic to use. Possible values are + stable, + bandwidth and + count. + + + + + + FailOverMACPolicy= + + 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 + none, + active and + follow. + + + + + + ARPValidate= + + 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 + none, + active, + backup and + all. + + + + + + ARPIntervalSec= + + Specifies the ARP link monitoring frequency in milliseconds. + A value of 0 disables ARP monitoring. The default value is 0. + + + + + + ARPIPTargets= + + 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. + + + + + + ARPAllTargets= + + 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 + any and + all. + + + + + + PrimaryReselectPolicy= + + 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 + always, + better and + failure. + + + + + + ResendIGMP= + + 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. + + + + + + PacketsPerSlave= + + 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. + + + + + + GratuitousARP= + + 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. + + + + + + AllSlavesActive= + + 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). + + + + + + MinLinks= + + Specifies the minimum number of links that must be active before + asserting carrier. The default value is 0. + + + + + + + For more detail information see + + Linux Ethernet Bonding Driver HOWTO + + + + + Example + + /etc/systemd/network/25-bridge.netdev + + [NetDev] +Name=bridge0 +Kind=bridge + + + + /etc/systemd/network/25-vlan1.netdev + + [Match] +Virtualization=no + +[NetDev] +Name=vlan1 +Kind=vlan + +[VLAN] +Id=1 + + + /etc/systemd/network/25-ipip.netdev + [NetDev] +Name=ipip-tun +Kind=ipip +MTUBytes=1480 + +[Tunnel] +Local=192.168.223.238 +Remote=192.169.224.239 +TTL=64 + + + /etc/systemd/network/25-tap.netdev + [NetDev] +Name=tap-test +Kind=tap + +[Tap] +MultiQueue=true +PacketInfo=true + + + /etc/systemd/network/25-sit.netdev + [NetDev] +Name=sit-tun +Kind=sit +MTUBytes=1480 + +[Tunnel] +Local=10.65.223.238 +Remote=10.65.223.239 + + + + /etc/systemd/network/25-gre.netdev + [NetDev] +Name=gre-tun +Kind=gre +MTUBytes=1480 + +[Tunnel] +Local=10.65.223.238 +Remote=10.65.223.239 + + + + /etc/systemd/network/25-vti.netdev + + [NetDev] +Name=vti-tun +Kind=vti +MTUBytes=1480 + +[Tunnel] +Local=10.65.223.238 +Remote=10.65.223.239 + + + + /etc/systemd/network/25-veth.netdev + [NetDev] +Name=veth-test +Kind=veth + +[Peer] +Name=veth-peer + + + + /etc/systemd/network/25-bond.netdev + [NetDev] +Name=bond1 +Kind=bond + +[Bond] +Mode=802.3ad +TransmitHashPolicy=layer3+4 +MIIMonitorSec=1s +LACPTransmitRate=fast + + + + + /etc/systemd/network/25-dummy.netdev + [NetDev] +Name=dummy-test +Kind=dummy +MACAddress=12:34:56:78:9a:bc + + + + + See Also + + systemd1, + systemd-networkd8, + systemd.link5, + systemd.network5 + + + + diff --git a/src/grp-system/systemd/systemd.network.xml b/src/grp-system/systemd/systemd.network.xml new file mode 100644 index 0000000000..821e22aff8 --- /dev/null +++ b/src/grp-system/systemd/systemd.network.xml @@ -0,0 +1,1205 @@ + + + + + + + + + systemd.network + systemd + + + + Developer + Tom + Gundersen + teg@jklm.no + + + + + + systemd.network + 5 + + + + systemd.network + Network configuration + + + + network.network + + + + Description + + Network setup is performed by + systemd-networkd8. + + + Network files must have the extension + .network; other extensions are ignored. + Networks are applied to links whenever the links appear. + + The .network files are read from the + files located in the system network directory + /usr/lib/systemd/network, the volatile + runtime network directory + /run/systemd/network and the local + administration network directory + /etc/systemd/network. 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 + /etc have the highest priority, files in + /run take precedence over files with the same + name in /usr/lib. 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 /dev/null + disables the configuration file entirely (it is "masked"). + + 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 /proc/sys/net/ipv6/conf/ifname/disable_ipv6. + + + + + [Match] Section Options + + The network file contains a [Match] + section, which determines if a given network file may be applied + to a given device; and a [Network] 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. + + A network file is said to match a device if each of the + entries in the [Match] section matches, or if + the section is empty. The following keys are accepted: + + + + MACAddress= + + The hardware address of the interface (use full colon-delimited hexadecimal, e.g., + 01:23:45:67:89:ab). + + + + Path= + + A whitespace-separated list of shell-style globs + matching the persistent path, as exposed by the udev + property ID_PATH. + + + + Driver= + + A whitespace-separated list of shell-style globs + matching the driver currently bound to the device, as + exposed by the udev property DRIVER + of its parent device, or if that is not set the driver + as exposed by ethtool -i of the + device itself. + + + + Type= + + A whitespace-separated list of shell-style globs + matching the device type, as exposed by the udev property + DEVTYPE. + + + + Name= + + A whitespace-separated list of shell-style globs + matching the device name, as exposed by the udev property + INTERFACE. + + + + Host= + + Matches against the hostname or machine ID of the + host. See ConditionHost= in + systemd.unit5 + for details. + + + + + Virtualization= + + Checks whether the system is executed in a virtualized + environment and optionally test whether it is a specific + implementation. See ConditionVirtualization= in + systemd.unit5 + for details. + + + + + KernelCommandLine= + + Checks whether a specific kernel command line option is + set (or if prefixed with the exclamation mark unset). See + ConditionKernelCommandLine= in + systemd.unit5 + for details. + + + + + Architecture= + + Checks whether the system is running on a specific + architecture. See ConditionArchitecture= in + systemd.unit5 + for details. + + + + + + + + + [Link] Section Options + + The [Link] section accepts the following keys: + + + + MACAddress= + + The hardware address to set for the device. + + + + MTUBytes= + + 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. + 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. + + + + + + + [Network] Section Options + + The [Network] section accepts the following keys: + + + + Description= + + A description of the device. This is only used for + presentation purposes. + + + + DHCP= + + Enables DHCPv4 and/or DHCPv6 client support. Accepts + yes, no, + ipv4, or ipv6. + + 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 + IPv6AcceptRouterAdvertisements=. + + Furthermore, note that by default the domain name + specified through DHCP is not used for name resolution. + See option below. + + See the [DHCP] section below for further configuration options for the DHCP client + support. + + + + DHCPServer= + + A boolean. Enables DHCPv4 server support. Defaults + to no. Further settings for the DHCP + server may be set in the [DHCPServer] + section described below. + + + + LinkLocalAddressing= + + Enables link-local address autoconfiguration. Accepts + yes, no, + ipv4, or ipv6. Defaults to + ipv6. + + + + IPv4LLRoute= + + A boolean. When true, sets up the route needed for + non-IPv4LL hosts to communicate with IPv4LL-only hosts. Defaults + to false. + + + + + IPv6Token= + + 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. + + + + LLMNR= + + A boolean or resolve. When true, + enables Link-Local + Multicast Name Resolution on the link. When set to + resolve, only resolution is enabled, + but not host registration and announcement. Defaults to + true. This setting is read by + systemd-resolved.service8. + + + + MulticastDNS= + + A boolean or resolve. When true, + enables Multicast + DNS support on the link. When set to + resolve, only resolution is enabled, + but not host or service registration and + announcement. Defaults to false. This setting is read by + systemd-resolved.service8. + + + + DNSSEC= + + A boolean or + allow-downgrade. When true, enables + DNSSEC + DNS validation support on the link. When set to + allow-downgrade, compatibility with + non-DNSSEC capable networks is increased, by automatically + turning off DNSEC in this case. This option defines a + per-interface setting for + resolved.conf5's + global DNSSEC= option. Defaults to + false. This setting is read by + systemd-resolved.service8. + + + + DNSSECNegativeTrustAnchors= + 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 + systemd-resolved.service8. + + + + LLDP= + + 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 + routers-only. When true, incoming LLDP packets are accepted and a database of all LLDP + neighbors maintained. If routers-only 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 routers-only. Use + networkctl1 to query the + collected neighbor data. LLDP is only available on Ethernet links. See EmitLLDP= below + for enabling LLDP packet emission from the local system. + + + + + EmitLLDP= + + Controls support for Ethernet LLDP packet emission. Accepts a boolean parameter or the special values + nearest-bridge, non-tpmr-bridge and + customer-bridge. 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 machine-id5) and the + local interface name, as well as the pretty hostname of the system (as set in + machine-info5). 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 nearest-bridge setting permits propagation only to the nearest + connected bridge, non-tpmr-bridge permits propagation across Two-Port MAC Relays, but + not any other bridges, and customer-bridge permits propagation until a customer bridge + is reached. For details about these concepts, see IEEE 802.1AB-2009. Note that + configuring this setting to true is equivalent to nearest-bridge, the recommended and + most restricted level of propagation. See LLDP= above for an option to enable LLDP + reception. + + + + BindCarrier= + + 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. + + + + + Address= + + A static IPv4 or IPv6 address and its prefix length, + separated by a / character. Specify + this key more than once to configure several addresses. + The format of the address must be as described in + inet_pton3. + This is a short-hand for an [Address] section only + containing an Address key (see below). This option may be + specified more than once. + + + 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. + + + + + Gateway= + + The gateway address, which must be in the format + described in + inet_pton3. + This is a short-hand for a [Route] section only containing + a Gateway key. This option may be specified more than + once. + + + + DNS= + + A DNS server address, which must be in the format + described in + inet_pton3. + This option may be specified more than once. This setting is read by + systemd-resolved.service8. + + + + Domains= + + The domains used for DNS host name resolution on this link. Takes a list of DNS domain names which + are 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. + + The specified domains are also used for routing of DNS queries: look-ups for host names ending in the + domains specified here are preferably routed to the DNS servers configured for this interface. If a domain + name is prefixed with ~, the domain name becomes a pure "routing" domain, is used for + DNS query routing purposes only and is not used in the described domain search logic. By specifying a + routing domain of ~. (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) it is possible to + route all DNS traffic preferably to the DNS server specified for this interface. The route domain logic is + particularly useful on multi-homed hosts with DNS servers serving particular private DNS zones on each + interface. + + This setting is read by + systemd-resolved.service8. + + + + NTP= + + An NTP server address. This option may be specified more than once. This setting is read by + systemd-timesyncd.service8. + + + + IPForward= + 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 ipv4 or + ipv6, which only enable IP packet + forwarding for the specified address family. This controls + the net.ipv4.ip_forward and + net.ipv6.conf.all.forwarding sysctl + options of the network interface (see ip-sysctl.txt + for details about sysctl options). Defaults to + no. + + 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. + + To allow IP packet forwarding only between specific + network interfaces use a firewall. + + + + IPMasquerade= + 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 + IPForward=ipv4. Defaults to + no. + + + IPv6PrivacyExtensions= + Configures use of stateless temporary + addresses that change over time (see RFC 4941, + Privacy Extensions for Stateless Address Autoconfiguration + in IPv6). Takes a boolean or the special values + prefer-public and + kernel. When true, enables the privacy + extensions and prefers temporary addresses over public + addresses. When prefer-public, enables the + privacy extensions, but prefers public addresses over + temporary addresses. When false, the privacy extensions + remain disabled. When kernel, the kernel's + default setting will be left in place. Defaults to + no. + + + IPv6AcceptRouterAdvertisements= + Force the setting of the accept_ra + (router advertisements) setting for the interface. + When unset, the kernel default is used, and router + advertisements are accepted only when local forwarding + is disabled for that interface. + When router advertisements are accepted, they will + trigger the start of the DHCPv6 client if the relevant + flags are passed, or if no routers are found on the link. + Takes a boolean. If true, router advertisements are + accepted, when false, router advertisements are ignored, + independently of the local forwarding state. + + See + ip-sysctl.txt + in the kernel documentation, but note that systemd's + setting of 1 corresponds to + kernel's setting of 2. + + + + IPv6DuplicateAddressDetection= + Configures the amount of IPv6 Duplicate + Address Detection (DAD) probes to send. Defaults to unset. + + + + IPv6HopLimit= + 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. + + + + ProxyARP= + 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 RFC 1027. + Defaults to unset. + + + + Bridge= + + The name of the bridge to add the link to. + + + + Bond= + + The name of the bond to add the link to. + + + + VLAN= + + The name of a VLAN to create on the link. This + option may be specified more than once. + + + + MACVLAN= + + The name of a MACVLAN to create on the link. This + option may be specified more than once. + + + + VXLAN= + + The name of a VXLAN to create on the link. This + option may be specified more than once. + + + + Tunnel= + + The name of a Tunnel to create on the link. This + option may be specified more than once. + + + + + + + + [Address] Section Options + + An [Address] section accepts the + following keys. Specify several [Address] + sections to configure several addresses. + + + + Address= + + As in the [Network] section. This + key is mandatory. + + + + Peer= + + The peer address in a point-to-point connection. + Accepts the same format as the Address + key. + + + + Broadcast= + + The broadcast address, which must be in the format + described in + inet_pton3. + This key only applies to IPv4 addresses. If it is not + given, it is derived from the Address + key. + + + + Label= + + An address label. + + + + PreferredLifetime= + + Allows the default "preferred lifetime" of the address to be overridden. + Only three settings are accepted: forever or infinity + which is the default and means that the address never expires, and 0 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. + + + + + + + [Route] Section Options + The [Route] section accepts the + following keys. Specify several [Route] + sections to configure several routes. + + + + Gateway= + + As in the [Network] section. + + + + Destination= + + The destination prefix of the route. Possibly + followed by a slash and the prefix length. If omitted, a + full-length host route is assumed. + + + + Source= + + The source prefix of the route. Possibly followed by + a slash and the prefix length. If omitted, a full-length + host route is assumed. + + + + Metric= + + The metric of the route (an unsigned integer). + + + + Scope= + + The scope of the route, which can be global, + link or host. Defaults to + global. + + + + PreferredSource= + + The preferred source address of the route. The address + must be in the format described in + inet_pton3. + + + + Table=num + + The table identifier for the route (a number between 1 and 4294967295, or 0 to unset). + The table can be retrieved using ip route show table num. + + + + + + + + [DHCP] Section Options + The [DHCP] section configures the + DHCPv4 and DHCP6 client, if it is enabled with the + DHCP= setting described above: + + + + UseDNS= + + When true (the default), the DNS servers received + from the DHCP server will be used and take precedence over + any statically configured ones. + + This corresponds to the + option in resolv.conf5. + + + + UseNTP= + + 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. + + + + UseMTU= + + When true, the interface maximum transmission unit + from the DHCP server will be used on the current link. + Defaults to false. + + + + SendHostname= + + When true (the default), the machine's hostname will + be sent to the DHCP server. + + + + UseHostname= + + When true (the default), the hostname received from + the DHCP server will be set as the transient hostname of the system + + + + + Hostname= + + Use this value for the hostname which is sent to the + DHCP server, instead of machine's hostname. + + + + UseDomains= + + Takes a boolean argument, or the special value route. 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 setting. If set to route, 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 setting when the argument is prefixed with ~. Defaults to + false. + + It is recommended to enable this option only on trusted networks, as setting this affects resolution + of all host names, in particular to 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. + + When set to true, this setting corresponds to the option in resolv.conf5. + + + + UseRoutes= + + 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. + + + + + UseTimezone= + + When true, the timezone received from the + DHCP server will be set as timezone of the local + system. Defaults to no. + + + + CriticalConnection= + + 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. + + + + + ClientIdentifier= + + The DHCPv4 client identifier to use. Either mac to use the MAC address of the link + or duid (the default, see below) to use a RFC4361-compliant Client ID. + + + + + VendorClassIdentifier= + + The vendor class identifier used to identify vendor + type and configuration. + + + + + DUIDType= + + Override the global DUIDType setting for this network. See + networkd.conf5 + for a description of possible values. + + + + + DUIDRawData= + + Override the global DUIDRawData setting for this network. See + networkd.conf5 + for a description of possible values. + + + + + IAID= + + The DHCP Identity Association Identifier (IAID) for the interface, a 32-bit unsigned integer. + + + + + RequestBroadcast= + + 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. + + + + + RouteMetric= + + Set the routing metric for routes specified by the + DHCP server. + + + + + + + [DHCPServer] Section Options + The [DHCPServer] section contains + settings for the DHCP server, if enabled via the + DHCPServer= option described above: + + + + + PoolOffset= + PoolSize= + + 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. PoolOffset= takes the offset of the pool + from the start of subnet, or zero to use the default value. + PoolSize= 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. + + + + DefaultLeaseTimeSec= + MaxLeaseTimeSec= + + 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. + + + + EmitDNS= + DNS= + + Configures whether the DHCP leases handed out + to clients shall contain DNS server information. The + EmitDNS= setting takes a boolean argument + and defaults to yes. The DNS servers to + pass to clients may be configured with the + DNS= option, which takes a list of IPv4 + addresses. If the EmitDNS= 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 + /etc/resolv.conf 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 + MaxLeaseTimeSec= described + above. + + + + EmitNTP= + NTP= + + Similar to the EmitDNS= and + DNS= 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 + EmitDNS= and + DNS=. + + + + EmitRouter= + + Similar to the EmitDNS= + 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 + EmitDNS=. + + + + EmitTimezone= + Timezone= + + Configures whether the DHCP leases handed out + to clients shall contain timezone information. The + EmitTimezone= setting takes a boolean + argument and defaults to yes. The + Timezone= setting takes a timezone string + (such as Europe/Berlin or + UTC) to pass to clients. If no explicit + timezone is set, the system timezone of the local host is + propagated, as determined by the + /etc/localtime symlink. + + + + + + + [Bridge] Section Options + The [Bridge] section accepts the + following keys. + + + UnicastFlood= + + 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. + + + + + HairPin= + + 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. + + + + UseBPDU= + + A boolean. Configures whether STP Bridge Protocol Data Units will be + processed by the bridge port. Defaults to yes. + + + + FastLeave= + + 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. + + + + AllowPortToBeRoot= + + 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. + + + + Cost= + + 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. + + + + + + [BridgeFDB] Section Options + The [BridgeFDB] section manages the + forwarding database table of a port and accepts the following + keys. Specify several [BridgeFDB] sections to + configure several static MAC table entries. + + + + MACAddress= + + As in the [Network] section. This + key is mandatory. + + + + VLANId= + + 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. + + + + + + + Example + + /etc/systemd/network/50-static.network + + [Match] +Name=enp2s0 + +[Network] +Address=192.168.0.15/24 +Gateway=192.168.0.1 + + + + /etc/systemd/network/80-dhcp.network + + [Match] +Name=en* + +[Network] +DHCP=yes + + + + /etc/systemd/network/25-bridge-static.network + + [Match] +Name=bridge0 + +[Network] +Address=192.168.0.15/24 +Gateway=192.168.0.1 +DNS=192.168.0.1 + + + + /etc/systemd/network/25-bridge-slave-interface.network + + [Match] +Name=enp2s0 + +[Network] +Bridge=bridge0 + + + /etc/systemd/network/25-ipip.network + + [Match] +Name=em1 + +[Network] +Tunnel=ipip-tun + + + + /etc/systemd/network/25-sit.network + + [Match] +Name=em1 + +[Network] +Tunnel=sit-tun + + + + /etc/systemd/network/25-gre.network + + [Match] +Name=em1 + +[Network] +Tunnel=gre-tun + + + + /etc/systemd/network/25-vti.network + + [Match] +Name=em1 + +[Network] +Tunnel=vti-tun + + + + /etc/systemd/network/25-bond.network + + [Match] +Name=bond1 + +[Network] +DHCP=yes + + + + + + + See Also + + systemd1, + systemd-networkd.service8, + systemd.link5, + systemd.netdev5, + systemd-resolved.service8 + + + + diff --git a/src/grp-system/systemd/systemd.nspawn.xml b/src/grp-system/systemd/systemd.nspawn.xml new file mode 100644 index 0000000000..3683412c14 --- /dev/null +++ b/src/grp-system/systemd/systemd.nspawn.xml @@ -0,0 +1,454 @@ + + +%entities; +]> + + + + + + + systemd.nspawn + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.nspawn + 5 + + + + systemd.nspawn + Container settings + + + + /etc/systemd/nspawn/machine.nspawn + /run/systemd/nspawn/machine.nspawn + /var/lib/machines/machine.nspawn + + + + Description + + An nspawn container settings file (suffix + .nspawn) encodes additional runtime + information about a local container, and is searched, read and + used by + systemd-nspawn1 + 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 systemd-nspawn command + line, and make it easier to persistently attach specific settings + to specific containers. The syntax of these files is inspired by + .desktop files following the XDG + Desktop Entry Specification, which in turn are inspired by + Microsoft Windows .ini files. + + Boolean arguments used in these settings files can be + written in various formats. For positive settings, the strings + , , + and are equivalent. For negative settings, the + strings , , + and are + equivalent. + + 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. + + + + + <filename>.nspawn</filename> File Discovery + + Files are searched by appending the + .nspawn suffix to the machine name of the + container, as specified with the + switch of systemd-nspawn, or derived from the + directory or image file name. This file is first searched in + /etc/systemd/nspawn/ and + /run/systemd/nspawn/. 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. + + Persistent settings files created and maintained by the + administrator (and thus trusted) should be placed in + /etc/systemd/nspawn/, while automatically + downloaded (and thus potentially untrusted) settings files are + placed in /var/lib/machines/ instead (next to + the container images), where their security impact is limited. In + order to add privileged settings to .nspawn + files acquired from the image vendor, it is recommended to copy the + settings files into /etc/systemd/nspawn/ 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 + systemd-nspawn's + switch, see + systemd-nspawn1 + for details. + + + + [Exec] Section Options + + Settings files may include an [Exec] + section, which carries various execution parameters: + + + + + Boot= + + Takes a boolean argument, which defaults to off. If enabled, systemd-nspawn + will automatically search for an init executable and invoke it. In this case, the + specified parameters using Parameters= are passed as additional arguments to the + init process. This setting corresponds to the switch on the + systemd-nspawn command line. This option may not be combined with + ProcessTwo=yes. + + + + ProcessTwo= + + 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 switch + on the systemd-nspawn command line. This option may not be combined with + Boot=yes. + + + + Parameters= + + Takes a space-separated list of + arguments. This is either a command line, beginning with the + binary name to execute, or – if Boot= is + enabled – the list of arguments to pass to the init + process. This setting corresponds to the command line + parameters passed on the systemd-nspawn + command line. + + + + Environment= + + Takes an environment variable assignment + consisting of key and value, separated by + =. 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 command line + switch. + + + + User= + + 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 command line + switch. + + + + WorkingDirectory= + + 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 command line + switch. + + + + Capability= + DropCapability= + + Takes a space-separated list of Linux process + capabilities (see + capabilities7 + for details). The Capability= setting + specifies additional capabilities to pass on top of the + default set of capabilities. The + DropCapability= setting specifies + capabilities to drop from the default set. These settings + correspond to the and + command line + switches. Note that Capability= is a + privileged setting, and only takes effect in + .nspawn files in + /etc/systemd/nspawn/ and + /run/system/nspawn/ (see above). On the + other hand, DropCapability= takes effect in + all cases. + + + + KillSignal= + + 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 is used + (on systemd-compatible init systems SIGRTMIN+3 triggers an + orderly shutdown). For a list of valid signals, see + signal7. + + + + Personality= + + Configures the kernel personality for the + container. This is equivalent to the + switch. + + + + MachineID= + + Configures the 128-bit machine ID (UUID) to pass to + the container. This is equivalent to the + command line switch. This option is + privileged (see above). + + + + PrivateUsers= + + Configures support for usernamespacing. This is equivalent to the + command line switch, and takes the same options. This option is privileged + (see above). + + + + + + [Files] Section Options + + Settings files may include a [Files] + section, which carries various parameters configuring the file + system of the container: + + + + + ReadOnly= + + 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 + command line + switch. + + + + Volatile= + + Takes a boolean argument, or the special value + state. This configures whether to run the + container with volatile state and/or configuration. This + option is equivalent to , see + systemd-nspawn1 + for details about the specific options + supported. + + + + Bind= + BindReadOnly= + + 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 and + , see + systemd-nspawn1 + for details about the specific options supported. This setting + is privileged (see above). + + + + TemporaryFileSystem= + + Adds a tmpfs 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 tmpfs mounts. This + option is equivalent to the command line switch + , see + systemd-nspawn1 + for details about the specific options supported. This setting + is privileged (see above). + + + + PrivateUsersChown= + + 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 + command line switch. This option is privileged (see + above). + + + + + + + [Network] Section Options + + Settings files may include a [Network] + section, which carries various parameters configuring the network + connectivity of the container: + + + + + Private= + + 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 + command line + switch. + + + + VirtualEthernet= + + Takes a boolean argument. Configures whether + to create a virtual Ethernet connection + (veth) between host and the container. This + setting implies Private=yes. This setting + corresponds to the command + line switch. This option is privileged (see + above). + + + + VirtualEthernetExtra= + + Takes a colon-separated pair of interface + names. Configures an additional virtual Ethernet connection + (veth) 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 + Private=yes. This setting corresponds to + the command line + switch, and maybe be used multiple times. It is independent of + VirtualEthernet=. This option is privileged + (see above). + + + + Interface= + + Takes a space-separated list of interfaces to + add to the container. This option corresponds to the + command line switch and + implies Private=yes. This option is + privileged (see above). + + + + MACVLAN= + IPVLAN= + + 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 + and + command line switches and + imply Private=yes. These options are + privileged (see above). + + + + Bridge= + + Takes an interface name. This setting implies + VirtualEthernet=yes and + Private=yes 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 + command line switch. This + option is privileged (see above). + + + + Zone= + + Takes a network zone name. This setting implies VirtualEthernet=yes and + Private=yes 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 + vz-. This option corresponds to the command line + switch. This option is privileged (see above). + + + + Port= + + Exposes a TCP or UDP port of the container on + the host. This option corresponds to the + command line switch, see + systemd-nspawn1 + for the precise syntax of the argument this option takes. This + option is privileged (see above). + + + + + + See Also + + systemd1, + systemd-nspawn1, + systemd.directives7 + + + + 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..946234ad90 --- /dev/null +++ b/src/grp-system/systemd/systemd.offline-updates.xml @@ -0,0 +1,169 @@ + + + + + + + + systemd.offline-updates + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.offline-updates + 7 + + + + systemd.offline-updates + Implementation of offline updates in systemd + + + + Implementing Offline System Updates + + 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 + GNOME design whiteboard. + + + The logic: + + + + The package manager prepares system updates by downloading all (RPM or DEB or + whatever) packages to update off-line in a special directory + /var/lib/system-update (or + another directory of the package/upgrade manager's choice). + + + + When the user OK'ed the update, the symlink /system-update is + created that points to /var/lib/system-update (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 /var is not available yet. + + + + Very early in the new boot + systemd-update-generator8 + checks whether /system-update exists. If so, it (temporarily and for + this boot only) redirects (i.e. symlinks) default.target to + system-update.target, a special target that is pulls in the base system + (i.e. sysinit.target, so that all file systems are mounted but little + else) and the system update units. + + + + The system now continues to boot into default.target, and thus + into system-update.target. This target pulls in the system update unit, + which starts the system update script after all file systems have been mounted. + + + + As the first step, the update script should check if the + /system-update symlink points to the 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 created the symlink before reboot should perform any actions. It + is unsafe to run multiple updates in parallel. + + + + 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 systemctl reboot. + In addition, on failure the script should revert to the old file system snapshot + (without the symlink). + + + + The system is rebooted. Since the /system-update symlink is gone, + the generator won't redirect default.target after reboot and the + system now boots into the default target again. + + + + + + Recommendations + + + + To make things a bit more robust we recommend hooking the update script into + system-update.target via a .wants/ + symlink in the distribution package, rather than depending on systemctl + enable 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 + /usr/lib/systemd/system-update.target.wants/foobar.service + → ../foobar.service to your package. + + + + Make sure to remove the /system-update symlink as early as + possible in the update script to avoid reboot loops in case the update fails. + + + + Use FailureAction=reboot in the service file for your update script + to ensure that a reboot is automatically triggered if the update fails. + FailureAction= 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 + Reboot() call or calling systemct reboot. See + logind dbus API + for details. + + + + The update service should declare DefaultDependencies=false, + and pull in any services it requires explicitly. + + + + + + See also + + + Implementing Offline System Updates, + systemd1, + systemd.generator7, + systemd-update-generator8, + dnf.plugin.system-upgrade8 + + + 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 @@ + + + + + + + + systemd.path + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.path + 5 + + + + systemd.path + Path unit configuration + + + + path.path + + + + Description + + A unit configuration file whose name ends in + .path encodes information about a path + monitored by systemd, for path-based activation. + + This man page lists the configuration options specific to + this unit type. See + systemd.unit5 + 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. + + 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 foo.path + activates a matching service foo.service. The + unit to activate may be controlled by Unit= + (see below). + + Internally, path units use the + inotify7 + 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. + + + + Automatic Dependencies + + 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. + + An implicit Before= dependency is added + between a path unit and the unit it is supposed to activate. + + Unless DefaultDependencies=false in the [Unit] section is used, path + units will implicitly have dependencies of type Before= on paths.target, + dependencies of type After= and Requires= on + sysinit.target, and have dependencies of type Conflicts= and + Before= on shutdown.target. 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. + + + + + Options + + 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: + + + + PathExists= + PathExistsGlob= + PathChanged= + PathModified= + DirectoryNotEmpty= + + Defines paths to monitor for certain changes: + PathExists= may be used to watch the mere + existence of a file or directory. If the file specified + exists, the configured unit is activated. + PathExistsGlob= works similar, but checks + for the existence of at least one file matching the globbing + pattern specified. PathChanged= 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. PathModified= is + similar, but additionally it is activated also on simple + writes to the watched file. + DirectoryNotEmpty= may be used to watch a + directory and activate the configured unit whenever it + contains at least one file. + + The arguments of these directives must be absolute file + system paths. + + 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. + + If a path already exists (in case of + PathExists= and + PathExistsGlob=) or a directory already is + not empty (in case of DirectoryNotEmpty=) + at the time the path unit is activated, then the configured + unit is immediately activated as well. Something similar does + not apply to PathChanged= and + PathModified=. + + If the path itself or any of the containing directories + are not accessible, systemd will watch for + permission changes and notice that conditions are satisfied + when permissions allow that. + + + Unit= + + The unit to activate when any of the + configured paths changes. The argument is a unit name, whose + suffix is not .path. 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. + + + MakeDirectory= + + Takes a boolean argument. If true, the + directories to watch are created before watching. This option + is ignored for PathExists= settings. + Defaults to . + + + DirectoryMode= + + If MakeDirectory= is + enabled, use the mode specified here to create the directories + in question. Takes an access mode in octal notation. Defaults + to . + + + + + + See Also + + systemd1, + systemctl1, + systemd.unit5, + systemd.service5, + inotify7, + systemd.directives7 + + + + diff --git a/src/grp-system/systemd/systemd.preset.xml b/src/grp-system/systemd/systemd.preset.xml new file mode 100644 index 0000000000..b7164014f0 --- /dev/null +++ b/src/grp-system/systemd/systemd.preset.xml @@ -0,0 +1,189 @@ + + + + + + + + systemd.preset + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.preset + 5 + + + + systemd.preset + Service enablement presets + + + + /etc/systemd/system-preset/*.preset + /run/systemd/system-preset/*.preset + /usr/lib/systemd/system-preset/*.preset + /etc/systemd/user-preset/*.preset + /run/systemd/user-preset/*.preset + /usr/lib/systemd/user-preset/*.preset + + + + Description + + Preset files may be used to encode policy which units shall + be enabled by default and which ones shall be disabled. They are + read by systemctl preset (for more information + see + systemctl1) + which uses this information to enable or disable a unit according + to preset policy. systemctl preset is used by + the post install scriptlets of RPM packages (or other OS package + formats), to enable/disable specific units by default on package + installation, enforcing distribution, spin or administrator preset + policy. This allows choosing a certain set of units to be + enabled/disabled even before installing the actual package. + + For more information on the preset logic please have a look + at the Presets + document. + + It is not recommended to ship preset files within the + respective software packages implementing the units, but rather + centralize them in a distribution or spin default policy, which + can be amended by administrator policy. + + If no preset files exist, systemctl + preset will enable all units that are installed by + default. If this is not desired and all units shall rather be + disabled, it is necessary to ship a preset file with a single, + catchall "disable *" line. (See example 1, + below.) + + + + Preset File Format + + The preset files contain a list of directives consisting of + either the word enable or + disable followed by a space and a unit name + (possibly with shell style wildcards), separated by newlines. + Empty lines and lines whose first non-whitespace character is # or + ; are ignored. + + Two different directives are understood: + enable may be used to enable units by default, + disable to disable units by default. + + If multiple lines apply to a unit name, the first matching + one takes precedence over all others. + + Each preset file shall be named in the style of + <priority>-<policy-name>.preset. Files + in /etc/ override files with the same name in + /usr/lib/ and /run/. + Files in /run/ override files with the same + name in /usr/lib/. Packages should install + their preset files in /usr/lib/. Files in + /etc/ are reserved for the local + administrator, who may use this logic to override the preset files + installed by vendor packages. All preset files are sorted by their + filename in lexicographic order, regardless of which of the + directories they reside in. If multiple files specify the same + unit name, the entry in the file with the lexicographically + earliest name will be applied. It is recommended to prefix all + filenames with a two-digit number and a dash, to simplify the + ordering of the files. + + If the administrator wants to disable a preset file supplied + by the vendor, the recommended way is to place a symlink to + /dev/null in + /etc/systemd/system-preset/ bearing the same + filename. + + + + Example + + + Default off example <filename>/usr/lib/systemd/system-preset/99-default.preset</filename>: + + disable * + + + This disables all units. Due to the filename prefix + 99-, it will be read last and hence can easily + be overridden by spin or administrator preset policy or + suchlike. + + + A GNOME spin example <filename>/usr/lib/systemd/system-preset/50-gnome.preset</filename>: + + enable gdm.service +enable colord.service +enable accounts-daemon.service +enable avahi-daemon.* + + + + This enables the three mentioned units, plus all + avahi-daemon regardless of which unit type. A + file like this could be useful for inclusion in a GNOME spin of a + distribution. It will ensure that the units necessary for GNOME + are properly enabled as they are installed. It leaves all other + units untouched, and subject to other (later) preset files, for + example like the one from the first example above. + + + Administrator policy <filename>/etc/systemd/system-preset/00-lennart.preset</filename>: + + enable httpd.service +enable sshd.service +enable postfix.service +disable * + + + This enables three specific services and disables all + others. This is useful for administrators to specifically select + the units to enable, and disable all others. Due to the filename + prefix 00- it will be read early and hence + overrides all other preset policy files. + + + + See Also + + systemd1, + systemctl1, + systemd-delta1 + + + + 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..066f2cc19b --- /dev/null +++ b/src/grp-system/systemd/systemd.resource-control.xml @@ -0,0 +1,628 @@ + + + + + + + + systemd.resource-control + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.resource-control + 5 + + + + systemd.resource-control + Resource control unit settings + + + + + slice.slice, + scope.scope, + service.service, + socket.socket, + mount.mount, + swap.swap + + + + + Description + + 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 Control Groups + kernel concept for organizing processes in a hierarchical tree of + named groups for the purpose of resource management. + + This man page lists the configuration options shared by + those six unit types. See + systemd.unit5 + for the common options of all unit configuration files, and + systemd.slice5, + systemd.scope5, + systemd.service5, + systemd.socket5, + systemd.mount5, + and + systemd.swap5 + 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. + + See the New + Control Group Interfaces for an introduction on how to make + use of resource control APIs from programs. + + + + Automatic Dependencies + + Units with the Slice= setting set get + automatic Requires= and + After= dependencies on the specified slice + unit. + + + + Unified and Legacy Control Group Hierarchies + + Unified control group hierarchy is the new version of kernel control group interface. Depending on the + resource type, there are differences in resource control capabilities. Also, because of interface changes, some + resource types have a separate set of options on the unified hierarchy. + + + + + + + IO prefixed settings are superset of and replace BlockIO + prefixed ones. On unified hierarchy, IO resource control also applies to buffered writes. + + + + + + To ease the transition, there is best-effort translation between the two versions of settings. If all + settings of a unit for a given resource type are for the other hierarchy type, the settings are translated and + applied. If there are any valid settings for the hierarchy in use, all translations are disabled for the resource + type. Mixing the two types of settings on a unit can lead to confusing results. + + + + Options + + Units of the types listed above can have settings + for resource control configuration: + + + + + CPUAccounting= + + + 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 + DefaultCPUAccounting= in + systemd-system.conf5. + + + + + CPUShares=weight + StartupCPUShares=weight + + + Assign the specified CPU time share weight to the + processes executed. These options take an integer value and + control the cpu.shares control group + attribute. The allowed range is 2 to 262144. Defaults to + 1024. For details about this control group attribute, see + sched-design-CFS.txt. + The available CPU time is split up among all units within + one slice relative to their CPU time share weight. + + While StartupCPUShares= only + applies to the startup phase of the system, + CPUShares= applies to normal runtime of + the system, and if the former is not set also to the startup + phase. Using StartupCPUShares= allows + prioritizing specific services at boot-up differently than + during normal runtime. + + These options imply + CPUAccounting=true. + + + + + CPUQuota= + + + 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 + cpu.cfs_quota_us control group + attribute. For details about this control group attribute, + see sched-design-CFS.txt. + + Example: CPUQuota=20% ensures that + the executed processes will never get more than 20% CPU time + on one CPU. + + Implies CPUAccounting=true. + + + + + MemoryAccounting= + + + 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 + DefaultMemoryAccounting= in + systemd-system.conf5. + + + + + MemoryLimit=bytes + + + 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. If assigned the special value + infinity, no memory limit is applied. This + controls the memory.limit_in_bytes + control group attribute. For details about this control + group attribute, see memory.txt. + + Implies MemoryAccounting=true. + + + + + TasksAccounting= + + + 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 + DefaultTasksAccounting= in + systemd-system.conf5. + + + + + TasksMax=N + + + 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. If assigned the special value + infinity, no tasks limit is applied. This + controls the pids.max control group + attribute. For details about this control group attribute, + see pids.txt. + + Implies TasksAccounting=true. The + system default for this setting may be controlled with + DefaultTasksMax= in + systemd-system.conf5. + + + + + IOAccounting= + + + 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 DefaultIOAccounting= + in + systemd-system.conf5. + + This setting is supported only if the unified control group hierarchy is used. Use + BlockIOAccounting= on systems using the legacy control group hierarchy. + + + + + IOWeight=weight + StartupIOWeight=weight + + + 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 io.weight control group attribute, which defaults to + 100. For details about this control group attribute, see cgroup-v2.txt. The available I/O + bandwidth is split up among all units within one slice relative to their block I/O weight. + + While StartupIOWeight= only applies + to the startup phase of the system, + IOWeight= 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. + + Implies IOAccounting=true. + + This setting is supported only if the unified control group hierarchy is used. Use + BlockIOWeight= and StartupBlockIOWeight= on systems using the legacy + control group hierarchy. + + + + + IODeviceWeight=device weight + + + 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 io.weight 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 cgroup-v2.txt. + + Implies IOAccounting=true. + + This setting is supported only if the unified control group hierarchy is used. Use + BlockIODeviceWeight= on systems using the legacy control group hierarchy. + + + + + IOReadBandwidthMax=device bytes + IOWriteBandwidthMax=device bytes + + + 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 io.max control + group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For details + about this control group attribute, see cgroup-v2.txt. + + + Implies IOAccounting=true. + + This setting is supported only if the unified control group hierarchy is used. Use + BlockIOAccounting= on systems using the legacy control group hierarchy. + + + + + IOReadIOPSMax=device IOPS + IOWriteIOPSMax=device IOPS + + + 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 io.max control + group attributes. Use this option multiple times to set IOPS limits for multiple devices. For details about + this control group attribute, see cgroup-v2.txt. + + + Implies IOAccounting=true. + + This setting is supported only if the unified control group hierarchy is used. + + + + + BlockIOAccounting= + + + 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 + DefaultBlockIOAccounting= in + systemd-system.conf5. + + This setting is supported only if the legacy control group hierarchy is used. Use + IOAccounting= on systems using the unified control group hierarchy. + + + + + BlockIOWeight=weight + StartupBlockIOWeight=weight + + 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 blkio.weight control group attribute, which defaults to + 500. For details about this control group attribute, see blkio-controller.txt. + The available I/O bandwidth is split up among all units within one slice relative to their block I/O + weight. + + While StartupBlockIOWeight= only + applies to the startup phase of the system, + BlockIOWeight= 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. + + Implies + BlockIOAccounting=true. + + This setting is supported only if the legacy control group hierarchy is used. Use + IOWeight= and StartupIOWeight= on systems using the unified control group + hierarchy. + + + + + + BlockIODeviceWeight=device weight + + + 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 blkio.weight_device 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 blkio-controller.txt. + + Implies + BlockIOAccounting=true. + + This setting is supported only if the legacy control group hierarchy is used. Use + IODeviceWeight= on systems using the unified control group hierarchy. + + + + + BlockIOReadBandwidth=device bytes + BlockIOWriteBandwidth=device bytes + + + 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 + blkio.throttle.read_bps_device and blkio.throttle.write_bps_device + control group attributes. Use this option multiple times to set bandwidth limits for multiple devices. For + details about these control group attributes, see blkio-controller.txt. + + + Implies + BlockIOAccounting=true. + + This setting is supported only if the legacy control group hierarchy is used. Use + IOReadBandwidthMax= and IOWriteBandwidthMax= on systems using the + unified control group hierarchy. + + + + + DeviceAllow= + + + Control access to specific device nodes by the + executed processes. Takes two space-separated strings: a + device node specifier followed by a combination of + r, w, + m to control + reading, writing, + or creation of the specific device node(s) by the unit + (mknod), respectively. This controls + the devices.allow and + devices.deny control group + attributes. For details about these control group + attributes, see devices.txt. + + The device node specifier is either a path to a device + node in the file system, starting with + /dev/, or a string starting with either + char- or block- + followed by a device group name, as listed in + /proc/devices. 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 + * and ? + wildcards. Examples: /dev/sda5 is a + path to a device node, referring to an ATA or SCSI block + device. char-pts and + char-alsa are specifiers for all pseudo + TTYs and all ALSA sound devices, + respectively. char-cpu/* is a specifier + matching all CPU related device groups. + + + + + DevicePolicy=auto|closed|strict + + + + Control the policy for allowing device access: + + + + + + means to only allow types of access that are + explicitly specified. + + + + + + + in addition, allows access to standard pseudo + devices including + /dev/null, + /dev/zero, + /dev/full, + /dev/random, and + /dev/urandom. + + + + + + + + + in addition, allows access to all devices if no + explicit DeviceAllow= is present. + This is the default. + + + + + + + + + Slice= + + + The name of the slice unit to place the unit + in. Defaults to system.slice 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 system.slice + that is named after the template name. + + This option may be used to arrange systemd units in a + hierarchy of slices each of which might have resource + settings applied. + + 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. + + Special care should be taken when relying on the default slice assignment in templated service units + that have DefaultDependencies=no set, see + systemd.service5, section + "Automatic Dependencies" for details. + + + + + + Delegate= + + + Turns on delegation of further resource control + partitioning to processes of the unit. For unprivileged + services (i.e. those using the User= + 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. + + + + + + + + See Also + + systemd1, + systemd.unit5, + systemd.service5, + systemd.slice5, + systemd.scope5, + systemd.socket5, + systemd.mount5, + systemd.swap5, + systemd.directives7, + systemd.special7, + The documentation for control groups and specific controllers in the Linux kernel: + cgroups.txt, + cpuacct.txt, + memory.txt, + blkio-controller.txt. + + + 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 @@ + + + + + + + + systemd.scope + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.scope + 5 + + + + systemd.scope + Scope unit configuration + + + + scope.scope + + + + Description + + 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 .scope 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. + + The main purpose of scope units is grouping worker processes + of a system service for organization and for managing resources. + + systemd-run may + be used to easily launch a command in a new scope unit from the + command line. + + See the New + Control Group Interfaces for an introduction on how to make + use of scope units from programs. + + + + Automatic Dependencies + + Unless DefaultDependencies=false + is used, scope units will implicitly have dependencies of + type Conflicts= and + Before= on + shutdown.target. 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. + + + Additional implicit dependencies may be added as result of + resource control parameters as documented in + systemd.resource-control5. + + + + + See Also + + systemd1, + systemd-run1, + systemd.unit5, + systemd.resource-control5, + systemd.service5, + systemd.directives7. + + + + diff --git a/src/grp-system/systemd/systemd.service.xml b/src/grp-system/systemd/systemd.service.xml new file mode 100644 index 0000000000..6641dfed4f --- /dev/null +++ b/src/grp-system/systemd/systemd.service.xml @@ -0,0 +1,1352 @@ + + + + + + + + systemd.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.service + 5 + + + + systemd.service + Service unit configuration + + + + service.service + + + + Description + + A unit configuration file whose name ends in + .service encodes information about a process + controlled and supervised by systemd. + + This man page lists the configuration options specific to + this unit type. See + systemd.unit5 + for the common options of all unit configuration files. The common + configuration items are configured in the generic + [Unit] and [Install] + sections. The service specific configuration options are + configured in the [Service] section. + + Additional options are listed in + systemd.exec5, + which define the execution environment the commands are executed + in, and in + systemd.kill5, + which define the way the processes of the service are terminated, + and in + systemd.resource-control5, + which configure resource control settings for the processes of the + service. + + 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 .service 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 Incompatibilities + with SysV document. + + + + Automatic Dependencies + + Services with Type=dbus set automatically + acquire dependencies of type Requires= and + After= on + dbus.socket. + + Socket activated service are automatically ordered after + their activated .socket units via an + automatic After= dependency. + + Unless DefaultDependencies= in the [Unit] is set to + , service units will implicitly have dependencies of type Requires= and + After= on sysinit.target, a dependency of type After= on + basic.target as well as dependencies of type Conflicts= and + Before= on shutdown.target. 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. + + Instanced service units (i.e. service units with an @ in their name) are assigned by + default a per-template slice unit (see + systemd.slice5), 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 DefaultDependencies=no in the + template unit, and either define your own per-template slice unit file that also sets + DefaultDependencies=no, or set Slice=system.slice (or another suitable slice) + in the template unit. Also see + systemd.resource-control5. + + Additional implicit dependencies may be added as result of + execution and resource control parameters as documented in + systemd.exec5 + and + systemd.resource-control5. + + + + Options + + Service files must include a [Service] + 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 + systemd.exec5 + and + systemd.kill5. + The options specific to the [Service] section + of service units are the following: + + + + Type= + + Configures the process start-up type for this + service unit. One of + , + , + , + , + or + . + + If set to (the default if + neither Type= nor + BusName=, but ExecStart= + are specified), it is expected that the process configured + with ExecStart= 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. + + If set to , it is expected that + the process configured with ExecStart= will + call fork() 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 PIDFile= + 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. + + Behavior of is similar to + ; however, it is expected that the + process has to exit before systemd starts follow-up units. + RemainAfterExit= is particularly useful for + this type of service. This is the implied default if neither + Type= or ExecStart= are + specified. + + Behavior of is similar to + ; however, it is expected that the + daemon acquires a name on the D-Bus bus, as configured by + BusName=. 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 dbus.socket + unit. This type is the default if BusName= + is specified. + + Behavior of is similar to + ; however, it is expected that the + daemon sends a notification message via + sd_notify3 + 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, + NotifyAccess= (see below) should be set to + open access to the notification socket provided by systemd. If + NotifyAccess= is not set, it will be + implicitly set to . Note that currently + Type= will not work + if used in combination with + PrivateNetwork=. + + Behavior of is very similar to + ; however, actual execution of the + service binary is delayed until all jobs are dispatched. This + may be used to avoid interleaving of output of shell services + with the status output on the console. + + + + + RemainAfterExit= + + Takes a boolean value that specifies whether + the service shall be considered active even when all its + processes exited. Defaults to . + + + + + GuessMainPID= + + 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 + is set and + 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 . + + + + + PIDFile= + + Takes an absolute file name pointing to the + PID file of this daemon. Use of this option is recommended for + services where Type= is set to + . 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. + + + + + + BusName= + + Takes a D-Bus bus name that this service is + reachable as. This option is mandatory for services where + Type= is set to + . + + + + + ExecStart= + 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). + + + When Type= is not + , only one command may and must be + given. When Type=oneshot is used, zero or + more commands may be specified. This can 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 + ExecStart= is specified, then the service + must have RemainAfterExit=yes set. + + 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 @, the second + token will be passed as argv[0] to the + executed process, followed by the further arguments specified. + If the absolute filename is prefixed with + -, 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 both + - and @ are used, they + can appear in either order. + + 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 + -), other lines are not executed, and the + unit is considered failed. + + Unless Type=forking is set, the + process started via this command line will be considered the + main process of the daemon. + + + + + ExecStartPre= + ExecStartPost= + Additional commands that are executed before + or after the command in ExecStart=, + respectively. Syntax is the same as for + ExecStart=, except that multiple command + lines are allowed and the commands are executed one after the + other, serially. + + If any of those commands (not prefixed with + -) fail, the rest are not executed and the + unit is considered failed. + + ExecStart= commands are only run after + all ExecStartPre= commands that were not prefixed + with a - exit successfully. + + ExecStartPost= commands are only run after + the service has started successfully, as determined by Type= + (i.e. the process has been started for Type=simple + or Type=idle, the process exits successfully for + Type=oneshot, the initial process exits successfully + for Type=forking, READY=1 is sent + for Type=notify, or the BusName= + has been taken for Type=dbus). + + Note that ExecStartPre= may not be + used to start long-running processes. All processes forked + off by processes invoked via ExecStartPre= will + be killed before the next service process is run. + + Note that if any of the commands specified in ExecStartPre=, + ExecStart=, or ExecStartPost= fail (and are not prefixed with + -, see above) or time out before the service is fully up, execution continues with commands + specified in ExecStopPost=, the commands in ExecStop= are skipped. + + + + + ExecReload= + Commands to execute to trigger a configuration + reload in the service. This argument takes multiple command + lines, following the same scheme as described for + ExecStart= above. Use of this setting is + optional. Specifier and environment variable substitution is + supported here following the same scheme as for + ExecStart=. + + One additional, special environment variable is set: if + known, $MAINPID is set to the main process + of the daemon, and may be used for command lines like the + following: + + /bin/kill -HUP $MAINPID + + 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 + ExecReload= to a command that not only + triggers a configuration reload of the daemon, but also + synchronously waits for it to complete. + + + + + ExecStop= + Commands to execute to stop the service + started via ExecStart=. This argument takes + multiple command lines, following the same scheme as described + for ExecStart= 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 KillMode= setting (see + systemd.kill5). + If this option is not specified, the process is terminated by + sending the signal specified in KillSignal= + when service stop is requested. Specifier and environment + variable substitution is supported (including + $MAINPID, see above). + + 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 + SIGKILL 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. + + Note that the commands specified in ExecStop= 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 ExecStart=, + ExecStartPre= or ExecStartPost= failed (and weren't prefixed with + -, see above) or timed out. Use ExecStopPost= to invoke commands when a + service failed to start up correctly and is shut down again. + + 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 + ExecStopPost= instead. + + + + ExecStopPost= + Additional commands that are executed after the service is stopped. This includes cases where + the commands configured in ExecStop= were used, where the service does not have any + ExecStop= defined, or where the service exited unexpectedly. This argument takes multiple + command lines, following the same scheme as described for ExecStart=. Use of these settings + is optional. Specifier and environment variable substitution is supported. Note that – unlike + ExecStop= – commands specified with this setting are invoked when a service failed to start + up correctly and is shut down again. + + 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. + + + + RestartSec= + Configures the time to sleep before restarting + a service (as configured with Restart=). + Takes a unit-less value in seconds, or a time span value such + as "5min 20s". Defaults to 100ms. + + + + TimeoutStartSec= + 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 + infinity to disable the timeout logic. Defaults to + DefaultTimeoutStartSec= from the manager + configuration file, except when + Type=oneshot is used, in which case the + timeout is disabled by default (see + systemd-system.conf5). + + + + + TimeoutStopSec= + 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 + SIGTERM, and after another timeout of + equal duration with SIGKILL (see + KillMode= in + systemd.kill5). + Takes a unit-less value in seconds, or a time span value such + as "5min 20s". Pass infinity to disable the + timeout logic. Defaults to + DefaultTimeoutStopSec= from the manager + configuration file (see + systemd-system.conf5). + + + + + TimeoutSec= + A shorthand for configuring both + TimeoutStartSec= and + TimeoutStopSec= to the specified value. + + + + + RuntimeMaxSec= + + 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 Type=oneshot services, as they terminate immediately after + activation completed. Pass infinity (the default) to configure no runtime + limit. + + + + WatchdogSec= + Configures the watchdog timeout for a service. + The watchdog is activated when the start-up is completed. The + service must call + sd_notify3 + regularly with WATCHDOG=1 (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 + SIGABRT. By setting + Restart= to , + , or + , the service will be automatically + restarted. The time configured here will be passed to the + executed service process in the + WATCHDOG_USEC= 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, NotifyAccess= (see below) + should be set to open access to the notification socket + provided by systemd. If NotifyAccess= is + not set, it will be implicitly set to . + Defaults to 0, which disables this feature. The service can + check whether the service manager expects watchdog keep-alive + notifications. See + sd_watchdog_enabled3 + for details. + sd_event_set_watchdog3 + may be used to enable automatic watchdog notification support. + + + + + Restart= + 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 ExecStartPre=, + ExecStartPost=, + ExecStop=, + ExecStopPost=, or + ExecReload=. 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. + + Takes one of + , + , + , + , + , + , or + . + If set to (the default), the service will + not be restarted. If set to , 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 + SIGHUP, + SIGINT, + SIGTERM or + SIGPIPE, and + additionally, exit statuses and signals specified in + SuccessExitStatus=. If set to + , 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 , + 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 + , 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 + , the service will be restarted + only if the watchdog timeout for the service expires. If set + to , the service will be restarted + regardless of whether it exited cleanly or not, got terminated + abnormally by a signal, or hit a timeout. + + + Exit causes and the effect of the <varname>Restart=</varname> settings on them + + + + + + + Restart settings/Exit causes + + + + + + + + + + + + Clean exit code or signal + + X + X + + + + + + + Unclean exit code + + X + + X + + + + + + Unclean signal + + X + + X + X + X + + + + Timeout + + X + + X + X + + + + + Watchdog + + X + + X + X + + X + + + +
+ + As exceptions to the setting above, the service will not + be restarted if the exit code or signal is specified in + RestartPreventExitStatus= (see below). + Also, the services will always be restarted if the exit code + or signal is specified in + RestartForceExitStatus= (see below). + + Setting this to 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), + is an alternative choice. + + + + + SuccessExitStatus= + 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 SIGHUP, + SIGINT, SIGTERM, and + SIGPIPE. Exit status definitions can + either be numeric exit codes or termination signal names, + separated by spaces. For example: + + SuccessExitStatus=1 2 8 SIGKILL + + ensures that exit codes 1, 2, 8 and + the termination signal SIGKILL are + considered clean service terminations. + + + Note that if a process has a signal handler installed + and exits by calling + _exit2 + 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 + Proper + handling of SIGINT/SIGQUIT — How to be a proper + program. + + 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. + + + + RestartPreventExitStatus= + 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 Restart=. 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: + + RestartPreventExitStatus=1 6 SIGABRT + + ensures that exit codes 1 and 6 and the termination signal + SIGABRT 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. + + + + RestartForceExitStatus= + 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 Restart=. The argument format is + similar to + RestartPreventExitStatus=. + + + + PermissionsStartOnly= + Takes a boolean argument. If true, the + permission-related execution options, as configured with + User= and similar options (see + systemd.exec5 + for more information), are only applied to the process started + with + ExecStart=, and not to the various other + ExecStartPre=, + ExecStartPost=, + ExecReload=, + ExecStop=, and + ExecStopPost= + commands. If false, the setting is applied to all configured + commands the same way. Defaults to false. + + + + RootDirectoryStartOnly= + Takes a boolean argument. If true, the root + directory, as configured with the + RootDirectory= option (see + systemd.exec5 + for more information), is only applied to the process started + with ExecStart=, and not to the various + other ExecStartPre=, + ExecStartPost=, + ExecReload=, ExecStop=, + and ExecStopPost= commands. If false, the + setting is applied to all configured commands the same way. + Defaults to false. + + + + NonBlocking= + Set the O_NONBLOCK 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 + O_NONBLOCK flag set and hence are in + non-blocking mode. This option is only useful in conjunction + with a socket unit, as described in + systemd.socket5. + Defaults to false. + + + + NotifyAccess= + Controls access to the service status + notification socket, as accessible via the + sd_notify3 + call. Takes one of (the default), + or . If + , no daemon status updates are accepted + from the service processes, all status update messages are + ignored. If , only service updates sent + from the main process of the service are accepted. If + , 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 + Type=notify or + WatchdogSec= (see above). If those options + are used but NotifyAccess= is not + configured, it will be implicitly set to + . + + + + Sockets= + 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. + + 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 + Service= setting of + .socket units does not have to match the + inverse of the Sockets= setting of the + .service it refers to. + + 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. + + + + FailureAction= + Configure the action to take when the service enters a failed state. Takes the same values as + the unit setting StartLimitAction= and executes the same actions (see + systemd.unit5). Defaults to + . + + + + FileDescriptorStoreMax= + Configure how many file descriptors may be + stored in the service manager for the service using + sd_pid_notify_with_fds3's + FDSTORE=1 messages. This is useful for + implementing service restart schemes where the state is + serialized to /run 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 by default. 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 queued or being executed for it. + + + + USBFunctionDescriptors= + Configure the location of a file containing + USB + FunctionFS descriptors, for implementation of USB + gadget functions. This is used only in conjunction with a + socket unit with ListenUSBFunction= + configured. The contents of this file are written to the + ep0 file after it is + opened. + + + + USBFunctionStrings= + Configure the location of a file containing + USB FunctionFS strings. Behavior is similar to + USBFunctionDescriptors= + above. + + + + + Check + systemd.exec5 + and + systemd.kill5 + for more settings. + + + + + Command lines + + This section describes command line parsing and + variable and specifier substitutions for + ExecStart=, + ExecStartPre=, + ExecStartPost=, + ExecReload=, + ExecStop=, and + ExecStopPost= options. + + 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 \;. + + 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 (\) may be used to merge lines. + + + 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 + <, + <<, + >, and + >>, pipes using + |, running programs in the background using + &, and other elements of shell + syntax are not supported. + + The command to execute must be an absolute path name. It may + contain spaces, but control characters are not allowed. + + The command line accepts % specifiers as + described in + systemd.unit5. + Note that the first argument of the command line (i.e. the program + to execute) may not include specifiers. + + Basic environment variable substitution is supported. Use + ${FOO} 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 + $FOO 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. + + Example: + + Environment="ONE=one" 'TWO=two two' +ExecStart=/bin/echo $ONE $TWO ${TWO} + + This will execute /bin/echo with four + arguments: one, two, + two, and two two. + + Example: + Environment=ONE='one' "TWO='two two' too" THREE= +ExecStart=/bin/echo ${ONE} ${TWO} ${THREE} +ExecStart=/bin/echo $ONE $TWO $THREE + This results in echo being + called twice, the first time with arguments + 'one', + 'two two' too, , + and the second time with arguments + one, two two, + too. + + + To pass a literal dollar sign, use $$. + 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. + + Variables to be used in this fashion may be defined through + Environment= and + EnvironmentFile=. In addition, variables listed + in the section "Environment variables in spawned processes" in + systemd.exec5, + which are considered "static configuration", may be used (this + includes e.g. $USER, but not + $TERM). + + 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: + ExecStart=/bin/sh -c 'dmesg | tac' + + Example: + + ExecStart=/bin/echo one ; /bin/echo "two two" + + This will execute /bin/echo two times, + each time with one argument: one and + two two, respectively. Because two commands are + specified, Type=oneshot must be used. + + Example: + + ExecStart=/bin/echo / >/dev/null & \; \ +/bin/ls + + This will execute /bin/echo + with five arguments: /, + >/dev/null, + &, ;, and + /bin/ls. + + + C escapes supported in command lines and environment variables + + + + + + Literal + Actual value + + + + + \a + bell + + + \b + backspace + + + \f + form feed + + + \n + newline + + + \r + carriage return + + + \t + tab + + + \v + vertical tab + + + \\ + backslash + + + \" + double quotation mark + + + \' + single quotation mark + + + \s + space + + + \xxx + character number xx in hexadecimal encoding + + + \nnn + character number nnn in octal encoding + + + +
+ + + + Examples + + + Simple service + + The following unit file creates a service that will + execute /usr/sbin/foo-daemon. Since no + Type= is specified, the default + Type= will be assumed. + systemd will assume the unit to be started immediately after the + program has begun executing. + + [Unit] +Description=Foo + +[Service] +ExecStart=/usr/sbin/foo-daemon + +[Install] +WantedBy=multi-user.target + + 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 + Type= instead. + + Since no ExecStop= 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 + systemd.kill5 + for details. + + 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 + Type= if the service + understands systemd's notification protocol, + Type= if the service + can background itself or + Type= if the unit + acquires a DBus name once initialization is complete. See + below. + + + + Oneshot service + + Sometimes, units should just execute an action without + keeping active processes, such as a filesystem check or a + cleanup action on boot. For this, + Type= 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: + + [Unit] +Description=Cleanup old Foo data + +[Service] +Type=oneshot +ExecStart=/usr/sbin/foo-cleanup + +[Install] +WantedBy=multi-user.target + + 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. + + Type= are the + only service units that may have more than one + ExecStart= specified. They will be executed + in order until either they are all successful or one of them + fails. + + + + Stoppable oneshot service + + 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. + + For this, systemd knows the setting + RemainAfterExit=, 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 + Type= and + Type=. With + Type=, 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 + Type=, dependencies + will start immediately after the start action has been + dispatched. The following unit provides an example for a simple + static firewall. + + [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 + + Since the unit is considered to be running after the start + action has exited, invoking systemctl start + on that unit again will cause no action to be taken. + + + + Traditional forking services + + Many traditional daemons/services background (i.e. fork, + daemonize) themselves when starting. Set + Type= 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 + RemainAfterExit=), the + service is considered started. + + 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 + $MAINPID variable will be available in + ExecReload=, ExecStop=, + etc. + + 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, $MAINPID 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 PIDFile= 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. + + The following example shows a simple daemon that forks and + just starts one process in the background: + + [Unit] +Description=Some simple daemon + +[Service] +Type=forking +ExecStart=/usr/sbin/my-simple-daemon -d + +[Install] +WantedBy=multi-user.target + + Please see + systemd.kill5 + for details on how you can influence the way systemd terminates + the service. + + + + DBus services + + For services that acquire a name on the DBus system bus, + use Type= and set + BusName= 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: + + [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 + + For bus-activatable services, do not + include a [Install] section in the systemd + service file, but use the SystemdService= + option in the corresponding DBus service file, for example + (/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service): + + [D-BUS Service] +Name=org.example.simple-dbus-service +Exec=/usr/sbin/simple-dbus-service +User=root +SystemdService=simple-dbus-service.service + + Please see + systemd.kill5 + for details on how you can influence the way systemd terminates + the service. + + + + Services that notify systemd about their initialization + + Type= 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 + Type= for this. A + typical service file for such a daemon would look like + this: + + [Unit] +Description=Simple notifying service + +[Service] +Type=notify +ExecStart=/usr/sbin/simple-notifying-service + +[Install] +WantedBy=multi-user.target + + 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 + sd_notify3. + systemd will consider the unit to be in the 'starting' state + until a readiness notification has arrived. + + Please see + systemd.kill5 + for details on how you can influence the way systemd terminates + the service. + + + + + See Also + + systemd1, + systemctl1, + systemd.unit5, + systemd.exec5, + systemd.resource-control5, + systemd.kill5, + systemd.directives7 + + + + 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 @@ + + + + + + + + systemd.slice + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.slice + 5 + + + + systemd.slice + Slice unit configuration + + + + slice.slice + + + + Description + + A unit configuration file whose name ends in + .slice 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, + -.slice. Example: + foo-bar.slice is a slice that is located + within foo.slice, which in turn is located in + the root slice -.slice. + + + Note that slice units cannot be templated, nor is possible to add multiple names to a slice unit by creating + additional symlinks to it. + + By default, service and scope units are placed in + system.slice, virtual machines and containers + registered with + systemd-machined1 + are found in machine.slice, and user sessions + handled by + systemd-logind1 + in user.slice. See + systemd.special5 + for more information. + + See + systemd.unit5 + 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 + systemd.resource-control5 are allowed. + + + See the New + Control Group Interfaces for an introduction on how to make + use of slice units from programs. + + + + Automatic Dependencies + + Slice units automatically gain dependencies of type + After= and Requires= on + their immediate parent slice unit. + + Unless DefaultDependencies=false is used in the [Unit] section, slice + units will implicitly have dependencies of type Conflicts= and Before= on + shutdown.target. 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. + + + + + See Also + + systemd1, + systemd.unit5, + systemd.resource-control5, + systemd.service5, + systemd.scope5, + systemd.special7, + systemd.directives7 + + + + diff --git a/src/grp-system/systemd/systemd.socket.xml b/src/grp-system/systemd/systemd.socket.xml new file mode 100644 index 0000000000..5bf54d8ef3 --- /dev/null +++ b/src/grp-system/systemd/systemd.socket.xml @@ -0,0 +1,860 @@ + + + + + + + + systemd.socket + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.socket + 5 + + + + systemd.socket + Socket unit configuration + + + + socket.socket + + + + Description + + A unit configuration file whose name ends in + .socket encodes information about an IPC or + network socket or a file system FIFO controlled and supervised by + systemd, for socket-based activation. + + This man page lists the configuration options specific to + this unit type. See + systemd.unit5 + 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. + + Additional options are listed in + systemd.exec5, + which define the execution environment the + , , + and + commands are executed in, and in + systemd.kill5, + which define the way the processes are terminated, and in + systemd.resource-control5, + which configure resource control settings for the processes of the + socket. + + For each socket file, a matching service file must exist, + describing the service to start on incoming traffic on the socket + (see + systemd.service5 + 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 + described below. Depending on the setting of the + option described below, this .service + unit must either be named like the .socket unit, but with the + suffix replaced, unless overridden with ; + or it must be a template unit named the same way. Example: a + socket file foo.socket needs a matching + service foo.service if + is set. If + is set, a service template file + foo@.service must exist from which services + are instantiated for each incoming connection. + + Unless DefaultDependencies= in the [Unit] section is set to + , socket units will implicitly have dependencies of type Requires= and + After= on sysinit.target as well as dependencies of type + Conflicts= and Before= on shutdown.target. 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. + + Socket units will have a Before= + dependency on the service which they trigger added implicitly. No + implicit WantedBy= or + RequiredBy= 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 + Requires= dependency may be added. + + 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. + + 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 + sd_listen_fds3 + for details) or via the traditional + inetd8-style + socket passing (i.e. sockets passed in via standard input and + output, using StandardInput=socket in the + service file). + + + + Automatic Dependencies + + Socket units automatically gain a Before= + dependency on the service units they activate. + + Socket units referring to file system paths (such as AF_UNIX + sockets or FIFOs) implicitly gain Requires= and + After= dependencies on all mount units + necessary to access those paths. + + Socket units using the BindToDevice= + setting automatically gain a BindsTo= and + After= dependency on the device unit + encapsulating the specified network interface. + + If DefaultDependencies=yes is set (the + default), socket units automatically gain a + Before= dependency on + sockets.target. They also gain a pair of + After= and Requires= + dependency on sysinit.target, and a pair of + Before= and Conflicts= + dependencies on shutdown.target. These + dependencies ensure that the socket unit is started before normal + services at boot, and is stopped on shutdown. + + Additional implicit dependencies may be added as result of + execution and resource control parameters as documented in + systemd.exec5 + and + systemd.resource-control5. + + + + Options + + 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 + systemd.exec5 + and + systemd.kill5. + The options specific to the [Socket] section of socket units are + the following: + + + + ListenStream= + ListenDatagram= + ListenSequentialPacket= + Specifies an address to listen on for a stream + (SOCK_STREAM), datagram + (SOCK_DGRAM), or sequential packet + (SOCK_SEQPACKET) socket, respectively. + The address can be written in various formats: + + If the address starts with a slash + (/), it is read as file system socket in + the AF_UNIX socket family. + + If the address starts with an at symbol + (@), it is read as abstract namespace + socket in the AF_UNIX family. The + @ is replaced with a + NUL character before binding. For + details, see + unix7. + + If the address string is a single number, it is read as + port number to listen on via IPv6. Depending on the value of + BindIPv6Only= (see below) this might result + in the service being available via both IPv6 and IPv4 + (default) or just via IPv6. + + + 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. + + 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 + BindIPv6Only= setting (see below). + + + Note that SOCK_SEQPACKET (i.e. + ListenSequentialPacket=) is only available + for AF_UNIX sockets. + SOCK_STREAM (i.e. + ListenStream=) when used for IP sockets + refers to TCP sockets, SOCK_DGRAM (i.e. + ListenDatagram=) to UDP. + + 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. + + It is also possible to have more than one socket unit + for the same service when using Service=, + 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. + + 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 FreeBind= option described + below. + + + + ListenFIFO= + Specifies a file system FIFO to listen on. + This expects an absolute file system path as argument. + Behavior otherwise is very similar to the + ListenDatagram= directive + above. + + + + ListenSpecial= + 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 + ListenFIFO= directive above. Use this to + open character device nodes as well as special files in + /proc and + /sys. + + + + ListenNetlink= + Specifies a Netlink family to create a socket + for to listen on. This expects a short string referring to the + AF_NETLINK family name (such as + audit or kobject-uevent) + as argument, optionally suffixed by a whitespace followed by a + multicast group integer. Behavior otherwise is very similar to + the ListenDatagram= directive + above. + + + + ListenMessageQueue= + 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 + ListenFIFO= directive above. On Linux + message queue descriptors are actually file descriptors and + can be inherited between processes. + + + + ListenUSBFunction= + Specifies a USB + FunctionFS endpoint location to listen on, for + implementation of USB gadget functions. This expects an + absolute file system path as the argument. Behavior otherwise + is very similar to the ListenFIFO= + directive above. Use this to open the FunctionFS endpoint + ep0. When using this option, the + activated service has to have the + USBFunctionDescriptors= and + USBFunctionStrings= options set. + + + + + SocketProtocol= + Takes a one of + or . Specifies a socket protocol + (IPPROTO_UDPLITE) UDP-Lite + (IPPROTO_SCTP) SCTP socket respectively. + + + + + BindIPv6Only= + Takes a one of , + or . Controls + the IPV6_V6ONLY socket option (see + ipv67 + for details). If , IPv6 sockets bound + will be accessible via both IPv4 and IPv6. If + , they will be accessible via IPv6 + only. If (which is the default, + surprise!), the system wide default setting is used, as + controlled by + /proc/sys/net/ipv6/bindv6only, which in + turn defaults to the equivalent of + . + + + + + Backlog= + 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 + listen2 + for details. Defaults to SOMAXCONN (128). + + + + BindToDevice= + 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 socket7 + for details). If this option is used, an automatic dependency + from this socket unit on the network interface device unit + (systemd.device5 + is created. Note that setting this parameter might result in + additional dependencies to be added to the unit (see + above). + + + + SocketUser= + SocketGroup= + + 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. + + + + SocketMode= + 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. + + + + DirectoryMode= + 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. + + + + Accept= + 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 . For + performance reasons, it is recommended to write new daemons + only in a way that is suitable for + . A daemon listening on an + AF_UNIX socket may, but does not need to, + call + close2 + on the received socket before exiting. However, it must not + unlink the socket from a file system. It should not invoke + shutdown2 + on sockets it got with Accept=false, but it + may do so for sockets it got with + Accept=true set. Setting + Accept=true is mostly useful to allow + daemons designed for usage with + inetd8 + to work unmodified with systemd socket + activation. + + For IPv4 and IPv6 connections, the REMOTE_ADDR + environment variable will contain the remote IP address, and REMOTE_PORT + will contain the remote port. This is the same as the format used by CGI. + For SOCK_RAW, the port is the IP protocol. + + + + Writable= + Takes a boolean argument. May only be used in + conjunction with ListenSpecial=. If true, + the specified special file is opened in read-write mode, if + false, in read-only mode. Defaults to false. + + + + MaxConnections= + The maximum number of connections to + simultaneously run services instances for, when + 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 + or datagram sockets. Defaults to + 64. + + + + KeepAlive= + Takes a boolean argument. If true, the TCP/IP + stack will send a keep alive message after 2h (depending on + the configuration of + /proc/sys/net/ipv4/tcp_keepalive_time) + for all TCP streams accepted on this socket. This controls the + SO_KEEPALIVE socket option (see + socket7 + and the TCP + Keepalive HOWTO for details.) Defaults to + . + + + + KeepAliveTimeSec= + 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 + socket7 + and the TCP + Keepalive HOWTO for details.) + Defaults value is 7200 seconds (2 hours). + + + + KeepAliveIntervalSec= + 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 + socket7 + and the TCP + Keepalive HOWTO for details.) Defaults value is 75 + seconds. + + + + KeepAliveProbes= + 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 + socket7 + and the TCP + Keepalive HOWTO for details.) Defaults value is + 9. + + + + NoDelay= + 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 + tcp7 + Defaults to . + + + + Priority= + Takes an integer argument controlling the + priority for all traffic sent from this socket. This controls + the SO_PRIORITY socket option (see + socket7 + for details.). + + + + DeferAcceptSec= + + 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 + TCP_DEFER_ACCEPT socket option will be + used (see + tcp7), + 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 honouring 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. + + + If the client also uses the + TCP_DEFER_ACCEPT 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"). + + Disabled by default. + + + + + ReceiveBuffer= + SendBuffer= + 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 + socket7 + for details.). The usual suffixes K, M, G are supported and + are understood to the base of 1024. + + + + IPTOS= + 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 + ip7 + for details.). Either a numeric string or one of + , , + or may + be specified. + + + + IPTTL= + 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 + ip7 + and + ipv67 + for details.) + + + + Mark= + 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 + iptables8 + for details. + + + + ReusePort= + Takes a boolean value. If true, allows + multiple + bind2s + to this TCP or UDP port. This controls the SO_REUSEPORT socket + option. See + socket7 + for details. + + + + SmackLabel= + SmackLabelIPIn= + SmackLabelIPOut= + Takes a string value. Controls the extended + attributes security.SMACK64, + security.SMACK64IPIN and + security.SMACK64IPOUT, respectively, i.e. + the security label of the FIFO, or the security label for the + incoming or outgoing connections of the socket, respectively. + See Smack.txt + for details. + + + + SELinuxContextFromNet= + 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 SELinuxContext= option. + This configuration option only affects sockets with + Accept= mode set to + true. Also note that this option is useful + only when MLS/MCS SELinux policy is deployed. Defaults to + false. + + + + PipeSize= + Takes a size in bytes. Controls the pipe + buffer size of FIFOs configured in this socket unit. See + fcntl2 + for details. The usual suffixes K, M, G are supported and are + understood to the base of 1024. + + + + MessageQueueMaxMessages=, + MessageQueueMessageSize= + 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 + mq_setattr3 + for details. + + + + FreeBind= + 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 . + + + + Transparent= + Takes a boolean value. Controls the + IP_TRANSPARENT socket option. Defaults to + . + + + + Broadcast= + Takes a boolean value. This controls the + SO_BROADCAST socket option, which allows broadcast datagrams + to be sent from this socket. Defaults to + . + + + + PassCredentials= + Takes a boolean value. This controls the + SO_PASSCRED socket option, which allows + AF_UNIX sockets to receive the + credentials of the sending process in an ancillary message. + Defaults to . + + + + PassSecurity= + Takes a boolean value. This controls the + SO_PASSSEC socket option, which allows + AF_UNIX sockets to receive the security + context of the sending process in an ancillary message. + Defaults to . + + + + TCPCongestion= + 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. + + + + ExecStartPre= + ExecStartPost= + 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 + ExecStartPre= of service unit + files. + + + + ExecStopPre= + ExecStopPost= + 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 + ExecStartPre= of service unit + files. + + + + TimeoutSec= + Configures the time to wait for the commands + specified in ExecStartPre=, + ExecStartPost=, + ExecStopPre= and + ExecStopPost= 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 + SIGTERM, and after another delay of this + time with SIGKILL. (See + in + systemd.kill5.) + Takes a unit-less value in seconds, or a time span value such + as "5min 20s". Pass 0 to disable the + timeout logic. Defaults to + DefaultTimeoutStartSec= from the manager + configuration file (see + systemd-system.conf5). + + + + + Service= + Specifies the service unit name to activate on + incoming traffic. This setting is only allowed for sockets + with Accept=no. 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). + + + + RemoveOnStop= + 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 Symlinks=. 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. + + + + Symlinks= + 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. + + + + FileDescriptorName= + 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 + sd_listen_fds_with_names3 + call to acquire the names configured for the received file + descriptors. Names may contain any ASCII character, but must + exclude control characters and :, 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 .socket + suffix. + + + + TriggerLimitIntervalSec= + TriggerLimitBurst= + + Configures a limit on how often this socket unit my be activated within a specific time + interval. The TriggerLimitIntervalSec= may be used to configure the length of the time + interval in the usual time units us, ms, s, + min, h, … and defaults to 2s (See + systemd.time7 for details on + the various time units understood). The TriggerLimitBurst= setting takes a positive integer + value and specifies the number of permitted activations per time interval, and defaults to 200 for + Accept=yes 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. + + + + + Check + systemd.exec5 + and + systemd.kill5 + for more settings. + + + + + See Also + + systemd1, + systemctl1, + systemd.unit5, + systemd.exec5, + systemd.kill5, + systemd.resource-control5, + systemd.service5, + systemd.directives7, + sd_listen_fds3, + sd_listen_fds_with_names3 + + + For more extensive descriptions see the "systemd for Developers" series: + Socket Activation, + Socket Activation, part II, + Converting inetd Services, + Socket Activated Internet Services and OS Containers. + + + + diff --git a/src/grp-system/systemd/systemd.special.xml b/src/grp-system/systemd/systemd.special.xml new file mode 100644 index 0000000000..26974ed73f --- /dev/null +++ b/src/grp-system/systemd/systemd.special.xml @@ -0,0 +1,935 @@ + + + + + + + + + systemd.special + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.special + 7 + + + + systemd.special + Special systemd units + + + + basic.target, + bluetooth.target, + ctrl-alt-del.target, + cryptsetup.target, + cryptsetup-pre.target, + dbus.service, + dbus.socket, + default.target, + display-manager.service, + emergency.target, + exit.target, + final.target, + getty.target, + graphical.target, + halt.target, + hibernate.target, + hybrid-sleep.target, + initrd-fs.target, + kbrequest.target, + kexec.target, + local-fs.target, + local-fs-pre.target, + multi-user.target, + network.target, + network-online.target, + network-pre.target, + nss-lookup.target, + nss-user-lookup.target, + paths.target, + poweroff.target, + printer.target, + reboot.target, + remote-fs.target, + remote-fs-pre.target, + rescue.target, + initrd-root-device.target, + initrd-root-fs.target, + rpcbind.target, + runlevel2.target, + runlevel3.target, + runlevel4.target, + runlevel5.target, + shutdown.target, + sigpwr.target, + sleep.target, + slices.target, + smartcard.target, + sockets.target, + sound.target, + suspend.target, + swap.target, + sysinit.target, + syslog.socket, + system-update.target, + time-sync.target, + timers.target, + umount.target, + -.slice, + system.slice, + user.slice, + machine.slice + + + + Description + + A few units are treated specially by systemd. They have + special internal semantics and cannot be renamed. + + + + Special System Units + + + + basic.target + + A special target unit covering basic boot-up. + + systemd automatically adds dependencies of the types + Requires= and After= + for this target unit to all services (except for those with + DefaultDependencies=no). + + Usually, this should pull-in all local mount points plus + /var, /tmp and + /var/tmp, 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. + + + 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 + bootup7 + for details on the targets involved. + + + + + + ctrl-alt-del.target + + systemd starts this target whenever Control+Alt+Del is + pressed on the console. Usually, this should be aliased + (symlinked) to reboot.target. + + + + cryptsetup.target + + A target that pulls in setup services for all + encrypted block devices. + + + + dbus.service + + 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. + + + + dbus.socket + + A special unit for the D-Bus system bus socket. All + units with Type=dbus automatically gain a + dependency on this unit. + + + + default.target + + The default unit systemd starts at bootup. Usually, + this should be aliased (symlinked) to + multi-user.target or + graphical.target. + + The default unit systemd starts at bootup can be + overridden with the systemd.unit= kernel + command line option. + + + + display-manager.service + + The display manager service. Usually, this should be + aliased (symlinked) to gdm.service or a + similar display manager service. + + + + emergency.target + + 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 + systemd.unit=; it is also used when a file system check on a required file system fails, + and boot-up cannot continue. Compare with rescue.target, which serves a similar purpose, + but also starts the most basic services and mounts all file systems. + + Use the systemd.unit=emergency.target kernel command line option to boot into this + mode. A short alias for this kernel command line option is emergency, for compatibility + with SysV. + + In many ways booting into emergency.target is similar to the effect of booting + with init=/bin/sh 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. + + + + exit.target + + A special service unit for shutting down the system or + user service manager. It is equivalent to + poweroff.target on non-container + systems, and also works in containers. + + systemd will start this unit when it receives a + request to shut down over D-Bus or a + SIGTERM or SIGINT + signal when running as user service daemon. + + Normally, this (indirectly) pulls in + shutdown.target, which in turn should be + conflicted by all units that want to be scheduled for + shutdown when the service manager starts to exit. + + + + final.target + + 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. + + + + + getty.target + + A special target unit that pulls in statically + configured local TTY getty instances. + + + + + graphical.target + + A special target unit for setting up a graphical login + screen. This pulls in + multi-user.target. + + Units that are needed for graphical logins shall add + Wants= dependencies for their unit to + this unit (or multi-user.target) during + installation. This is best configured via + WantedBy=graphical.target in the unit's + [Install] section. + + + + hibernate.target + + A special target unit for hibernating the system. This + pulls in sleep.target. + + + + hybrid-sleep.target + + A special target unit for hibernating and suspending + the system at the same time. This pulls in + sleep.target. + + + + halt.target + + A special target unit for shutting down and halting + the system. Note that this target is distinct from + poweroff.target in that it generally + really just halts the system rather than powering it + down. + + Applications wanting to halt the system should start + this unit. + + + + initrd-fs.target + + systemd-fstab-generator3 + automatically adds dependencies of type + Before= to + sysroot-usr.mount and all mount points + found in /etc/fstab that have + and not have + mount options set. + + + + kbrequest.target + + systemd starts this target whenever Alt+ArrowUp is + pressed on the console. This is a good candidate to be + aliased (symlinked) to + rescue.target. + + + + kexec.target + + A special target unit for shutting down and rebooting + the system via kexec. + + Applications wanting to reboot the system with kexec + should start this unit. + + + + local-fs.target + + systemd-fstab-generator3 + automatically adds dependencies of type + Before= to all mount units that refer to + local mount points for this target unit. In addition, it + adds dependencies of type Wants= to this + target unit for those mounts listed in + /etc/fstab that have the + mount option set. + + + + multi-user.target + + A special target unit for setting up a multi-user + system (non-graphical). This is pulled in by + graphical.target. + + Units that are needed for a multi-user system shall + add Wants= dependencies for their unit to + this unit during installation. This is best configured via + WantedBy=multi-user.target in the unit's + [Install] section. + + + + network-online.target + + Units that strictly require a configured network + connection should pull in + network-online.target (via a + Wants= 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. + + Note the distinction between this unit and + network.target. 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, network.target 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, network.target + is part of the boot of most systems, while + network-online.target is not, except + when at least one unit requires it. Also see Running + Services After the Network is up for more + information. + + 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. + + + + paths.target + + A special target unit that sets up all path units (see + systemd.path5 + for details) that shall be active after boot. + + It is recommended that path units installed by + applications get pulled in via Wants= + dependencies from this unit. This is best configured via a + WantedBy=paths.target in the path unit's + [Install] section. + + + + poweroff.target + + A special target unit for shutting down and powering + off the system. + + Applications wanting to power off the system should + start this unit. + + runlevel0.target is an alias for + this target unit, for compatibility with SysV. + + + + reboot.target + + A special target unit for shutting down and rebooting + the system. + + Applications wanting to reboot the system should start + this unit. + + runlevel6.target is an alias for + this target unit, for compatibility with SysV. + + + + remote-fs.target + + Similar to local-fs.target, but + for remote mount points. + + systemd automatically adds dependencies of type + After= for this target unit to all SysV + init script service units with an LSB header referring to + the $remote_fs facility. + + + + rescue.target + + 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 + emergency.target, which is much more reduced and does not provide the file systems or + most basic services. + + runlevel1.target is an alias for this target unit, for compatibility with + SysV. + + Use the systemd.unit=rescue.target kernel command line option to boot into this + mode. A short alias for this kernel command line option is 1, for compatibility with + SysV. + + + + initrd-root-device.target + + A special initrd target unit that is reached when the root filesystem device is available, but before + it has been mounted. + systemd-fstab-generator3 + and + systemd-gpt-auto-generator3 + automatically setup the appropiate dependencies to make this happen. + + + + + initrd-root-fs.target + + systemd-fstab-generator3 + automatically adds dependencies of type + Before= to the + sysroot.mount unit, which is generated + from the kernel command line. + + + + + runlevel2.target + runlevel3.target + runlevel4.target + runlevel5.target + + 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) multi-user.target + (for runlevel 2) or graphical.target + (the others). + + + + shutdown.target + + A special target unit that terminates the services on + system shutdown. + + Services that shall be terminated on system shutdown + shall add Conflicts= dependencies to this + unit for their service unit, which is implicitly done when + DefaultDependencies=yes is set (the + default). + + + + sigpwr.target + + 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. + + + + sleep.target + + A special target unit that is pulled in by + suspend.target, + hibernate.target and + hybrid-sleep.target and may be used to + hook units into the sleep state logic. + + + + slices.target + + A special target unit that sets up all slice units (see + systemd.slice5 for + details) that shall be active after boot. By default the generic user.slice, + system.slice, machines.slice slice units, as well as the root + slice unit -.slice are pulled in and ordered before this unit (see below). + + It's a good idea to add WantedBy=slices.target lines to the [Install] + section of all slices units that may be installed dynamically. + + + + sockets.target + + A special target unit that sets up all socket + units (see + systemd.socket5 + for details) that shall be active after boot. + + Services that can be socket-activated shall add + Wants= dependencies to this unit for + their socket unit during installation. This is best + configured via a WantedBy=sockets.target + in the socket unit's [Install] + section. + + + + suspend.target + + A special target unit for suspending the system. This + pulls in sleep.target. + + + + swap.target + + Similar to local-fs.target, but + for swap partitions and swap files. + + + + sysinit.target + + This target pulls in the services required for system + initialization. System services pulled in by this target should + declare DefaultDependencies=no 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 + bootup7. + + + + + syslog.socket + + 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 Syslog + Interface document. + + + + system-update.target + + A special target unit that is used for off-line system + updates. + systemd-system-update-generator8 + will redirect the boot process to this target if + /system-update exists. For more + information see the System + Updates Specification. + + + + timers.target + + A special target unit that sets up all timer units + (see + systemd.timer5 + for details) that shall be active after boot. + + It is recommended that timer units installed by + applications get pulled in via Wants= + dependencies from this unit. This is best configured via + WantedBy=timers.target in the timer + unit's [Install] section. + + + + umount.target + + A special target unit that unmounts all mount and + automount points on system shutdown. + + Mounts that shall be unmounted on system shutdown + shall add Conflicts dependencies to this unit for their + mount unit, which is implicitly done when + DefaultDependencies=yes is set (the + default). + + + + + + + + Special System Units for Devices + + 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. + + + + bluetooth.target + + This target is started automatically as soon as a + Bluetooth controller is plugged in or becomes available at + boot. + + This may be used to pull in Bluetooth management + daemons dynamically when Bluetooth hardware is found. + + + + printer.target + + This target is started automatically as soon as a + printer is plugged in or becomes available at boot. + + This may be used to pull in printer management daemons + dynamically when printer hardware is found. + + + + smartcard.target + + This target is started automatically as soon as a + smartcard controller is plugged in or becomes available at + boot. + + This may be used to pull in smartcard management + daemons dynamically when smartcard hardware is found. + + + + sound.target + + This target is started automatically as soon as a + sound card is plugged in or becomes available at + boot. + + This may be used to pull in audio management daemons + dynamically when audio hardware is found. + + + + + + + Special Passive System Units + + 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 passive 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 + Wants= type dependency). + + Note that these passive units cannot be started manually, + i.e. systemctl start time-sync.target 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. + + + + cryptsetup-pre.target + + 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. + + + + local-fs-pre.target + + This target unit is + automatically ordered before + all local mount points marked + with + (see above). It can be used to + execute certain units before + all local mounts. + + + + network.target + + 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 + network.target 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 + Running + Services After the Network is up for more + information. Also see + network-online.target described + above. + + systemd automatically adds dependencies of type + After= for this target unit to all SysV + init script service units with an LSB header referring to + the $network facility. + + + + network-pre.target + + 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. + + + + nss-lookup.target + + 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 + nss-user-lookup.target 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 After= for this + target unit to all SysV init script service units with an + LSB header referring to the $named + facility. + + + + nss-user-lookup.target + + 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 + nss-lookup.target 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. + + + + remote-fs-pre.target + + 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 + Wants= type dependency. If the unit wants + to be pulled in by the first remote mount showing up, it + should use network-online.target (see + above). + + + + rpcbind.target + + The portmapper/rpcbind pulls in this target and orders + itself before it, to indicate its availability. systemd + automatically adds dependencies of type + After= for this target unit to all SysV + init script service units with an LSB header referring to + the $portmap facility. + + + + time-sync.target + + 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 + After= for this target unit to all SysV + init script service units with an LSB header referring to + the $time facility. + + + + + + + Special User Units + + When systemd runs as a user instance, the following special + units are available, which have similar definitions as their + system counterparts: + exit.target, + default.target, + shutdown.target, + sockets.target, + timers.target, + paths.target, + bluetooth.target, + printer.target, + smartcard.target, + sound.target. + + + + Special Slice Units + + There are four .slice units which form + the basis of the hierarchy for assignment of resources for + services, users, and virtual machines or containers. + + + + -.slice + + 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. + + + + + system.slice + + By default, all system services started by + systemd are found in this slice. + + + + + user.slice + + By default, all user processes and services started on + behalf of the user, including the per-user systemd instance + are found in this slice. + + + + + machine.slice + + By default, all virtual machines and containers + registered with systemd-machined are + found in this slice. + + + + + + + + See Also + + systemd1, + systemd.unit5, + systemd.service5, + systemd.socket5, + systemd.target5, + systemd.slice5, + bootup7, + systemd-fstab-generator8 + + + + 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 @@ + + + + + + + + systemd.swap + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.swap + 5 + + + + systemd.swap + Swap unit configuration + + + + swap.swap + + + + Description + + A unit configuration file whose name ends in + .swap encodes information about a swap device + or file for memory paging controlled and supervised by + systemd. + + This man page lists the configuration options specific to + this unit type. See + systemd.unit5 + 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. + + Additional options are listed in + systemd.exec5, + which define the execution environment the swapon8 + binary is executed in, in + systemd.kill5, + which define the way these processes are + terminated, and in + systemd.resource-control5, + which configure resource control settings for these processes of the + unit. + + Swap units must be named after the devices or files they control. Example: the swap device /dev/sda5 must be configured in a unit file dev-sda5.swap. For + details about the escaping logic used to convert a file system path to a unit name, see + systemd.unit5. Note that swap + units cannot be templated, nor is possible to add multiple names to a swap unit by creating additional symlinks to + it. + + + + Automatic Dependencies + + All swap units automatically get the + BindsTo= and After= + dependencies on the device units or the mount units of the files + they are activated from. + + Swap units with DefaultDependencies= in the [Unit] section enabled + implicitly acquire a Conflicts= and an After= dependency on + umount.target so that they are deactivated at shutdown, unless + DefaultDependencies=no is specified. + + Additional implicit dependencies may be added as result of + execution and resource control parameters as documented in + systemd.exec5 + and + systemd.resource-control5. + + + + <filename>fstab</filename> + + Swap units may either be configured via unit files, or via + /etc/fstab (see + fstab5 + for details). Swaps listed in /etc/fstab will + be converted into native units dynamically at boot and when the + configuration of the system manager is reloaded. See + systemd-fstab-generator8 + for details about the conversion. + + If a swap device or file is configured in both + /etc/fstab and a unit file, the configuration + in the latter takes precedence. + + When reading /etc/fstab, a few special + options are understood by systemd which influence how dependencies + are created for swap units. + + + + + + + With , the swap unit + will not be added as a dependency for + swap.target. This means that it will not + be activated automatically during boot, unless it is pulled in + by some other unit. The option has the + opposite meaning and is the default. + + + + + + + With , the swap unit + will be only wanted, not required by + swap.target. This means that the boot + will continue even if this swap device is not activated + successfully. + + + + + + + Options + + 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 + systemd.exec5 + and + systemd.kill5. + The options specific to the [Swap] section of swap units are the + following: + + + + + What= + Takes an absolute path of a device node or + file to use for paging. See + swapon8 + for details. If this refers to a device node, a dependency on + the respective device unit is automatically created. (See + systemd.device5 + for more information.) If this refers to a file, a dependency + on the respective mount unit is automatically created. (See + systemd.mount5 + for more information.) This option is + mandatory. + + + + Priority= + + 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 in the + Options= key. + + + + Options= + + 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 + swapon8 + for more information.) + + + + TimeoutSec= + 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 SIGTERM, and after another + delay of this time with SIGKILL. (See + in + systemd.kill5.) + Takes a unit-less value in seconds, or a time span value such + as "5min 20s". Pass 0 to disable the + timeout logic. Defaults to + DefaultTimeoutStartSec= from the manager + configuration file (see + systemd-system.conf5). + + + + + Check + systemd.exec5 + and + systemd.kill5 + for more settings. + + + + See Also + + systemd1, + systemctl1, + systemd.unit5, + systemd.exec5, + systemd.kill5, + systemd.resource-control5, + systemd.device5, + systemd.mount5, + swapon8, + systemd-fstab-generator8, + systemd.directives7 + + + + diff --git a/src/grp-system/systemd/systemd.target.xml b/src/grp-system/systemd/systemd.target.xml new file mode 100644 index 0000000000..ab910d75dd --- /dev/null +++ b/src/grp-system/systemd/systemd.target.xml @@ -0,0 +1,103 @@ + + + + + + + + systemd.target + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.target + 5 + + + + systemd.target + Target unit configuration + + + + target.target + + + + Description + + A unit configuration file whose name ends in + .target encodes information about a target unit + of systemd, which is used for grouping units and as well-known + synchronization points during start-up. + + This unit type has no specific options. See + systemd.unit5 + 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. + + 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 runlevel3.target exist + which are used by the SysV runlevel compatibility code in systemd. + See + systemd.special7 + for details). + + + + Automatic Dependencies + + Unless DefaultDependencies= in the [Unit] section is set to + , target units will implicitly complement all configured dependencies of type + Wants=, Requires= with dependencies of type After=, unless + an ordering dependency of any kind between the target and the respective other unit is already in place. Note that + this behaviour is disabled if either unit has DefaultDependencies=no. + + + + See Also + + systemd1, + systemctl1, + systemd.unit5, + systemd.special7, + systemd.directives7 + + + + diff --git a/src/grp-system/systemd/systemd.time.xml b/src/grp-system/systemd/systemd.time.xml new file mode 100644 index 0000000000..ffcac82263 --- /dev/null +++ b/src/grp-system/systemd/systemd.time.xml @@ -0,0 +1,313 @@ + + + + + + + + + systemd.time + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.time + 7 + + + + systemd.time + Time and date specifications + + + + Description + + In systemd, timestamps, time spans, and calendar events are + displayed and may be specified in closely related syntaxes. + + + + Displaying Time Spans + + 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. + + 2h 30min + + All specified time values are meant to be added up. The + above hence refers to 150 minutes. + + + + Parsing Time Spans + + When parsing, systemd will accept the same time span syntax. + Separating spaces may be omitted. The following time units are + understood: + + + usec, us + msec, ms + seconds, second, sec, s + minutes, minute, min, m + hours, hour, hr, h + days, day, d + weeks, week, w + months, month, M (defined as 30.44 days) + years, year, y (define as 365.25 days) + + + If no time unit is specified, generally seconds are assumed, + but some exceptions exist and are marked as such. In a few cases + ns, nsec is accepted too, + where the granularity of the time span allows for this. + + Examples for valid time span specifications: + + 2 h +2hours +48hr +1y 12month +55s500ms +300ms20s 5day + + + + Displaying Timestamps + + Timestamps refer to specific, unique points in time. On + display, systemd will format these in the local timezone as + follows: + + Fri 2012-11-23 23:02:15 CET + + The weekday is printed according to the locale choice of the + user. + + + + Parsing Timestamps + + When parsing, systemd will accept a similar syntax, but + expects no timezone specification, unless it is given as the + literal string "UTC". In this case, the time is considered in UTC, + otherwise in the local timezone. The weekday specification is + optional, but when the weekday is specified, it must either be in + the abbreviated (Wed) or non-abbreviated + (Wednesday) 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). + + A timestamp is considered invalid if a weekday is specified + and the date does not actually match the specified day of the + week. + + When parsing, systemd will also accept a few special + placeholders instead of timestamps: now may be + used to refer to the current time (or of the invocation of the + command that is currently executed). today, + yesterday, and tomorrow refer to + 00:00:00 of the current day, the day before, or the next day, + respectively. + + When parsing, systemd will also accept relative time + specifications. A time span (see above) that is prefixed with + + is evaluated to the current time plus the + specified time span. Correspondingly, a time span that is prefixed + with - is evaluated to the current time minus + the specified time span. Instead of prefixing the time span with + + or -, it may also be + suffixed with a space and the word left or + ago. + + Finally, a timespan prefixed with @ is + evaluated relative to the UNIX time epoch 1st Jan, 1970, + 00:00. + + 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): + + 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:13.9900009 → Fri 2012-11-23 11:12:13 + format_timestamp_us: Fri 2012-11-23 11:12:13.990000 + 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 + +3h30min UTC → -EINVAL + -5s → Fri 2012-11-23 18:15:17 + 11min ago → Fri 2012-11-23 18:04:22 + 11min ago UTC → -EINVAL + @1395716396 → Tue 2014-03-25 03:59:56 + + Note that timestamps printed by systemd will not be parsed + correctly by systemd, as the timezone specification is not + accepted, and printing timestamps is subject to locale settings + for the weekday, while parsing only accepts English weekday + names. + + In some cases, systemd will display a relative timestamp + (relative to the current time, or the time of invocation of the + command) instead or in addition to an absolute timestamp as + described above. A relative timestamp is formatted as + follows: + + 2 months 5 days ago + + Note that any relative timestamp will also parse correctly + where a timestamp is expected. (see above) + + + + Calendar Events + + 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: + + Thu,Fri 2012-*-1,5 11:12:13 + + 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. + + 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 - refers to a range of + continuous weekdays. , and - + may be combined freely. + + In the date and time specifications, any component may be + specified as * 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 + / and a repetition value, which indicates that + the value and all values plus multiples of the repetition value + are matched. + + The seconds component may contain decimal fractions both in + the value and the repetition. All fractions are rounded to 6 + decimal places. + + 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, :00 is + assumed. + + A timezone specification is not expected, unless it is given + as the literal string "UTC", similarly to timestamps. + + The special expressions + minutely, + hourly, daily, + monthly, weekly, + yearly, + quarterly, + semiannually may be used as + calendar events which refer to + *-*-* *:*:00, + *-*-* *:00:00, + *-*-* 00:00:00, + *-*-01 00:00:00, + Mon *-*-* 00:00:00, + *-01-01 00:00:00, + *-01,04,07,10-01 00:00:00 and + *-01,07-01 00:00:00, respectively. + + + Examples for valid timestamps and their + normalized form: + + 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 + 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-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 + + Calendar events are used by timer units, see + systemd.timer5 + for details. + + + + + See Also + + systemd1, + journalctl1, + systemd.timer5, + systemd.unit5, + systemd.directives7 + + + + diff --git a/src/grp-system/systemd/systemd.timer.xml b/src/grp-system/systemd/systemd.timer.xml new file mode 100644 index 0000000000..0fa95e97a8 --- /dev/null +++ b/src/grp-system/systemd/systemd.timer.xml @@ -0,0 +1,313 @@ + + + + + + + + systemd.timer + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.timer + 5 + + + + systemd.timer + Timer unit configuration + + + + timer.timer + + + + Description + + A unit configuration file whose name ends in + .timer encodes information about a timer + controlled and supervised by systemd, for timer-based + activation. + + This man page lists the configuration options specific to + this unit type. See + systemd.unit5 + 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. + + 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 + foo.timer activates a matching service + foo.service. The unit to activate may be + controlled by Unit= (see below). + + 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 RemainAfterExit= set (which stay around continously 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. + + + + Automatic Dependencies + + Timer units automatically gain a Before= + dependency on the service they are supposed to activate. + + Unless DefaultDependencies= in the [Unit] section is set to + , all timer units will implicitly have dependencies of type Requires= and + After= on sysinit.target, a dependency of type Before= + on timers.target, as well as Conflicts= and Before= on + shutdown.target to ensure that they are stopped cleanly prior to system shutdown. Timer units + with at least one OnCalendar= directive will have an additional After= + dependency on timer-sync.target 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 + DefaultDependencies= option. + + + + Options + + 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: + + + + OnActiveSec= + OnBootSec= + OnStartupSec= + OnUnitActiveSec= + OnUnitInactiveSec= + + Defines monotonic timers relative to different + starting points: OnActiveSec= defines a + timer relative to the moment the timer itself is activated. + OnBootSec= defines a timer relative to when + the machine was booted up. OnStartupSec= + defines a timer relative to when systemd was first started. + OnUnitActiveSec= defines a timer relative + to when the unit the timer is activating was last activated. + OnUnitInactiveSec= defines a timer relative + to when the unit the timer is activating was last + deactivated. + + Multiple directives may be combined of the same and of + different types. For example, by combining + OnBootSec= and + OnUnitActiveSec=, it is possible to define + a timer that elapses in regular intervals and activates a + specific service each time. + + 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 + systemd.time7. + + If a timer configured with OnBootSec= + or OnStartupSec= 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. + + These are monotonic timers, independent of wall-clock + time and timezones. If the computer is temporarily suspended, + the monotonic clock stops too. + + 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. + + Note that timers do not necessarily expire at the + precise time configured with these settings, as they are + subject to the AccuracySec= setting + below. + + + + + OnCalendar= + + Defines realtime (i.e. wallclock) timers with + calendar event expressions. See + systemd.time7 + for more information on the syntax of calendar event + expressions. Otherwise, the semantics are similar to + OnActiveSec= and related settings. + + Note that timers do not necessarily expire at the + precise time configured with this setting, as it is subject to + the AccuracySec= setting + below. + + + + AccuracySec= + + 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 + OnCalendar=, + OnActiveSec=, + OnBootSec=, + OnStartupSec=, + OnUnitActiveSec= or + OnUnitInactiveSec= and ending the time + configured with AccuracySec= 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 + systemd-system.conf5's + TimerSlackNSec= setting. See + prctl2 + for details. To optimize power consumption, make sure to set + this value as high as possible and as low as + necessary. + + + + RandomizedDelaySec= + + 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 + AccuracySec= 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 + RandomizedDelaySec= and + AccuracySec= 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 + AccuracySec= defaults to 1min and + RandomizedDelaySec= 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 + RandomizedDelaySec= to a higher value, and + AccuracySec=1us. + + + + Unit= + + The unit to activate when this timer elapses. + The argument is a unit name, whose suffix is not + .timer. 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. + + + + + Persistent= + + 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 OnCalendar=. Defaults + to false. + + + + + WakeSystem= + + 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 false. + + + + RemainAfterElapse= + + 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 + RemainAfterElapse= is on, it will not be + started again, and is guaranteed to elapse only once. However, + if RemainAfterElapse= is off, it might be + started again if it is already elapsed, and thus be triggered + multiple times. Defaults to + yes. + + + + + + See Also + + systemd1, + systemctl1, + systemd.unit5, + systemd.service5, + systemd.time7, + systemd.directives7, + systemd-system.conf5, + prctl2 + + + + diff --git a/src/grp-system/systemd/systemd.unit.xml b/src/grp-system/systemd/systemd.unit.xml new file mode 100644 index 0000000000..341789cd47 --- /dev/null +++ b/src/grp-system/systemd/systemd.unit.xml @@ -0,0 +1,1484 @@ + + +%entities; +]> + + + + + + + systemd.unit + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.unit + 5 + + + + systemd.unit + Unit configuration + + + + service.service, + socket.socket, + device.device, + mount.mount, + automount.automount, + swap.swap, + target.target, + path.path, + timer.timer, + slice.slice, + scope.scope + + /etc/systemd/system/* +/run/systemd/system/* +/usr/lib/systemd/system/* +… + + + ~/.config/systemd/user/* +/etc/systemd/user/* +$XDG_RUNTIME_DIR/systemd/user/* +/run/systemd/user/* +~/.local/share/systemd/user/* +/usr/lib/systemd/user/* +… + + + + + Description + + 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 + systemd1, + a resource management slice or + a group of externally created processes. The syntax is inspired by + XDG + Desktop Entry Specification .desktop + files, which are in turn inspired by Microsoft Windows + .ini files. + + 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. + + 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: + systemd.service5, + systemd.socket5, + systemd.device5, + systemd.mount5, + systemd.automount5, + systemd.swap5, + systemd.target5, + systemd.path5, + systemd.timer5, + systemd.slice5, + systemd.scope5. + + + 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 + .desktop file format. + + Unit files are loaded from a set of paths determined during + compilation, described in the next section. + + 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 , 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. + + Boolean arguments used in unit files can be written in + various formats. For positive settings the strings + , , + and are equivalent. For negative settings, the + strings , , + and are + equivalent. + + 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: "50" refers to 50 seconds; "2min + 200ms" refers to 2 minutes plus 200 milliseconds, i.e. 120200ms. + The following time units are understood: s, min, h, d, w, ms, us. + For details see + systemd.time7. + + 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. + + Along with a unit file foo.service, the + directory foo.service.wants/ may exist. All + unit files symlinked from such a directory are implicitly added as + dependencies of type Wants= 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 Wants=, see below. The preferred way to + create symlinks in the .wants/ directory of a + unit file is with the enable command of the + systemctl1 + tool which reads information from the [Install] section of unit + files (see below). A similar functionality exists for + Requires= type dependencies as well, the + directory suffix is .requires/ in this + case. + + Along with a unit file foo.service, a "drop-in" directory + foo.service.d/ may exist. All files with the suffix .conf 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 .d/ subdirectory and read its + .conf files, followed by the template .d/ subdirectory and the + .conf files there. Also note that settings from the [Install] section are not + honoured in drop-in unit files, and have no effect. + + In addition to /etc/systemd/system, + the drop-in .conf files for system services + can be placed in /usr/lib/systemd/system or + /run/systemd/system directories. Drop-in + files in /etc take precedence over those in + /run which in turn take precedence over + those in /usr/lib. Drop-in files under any of + these directories take precedence over unit files wherever located. + (Of course, since /run is temporary and + /usr/lib is for vendors, it is unlikely + drop-ins should be used in either of those places.) + + + Some unit names reflect paths existing in the file system + namespace. Example: a device unit + dev-sda.device refers to a device with the + device node /dev/sda 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 + systemd-escape1 + command. + + 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 @ character, systemd will look for a + unit template that shares the same name but with the + instance string (i.e. the part between the @ character + and the suffix) removed. Example: if a service + getty@tty3.service is requested + and no file by that name is found, systemd will look + for getty@.service and + instantiate a service from that configuration file if + it is found. + + To refer to the instance string from within the + configuration file you may use the special %i + specifier in many of the configuration options. See below for + details. + + If a unit file is empty (i.e. has the file size 0) or is + symlinked to /dev/null, its configuration + will not be loaded and it appears with a load state of + masked, and cannot be activated. Use this as an + effective way to fully disable a unit, making it impossible to + start it even manually. + + The unit file format is covered by the + Interface + Stability Promise. + + + + + Automatic Dependencies + + 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. + + A number of unit dependencies are automatically established, + depending on unit configuration. On top of that, for units with + DefaultDependencies=yes (the default) a couple + of additional dependencies are added. The precise effect of + DefaultDependencies=yes depends on the unit + type (see below). + + If DefaultDependencies=yes is set, units + that are referenced by other units of type + .target via a Wants= or + Requires= dependency might automatically gain + an Before= dependency too. See + systemd.target5 + for details. + + + + Unit File Load Path + + 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. + + When the variable $SYSTEMD_UNIT_PATH is set, + the contents of this variable overrides the unit load path. If + $SYSTEMD_UNIT_PATH ends with an empty component + (:), the usual unit load path will be appended + to the contents of the variable. + + + + Load path when running in system mode (<option>--system</option>). + + + + + + + + Path + Description + + + + + /etc/systemd/system + Local configuration + + + /run/systemd/system + Runtime units + + + /usr/lib/systemd/system + Units of installed packages + + + +
+ + + + Load path when running in user mode (<option>--user</option>). + + + + + + + + Path + Description + + + + + $XDG_CONFIG_HOME/systemd/user + User configuration (only used when $XDG_CONFIG_HOME is set) + + + $HOME/.config/systemd/user + User configuration (only used when $XDG_CONFIG_HOME is not set) + + + /etc/systemd/user + Local configuration + + + $XDG_RUNTIME_DIR/systemd/user + Runtime units (only used when $XDG_RUNTIME_DIR is set) + + + /run/systemd/user + Runtime units + + + $XDG_DATA_HOME/systemd/user + Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set) + + + $HOME/.local/share/systemd/user + Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set) + + + /usr/lib/systemd/user + Units of packages that have been installed system-wide + + + +
+ + Additional units might be loaded into systemd ("linked") + from directories not on the unit load path. See the + link command for + systemctl1. + Also, some units are dynamically created via a + systemd.generator7. + + + + + [Unit] Section Options + + The unit file may include a [Unit] section, which carries + generic information about the unit that is not dependent on the + type of unit: + + + + + Description= + 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. Apache2 + Web Server is a good example. Bad examples are + high-performance light-weight HTTP server + (too generic) or Apache2 (too specific and + meaningless for people who do not know + Apache). + + + + Documentation= + A space-separated list of URIs referencing + documentation for this unit or its configuration. Accepted are + only URIs of the types http://, + https://, file:, + info:, man:. For more + information about the syntax of these URIs, see uri7. + 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. + + + + Requires= + + 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 + After= or Before= + options. If a unit foo.service requires a + unit bar.service as configured with + Requires= and no ordering is configured + with After= or Before=, + then both units will be started simultaneously and without any + delay between them if foo.service is + activated. Often, it is a better choice to use + Wants= instead of + Requires= in order to achieve a system that + is more robust when dealing with failing services. + + Note that dependencies of this type may also be + configured outside of the unit configuration file by adding a + symlink to a .requires/ directory + accompanying the unit file. For details, see + above. + + + + Requisite= + + Similar to Requires=. + However, if the units listed here are not started already, + they will not be started and the transaction will fail + immediately. + + + + Wants= + + A weaker version of + Requires=. 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. + + Note that dependencies of this type may also be + configured outside of the unit configuration file by adding + symlinks to a .wants/ directory + accompanying the unit file. For details, see + above. + + + + BindsTo= + + Configures requirement dependencies, very + similar in style to Requires=, 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. + + + + PartOf= + + Configures dependencies similar to + Requires=, 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. + + + + Conflicts= + + A space-separated list of unit names. + Configures negative requirement dependencies. If a unit has a + Conflicts= 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 + After= and Before= + ordering dependencies. + + 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. + + + + Before= + After= + + A space-separated list of unit names. + Configures ordering dependencies between units. If a unit + foo.service contains a setting + and both units are being + started, bar.service's start-up is + delayed until foo.service is started up. + Note that this setting is independent of and orthogonal to the + requirement dependencies as configured by + Requires=. It is a common pattern to + include a unit name in both the After= and + Requires= 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. After= is the inverse of + Before=, i.e. while + After= ensures that the configured unit is + started after the listed unit finished starting up, + Before= 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 + After= 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 After= or + Before=. 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. + + + + + OnFailure= + + A space-separated list of one or more units + that are activated when this unit enters the + failed state. + + + + PropagatesReloadTo= + ReloadPropagatedFrom= + + 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. + + + + JoinsNamespaceOf= + + 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 + PrivateNetwork= and + PrivateTmp= directives (see + systemd.exec5 + for details). If a unit that has this setting set is started, + its processes will see the same /tmp, + /var/tmp 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 + PrivateNetwork= and/or + PrivateTmp= is enabled for both the unit + that joins the namespace and the unit whose namespace is + joined. + + + + RequiresMountsFor= + + Takes a space-separated list of absolute + paths. Automatically adds dependencies of type + Requires= and After= for + all mount units required to access the specified path. + + Mount points marked with 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 + (Requires= and After= or + some other combination). + + + + OnFailureJobMode= + + Takes a value of + fail, + replace, + replace-irreversibly, + isolate, + flush, + ignore-dependencies or + ignore-requirements. Defaults to + replace. Specifies how the units listed in + OnFailure= will be enqueued. See + systemctl1's + option for details on the + possible values. If this is set to isolate, + only a single unit may be listed in + OnFailure=.. + + + + IgnoreOnIsolate= + + Takes a boolean argument. If + , this unit will not be stopped when + isolating another unit. Defaults to + . + + + + StopWhenUnneeded= + + Takes a boolean argument. If + , 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 . + + + + RefuseManualStart= + RefuseManualStop= + + Takes a boolean argument. If + , 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 + . + + + + AllowIsolate= + + Takes a boolean argument. If + , this unit may be used with the + systemctl isolate 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 + . + + + + DefaultDependencies= + + Takes a boolean argument. If + , (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 . It is highly recommended to + leave this option enabled for the majority of common units. If + set to , this option does not disable + all implicit dependencies, just non-essential + ones. + + + + JobTimeoutSec= + JobTimeoutAction= + JobTimeoutRebootArgument= + + 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 + failed mode. This value defaults to infinity (job timeouts disabled), + except for device units. NB: this timeout is independent from any unit-specific timeout (for example, the + timeout set with TimeoutStartSec= 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. + + JobTimeoutAction= + optionally configures an additional + action to take when the time-out is + hit. It takes the same values as the + per-service + StartLimitAction= + setting, see + systemd.service5 + for details. Defaults to + . JobTimeoutRebootArgument= + configures an optional reboot string + to pass to the + reboot2 + system call. + + + + StartLimitIntervalSec= + StartLimitBurst= + + 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 StartLimitIntervalSec= to configure the + checking interval (defaults to DefaultStartLimitIntervalSec= in manager configuration file, + set to 0 to disable any kind of rate limiting). Use StartLimitBurst= to configure how many + starts per interval are allowed (defaults to DefaultStartLimitBurst= in manager + configuration file). These configuration options are particularly useful in conjunction with the service + setting Restart= (see + systemd.service5); however, + they apply to all kinds of starts (including manual), not just those triggered by the + Restart= logic. Note that units which are configured for Restart= 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 + systemctl reset-failed 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. + + + + StartLimitAction= + + Configure the action to take if the rate limit configured with + StartLimitIntervalSec= and StartLimitBurst= is hit. Takes one of + , , , + , , or + . If is set, hitting the rate limit will trigger no + action besides that the start will not be permitted. causes a reboot following the + normal shutdown procedure (i.e. equivalent to systemctl reboot). + causes a forced reboot which will terminate all processes forcibly but should + cause no dirty file systems on reboot (i.e. equivalent to systemctl reboot -f) and + causes immediate execution of the + reboot2 system call, which + might result in data loss. Similarly, , , + have the effect of powering down the system with similar + semantics. Defaults to . + + + + RebootArgument= + Configure the optional argument for the + reboot2 system call if + StartLimitAction= or a service's FailureAction= is a reboot action. This + works just like the optional argument to systemctl reboot command. + + + + ConditionArchitecture= + ConditionVirtualization= + ConditionHost= + ConditionKernelCommandLine= + ConditionSecurity= + ConditionCapability= + ConditionACPower= + ConditionNeedsUpdate= + ConditionFirstBoot= + ConditionPathExists= + ConditionPathExistsGlob= + ConditionPathIsDirectory= + ConditionPathIsSymbolicLink= + ConditionPathIsMountPoint= + ConditionPathIsReadWrite= + ConditionDirectoryNotEmpty= + ConditionFileNotEmpty= + ConditionFileIsExecutable= + + + + 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 AssertArchitecture=, + AssertVirtualization=, … options for a similar mechanism that puts the unit in a failure + state and logs about the failed check (see below). + + ConditionArchitecture= may be used to + check whether the system is running on a specific + architecture. Takes one of + x86, + x86-64, + ppc, + ppc-le, + ppc64, + ppc64-le, + ia64, + parisc, + parisc64, + s390, + s390x, + sparc, + sparc64, + mips, + mips-le, + mips64, + mips64-le, + alpha, + arm, + arm-be, + arm64, + arm64-be, + sh, + sh64, + m86k, + tilegx, + cris to test + against a specific architecture. The architecture is + determined from the information returned by + uname2 + and is thus subject to + personality2. + Note that a Personality= setting in the + same unit file has no effect on this condition. A special + architecture name native is mapped to the + architecture the system manager itself is compiled for. The + test may be negated by prepending an exclamation mark. + + ConditionVirtualization= 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 + vm and + container to test against a generic type of + virtualization solution, or one of + qemu, + kvm, + zvm, + vmware, + microsoft, + oracle, + xen, + bochs, + uml, + openvz, + lxc, + lxc-libvirt, + systemd-nspawn, + docker, + rkt to test + against a specific implementation. See + systemd-detect-virt1 + 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. + + ConditionHost= 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 + gethostname2, + or a machine ID formatted as string (see + machine-id5). + The test may be negated by prepending an exclamation + mark. + + ConditionKernelCommandLine= 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 =). 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. + + ConditionSecurity= may be used to + check whether the given security module is enabled on the + system. Currently, the recognized values are + selinux, + apparmor, + ima, + smack and + audit. The test may be negated by + prepending an exclamation mark. + + ConditionCapability= 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 + capabilities7 + for details). Pass a capability name such as + CAP_MKNOD, possibly prefixed with an + exclamation mark to negate the check. + + ConditionACPower= 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 true, + 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 + false, the condition will hold only if + there is at least one AC connector known and all AC connectors + are disconnected from a power source. + + ConditionNeedsUpdate= takes one of + /var or /etc as + argument, possibly prefixed with a ! (for + inverting the condition). This condition may be used to + conditionalize units on whether the specified directory + requires an update because /usr's + modification time is newer than the stamp file + .updated in the specified directory. This + is useful to implement offline updates of the vendor operating + system resources in /usr that require + updating of /etc or + /var on the next following boot. Units + making use of this condition should order themselves before + systemd-update-done.service8, + to make sure they run before the stamp file's modification + time gets reset indicating a completed update. + + ConditionFirstBoot= takes a boolean + argument. This condition may be used to conditionalize units + on whether the system is booting up with an unpopulated + /etc directory. This may be used to + populate /etc on the first boot after + factory reset, or when a new system instances boots up for the + first time. + + With ConditionPathExists= 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 + ConditionPathExists= is prefixed with an + exclamation mark (!), the test is negated, + and the unit is only started if the path does not + exist. + + ConditionPathExistsGlob= is similar + to ConditionPathExists=, but checks for the + existence of at least one file or directory matching the + specified globbing pattern. + + ConditionPathIsDirectory= is similar + to ConditionPathExists= but verifies + whether a certain path exists and is a directory. + + ConditionPathIsSymbolicLink= is + similar to ConditionPathExists= but + verifies whether a certain path exists and is a symbolic + link. + + ConditionPathIsMountPoint= is similar + to ConditionPathExists= but verifies + whether a certain path exists and is a mount point. + + ConditionPathIsReadWrite= is similar + to ConditionPathExists= but verifies + whether the underlying file system is readable and writable + (i.e. not mounted read-only). + + ConditionDirectoryNotEmpty= is + similar to ConditionPathExists= but + verifies whether a certain path exists and is a non-empty + directory. + + ConditionFileNotEmpty= is similar to + ConditionPathExists= but verifies whether a + certain path exists and refers to a regular file with a + non-zero size. + + ConditionFileIsExecutable= is similar + to ConditionPathExists= but verifies + whether a certain path exists, is a regular file and marked + executable. + + 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 + ConditionPathIsSymbolicLink=, 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. + + + + AssertArchitecture= + AssertVirtualization= + AssertHost= + AssertKernelCommandLine= + AssertSecurity= + AssertCapability= + AssertACPower= + AssertNeedsUpdate= + AssertFirstBoot= + AssertPathExists= + AssertPathExistsGlob= + AssertPathIsDirectory= + AssertPathIsSymbolicLink= + AssertPathIsMountPoint= + AssertPathIsReadWrite= + AssertDirectoryNotEmpty= + AssertFileNotEmpty= + AssertFileIsExecutable= + + Similar to the ConditionArchitecture=, + ConditionVirtualization=, …, 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. + + + + SourcePath= + 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. + + + + + + + + [Install] Section Options + + Unit files may include an [Install] section, which carries installation information for + the unit. This section is not interpreted by + systemd1 during runtime; it is + used by the enable and disable commands of the + systemctl1 tool during + installation of a unit. Note that settings in the [Install] section may not appear in + .d/*.conf unit file drop-ins (see above). + + + + Alias= + + 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, systemctl enable 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. + + + + WantedBy= + RequiredBy= + + 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 .wants/ or + .requires/ directory of each of the + listed units when this unit is installed by systemctl + enable. This has the effect that a dependency of + type Wants= or Requires= + 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 + Wants= and Requires= in + the [Unit] section for details. + + WantedBy=foo.service in a service + bar.service is mostly equivalent to + Alias=foo.service.wants/bar.service in the + same file. In case of template units, systemctl + enable must be called with an instance name, and + this instance will be added to the + .wants/ or + .requires/ list of the listed unit. E.g. + WantedBy=getty.target in a service + getty@.service will result in + systemctl enable getty@tty2.service + creating a + getty.target.wants/getty@tty2.service + link to getty@.service. + + + + + Also= + + Additional units to install/deinstall when + this unit is installed/deinstalled. If the user requests + installation/deinstallation of a unit with this option + configured, systemctl enable and + systemctl disable will automatically + install/uninstall units listed in this option as well. + + This option may be used more than once, or a + space-separated list of unit names may be + given. + + + + DefaultInstance= + + 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. + + + + 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. + + + + + Specifiers + + 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: + + + Specifiers available in unit files + + + + + + + Specifier + Meaning + Details + + + + + %n + Full unit name + + + + %N + Unescaped full unit name + Same as %n, but with escaping undone + + + %p + Prefix name + For instantiated units, this refers to the string before the @ character of the unit name. For non-instantiated units, this refers to the name of the unit with the type suffix removed. + + + %P + Unescaped prefix name + Same as %p, but with escaping undone + + + %i + Instance name + For instantiated units: this is the string between the @ character and the suffix of the unit name. + + + %I + Unescaped instance name + Same as %i, but with escaping undone + + + %f + Unescaped filename + This is either the unescaped instance name (if applicable) with / prepended (if applicable), or the prefix name prepended with /. + + + %c + Control group path of the unit + This path does not include the /sys/fs/cgroup/systemd/ prefix. + + + %r + Control group path of the slice the unit is placed in + This usually maps to the parent cgroup path of %c. + + + %R + Root control group path below which slices and units are placed + For system instances, this resolves to /, except in containers, where this maps to the container's root control group path. + + + %t + Runtime directory + This is either /run (for the system manager) or the path $XDG_RUNTIME_DIR resolves to (for user managers). + + + %u + User name + This is the name of the user running the service manager instance. In case of the system manager this resolves to root. + + + %U + User UID + This is the numeric UID of the user running the service manager instance. In case of the system manager this resolves to 0. + + + %h + User home directory + This is the home directory of the user running the service manager instance. In case of the system manager this resolves to /root. + + + %s + User shell + This is the shell of the user running the service manager instance. In case of the system manager this resolves to /bin/sh. + + + %m + Machine ID + The machine ID of the running system, formatted as string. See machine-id5 for more information. + + + %b + Boot ID + The boot ID of the running system, formatted as string. See random4 for more information. + + + %H + Host name + The hostname of the running system at the point in time the unit configuration is loaded. + + + %v + Kernel release + Identical to uname -r output + + + %% + Single percent sign + Use %% in place of % to specify a single percent sign. + + + +
+ + Please note that specifiers %U, + %h, %s 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 mode. + + + + Examples + + + Allowing units to be enabled + + The following snippet (highlighted) allows a unit (e.g. + foo.service) to be enabled via + systemctl enable: + + [Unit] +Description=Foo + +[Service] +ExecStart=/usr/sbin/foo-daemon + +[Install] +WantedBy=multi-user.target + + After running systemctl enable, a + symlink + /etc/systemd/system/multi-user.target.wants/foo.service + linking to the actual unit will be created. It tells systemd to + pull in the unit when starting + multi-user.target. The inverse + systemctl disable will remove that symlink + again. + + + + Overriding vendor settings + + There are two methods of overriding vendor settings in + unit files: copying the unit file from + /usr/lib/systemd/system to + /etc/systemd/system and modifying the + chosen settings. Alternatively, one can create a directory named + unit.d/ within + /etc/systemd/system and place a drop-in + file name.conf + there that only changes the specific settings one is interested + in. Note that multiple such drop-in files are read if + present. + + 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. + + 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. + + 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 ConditionPathExists= (or + e.g. ExecStart= 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. + + 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. + + Suppose there is a vendor-supplied unit + /usr/lib/systemd/system/httpd.service with + the following contents: + + [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 + + Now one wants to change some settings as an administrator: + firstly, in the local setup, /srv/webserver + might not exist, because the HTTP server is configured to use + /srv/www instead. Secondly, the local + configuration makes the HTTP server also depend on a memory + cache service, memcached.service, that + should be pulled in (Requires=) and also be + ordered appropriately (After=). Thirdly, in + order to harden the service a bit more, the administrator would + like to set the PrivateTmp= setting (see + systemd.service5 + for details). And lastly, the administrator would like to reset + the niceness of the service to its default value of 0. + + The first possibility is to copy the unit file to + /etc/systemd/system/httpd.service and + change the chosen settings: + + [Unit] +Description=Some HTTP server +After=remote-fs.target sqldb.service memcached.service +Requires=sqldb.service memcached.service +AssertPathExists=/srv/www + +[Service] +Type=notify +ExecStart=/usr/sbin/some-fancy-httpd-server +Nice=0 +PrivateTmp=yes + +[Install] +WantedBy=multi-user.target + + Alternatively, the administrator could create a drop-in + file + /etc/systemd/system/httpd.service.d/local.conf + with the following contents: + + [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 + + Note that dependencies (After=, 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. + + + + + + See Also + + systemd1, + systemctl1, + systemd.special7, + systemd.service5, + systemd.socket5, + systemd.device5, + systemd.mount5, + systemd.automount5, + systemd.swap5, + systemd.target5, + systemd.path5, + systemd.timer5, + systemd.scope5, + systemd.slice5, + systemd.time7, + systemd-analyze1, + capabilities7, + systemd.directives7, + uname1 + + + + diff --git a/src/grp-system/systemd/systemd.xml b/src/grp-system/systemd/systemd.xml new file mode 100644 index 0000000000..e05a9d6e29 --- /dev/null +++ b/src/grp-system/systemd/systemd.xml @@ -0,0 +1,1153 @@ + + + + + + + + + systemd + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd + 1 + + + + systemd + init + systemd system and service manager + + + + + systemd OPTIONS + + + init OPTIONS COMMAND + + + + + Description + + 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. + + For compatibility with SysV, if systemd is called as + init and a PID that is not 1, it will execute + telinit and pass all command line arguments + unmodified. That means init and + telinit are mostly equivalent when invoked from + normal login sessions. See + telinit8 + for more information. + + When run as a system instance, systemd interprets the + configuration file system.conf and the files + in system.conf.d directories; when run as a + user instance, systemd interprets the configuration file + user.conf and the files in + user.conf.d directories. See + systemd-system.conf5 + for more information. + + + + Options + + The following options are understood: + + + + + + Determine startup sequence, dump it and exit. + This is an option useful for debugging only. + + + + + Dump understood unit configuration items. This + outputs a terse but complete list of configuration items + understood in unit definition files. + + + + + Set default unit to activate on startup. If + not specified, defaults to + default.target. + + + + + + For , tell systemd to + run a system instance, even if the process ID is not 1, i.e. + systemd is not run as init process. + 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 + mode, but PID not 1. In practice, + passing explicitly is only useful in + conjunction with . + + + + + 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 + systemd.dump_core= option, see + below. + + + + VT + + 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 yes, the VT kernel messages + are written to is selected. If no, 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 + systemd.crash_vt= option, see + below. + + + + + + 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 + systemd.crash_shell= option, see + below. + + + + + + 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 systemd.crash_reboot= option, + see below. + + + + + + Ask for confirmation when spawning processes. + This switch has no effect when run as user + instance. + + + + + 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 . + + + + + Set log target. Argument must be one of + , + , + , + , + . + + + + + Set log level. As + argument this accepts a numerical log + level or the well-known syslog3 + symbolic names (lowercase): + , + , + , + , + , + , + , + . + + + + + Highlight important log messages. Argument is + a boolean value. If the argument is omitted, it defaults to + . + + + + + 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 + . + + + + + + Sets the default output or error output for + all services and sockets, respectively. That is, controls the + default for and + (see + systemd.exec5 + for details). Takes one of + , + , + , + , + , + , + , + , + . If the + argument is omitted + defaults to + and + to + . + + + + + + Override the machine-id set on the hard drive, + useful for network booting or for containers. May not be set + to all zeros. + + + + + + + + + Concepts + + systemd provides a dependency system between various + entities called "units" of 12 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 + systemd.unit5, + 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. + + The following unit types are available: + + + Service units, which start and control daemons + and the processes they consist of. For details, see + systemd.service5. + + Socket units, which encapsulate local IPC or + network sockets in the system, useful for socket-based + activation. For details about socket units, see + systemd.socket5, + for details on socket-based activation and other forms of + activation, see + daemon7. + + Target units are useful to group units, or + provide well-known synchronization points during boot-up, see + systemd.target5. + + Device units expose kernel devices in systemd + and may be used to implement device-based activation. For + details, see + systemd.device5. + + Mount units control mount points in the file + system, for details see + systemd.mount5. + + Automount units provide automount capabilities, + for on-demand mounting of file systems as well as parallelized + boot-up. See + systemd.automount5. + + Timer units are useful for triggering activation + of other units based on timers. You may find details in + systemd.timer5. + + Swap units are very similar to mount units and + encapsulate memory swap partitions or files of the operating + system. They are described in + systemd.swap5. + + Path units may be used to activate other + services when file system objects change or are modified. See + systemd.path5. + + 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 + systemd.slice5. + + Scope units are similar to service units, but + manage foreign processes instead of starting them as well. See + systemd.scope5. + + + + Units are named as their configuration files. Some units + have special semantics. A detailed list is available in + systemd.special7. + + systemd knows various kinds of dependencies, including + positive and negative requirement dependencies (i.e. + Requires= and Conflicts=) as + well as ordering dependencies (After= and + Before=). NB: ordering and requirement + dependencies are orthogonal. If only a requirement dependency + exists between two units (e.g. foo.service + requires bar.service), but no ordering + dependency (e.g. foo.service after + bar.service) 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. + + 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. + + On boot systemd activates the target unit + default.target 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 graphical.target (for fully-featured + boots into the UI) or multi-user.target (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 + systemd.special7 + for details about these target units. + + Processes systemd spawns are placed in individual Linux + control groups named after the unit which they belong to in the + private systemd hierarchy. (see cgroups.txt + 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 + /sys/fs/cgroup/systemd/), or in tools such as + systemd-cgls1 + or + ps1 + (ps xawf -eo pid,user,cgroup,args is + particularly useful to list all processes and the systemd units + they belong to.). + + 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 + /dev/initctl interface is provided, and + compatibility implementations of the various SysV client tools are + available. In addition to that, various established Unix + functionality such as /etc/fstab or the + utmp database are supported. + + 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. + + 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 + /sys or /proc. + + For more information about the concepts and + ideas behind systemd, please refer to the + Original Design Document. + + Note that some but not all interfaces provided + by systemd are covered by the + Interface + Stability Promise. + + 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 + systemd.generator7. + + Systems which invoke systemd in a container or initrd + environment should implement the + Container Interface or + initrd Interface + specifications, respectively. + + + + Directories + + + + System unit directories + + 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 pkg-config systemd + --variable=systemdsystemunitdir. Other directories + checked are /usr/local/lib/systemd/system + and /usr/lib/systemd/system. User + configuration always takes precedence. pkg-config + systemd --variable=systemdsystemconfdir returns the + path of the system configuration directory. Packages should + alter the content of these directories only with the + enable and disable + commands of the + systemctl1 + tool. Full list of directories is provided in + systemd.unit5. + + + + + + + User unit directories + + Similar rules apply for the user unit + directories. However, here the + XDG + Base Directory specification is followed to find + units. Applications should place their unit files in the + directory returned by pkg-config systemd + --variable=systemduserunitdir. Global configuration + is done in the directory reported by pkg-config + systemd --variable=systemduserconfdir. The + enable and disable + commands of the + systemctl1 + 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 + systemd.unit5. + + + + + + + SysV init scripts directory + + 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 + .service suffix + removed). + + + + + + SysV runlevel link farm directory + + 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. + + + + + + Signals + + + + SIGTERM + + Upon receiving this signal the systemd system + manager serializes its state, reexecutes itself and + deserializes the saved state again. This is mostly equivalent + to systemctl daemon-reexec. + + systemd user managers will start the + exit.target unit when this signal is + received. This is mostly equivalent to systemctl + --user start exit.target. + + + + SIGINT + + Upon receiving this signal the systemd system + manager will start the + ctrl-alt-del.target unit. This is mostly + equivalent to systemctl start + ctl-alt-del.target. 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. + + systemd user managers treat this signal the same way as + SIGTERM. + + + + SIGWINCH + + When this signal is received the systemd + system manager will start the + kbrequest.target unit. This is mostly + equivalent to systemctl start + kbrequest.target. + + This signal is ignored by systemd user + managers. + + + + SIGPWR + + When this signal is received the systemd + manager will start the sigpwr.target + unit. This is mostly equivalent to systemctl start + sigpwr.target. + + + + SIGUSR1 + + When this signal is received the systemd + manager will try to reconnect to the D-Bus + bus. + + + + SIGUSR2 + + 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 + systemd-analyze dump. + + + + SIGHUP + + Reloads the complete daemon configuration. + This is mostly equivalent to systemctl + daemon-reload. + + + + SIGRTMIN+0 + + Enters default mode, starts the + default.target unit. This is mostly + equivalent to systemctl start + default.target. + + + + SIGRTMIN+1 + + Enters rescue mode, starts the + rescue.target unit. This is mostly + equivalent to systemctl isolate + rescue.target. + + + + SIGRTMIN+2 + + Enters emergency mode, starts the + emergency.service unit. This is mostly + equivalent to systemctl isolate + emergency.service. + + + + SIGRTMIN+3 + + Halts the machine, starts the + halt.target unit. This is mostly + equivalent to systemctl start + halt.target. + + + + SIGRTMIN+4 + + Powers off the machine, starts the + poweroff.target unit. This is mostly + equivalent to systemctl start + poweroff.target. + + + + SIGRTMIN+5 + + Reboots the machine, starts the + reboot.target unit. This is mostly + equivalent to systemctl start + reboot.target. + + + + SIGRTMIN+6 + + Reboots the machine via kexec, starts the + kexec.target unit. This is mostly + equivalent to systemctl start + kexec.target. + + + + SIGRTMIN+13 + + Immediately halts the machine. + + + + SIGRTMIN+14 + + Immediately powers off the machine. + + + + SIGRTMIN+15 + + Immediately reboots the machine. + + + + SIGRTMIN+16 + + Immediately reboots the machine with kexec. + + + + SIGRTMIN+20 + + Enables display of status messages on the + console, as controlled via + systemd.show_status=1 on the kernel command + line. + + + + SIGRTMIN+21 + + Disables display of + status messages on the console, as + controlled via + systemd.show_status=0 + on the kernel command + line. + + + + SIGRTMIN+22 + SIGRTMIN+23 + + Sets the log level to debug + (or info on + SIGRTMIN+23), as controlled via + systemd.log_level=debug (or + systemd.log_level=info on + SIGRTMIN+23) on the kernel command + line. + + + + SIGRTMIN+24 + + Immediately exits the manager (only available + for --user instances). + + + + SIGRTMIN+26 + SIGRTMIN+27 + SIGRTMIN+28 + + Sets the log level to + journal-or-kmsg (or + console on + SIGRTMIN+27, kmsg on + SIGRTMIN+28), as controlled via + systemd.log_target=journal-or-kmsg (or + systemd.log_target=console on + SIGRTMIN+27 or + systemd.log_target=kmsg on + SIGRTMIN+28) on the kernel command + line. + + + + + + Environment + + + + $SYSTEMD_LOG_LEVEL + systemd reads the log level from this + environment variable. This can be overridden with + . + + + + $SYSTEMD_LOG_TARGET + systemd reads the log target from this + environment variable. This can be overridden with + . + + + + $SYSTEMD_LOG_COLOR + Controls whether systemd highlights important + log messages. This can be overridden with + . + + + + $SYSTEMD_LOG_LOCATION + Controls whether systemd prints the code + location along with log messages. This can be overridden with + . + + + + $XDG_CONFIG_HOME + $XDG_CONFIG_DIRS + $XDG_DATA_HOME + $XDG_DATA_DIRS + + The systemd user manager uses these variables + in accordance to the XDG + Base Directory specification to find its + configuration. + + + + $SYSTEMD_UNIT_PATH + + Controls where systemd looks for unit + files. + + + + $SYSTEMD_SYSVINIT_PATH + + Controls where systemd looks for SysV init + scripts. + + + + $SYSTEMD_SYSVRCND_PATH + + Controls where systemd looks for SysV init + script runlevel link farms. + + + + $SYSTEMD_COLORS + + Controls whether colorized output should be generated. + + + + + $LISTEN_PID + $LISTEN_FDS + $LISTEN_FDNAMES + + Set by systemd for supervised processes during + socket-based activation. See + sd_listen_fds3 + for more information. + + + + $NOTIFY_SOCKET + + Set by systemd for supervised processes for + status and start-up completion notification. See + sd_notify3 + for more information. + + + + + + Kernel Command Line + + When run as system instance systemd parses a number of + kernel command line argumentsIf 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 /proc/cmdline + instead.: + + + + systemd.unit= + rd.systemd.unit= + + Overrides the unit to activate on boot. + Defaults to default.target. This may be + used to temporarily boot into a different boot unit, for + example rescue.target or + emergency.service. See + systemd.special7 + for details about these units. The option prefixed with + rd. is honored only in the initial RAM disk + (initrd), while the one that is not prefixed only in the main + system. + + + + systemd.dump_core= + + Takes a boolean argument. If + , the systemd manager (PID 1) dumps core + when it crashes. Otherwise, no core dump is created. Defaults + to . + + + + systemd.crash_chvt= + + 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 + no, meaning that no such switch is + attempted. If set to yes, the VT the + kernel messages are written to is selected. + + + + systemd.crash_shell= + + Takes a boolean argument. If + , the system manager (PID 1) spawns a + shell when it crashes, after a 10s delay. Otherwise, no shell + is spawned. Defaults to , for security + reasons, as the shell is not protected by password + authentication. + + + + systemd.crash_reboot= + + Takes a boolean argument. If + , 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 + , in order to avoid a reboot loop. If + combined with systemd.crash_shell=, the + system is rebooted after the shell exits. + + + + systemd.confirm_spawn= + + Takes a boolean argument. If + , the system manager (PID 1) asks for + confirmation when spawning processes. Defaults to + . + + + + systemd.show_status= + + Takes a boolean argument or the constant + auto. If , the + systemd manager (PID 1) shows terse service status updates on + the console during bootup. auto behaves + like until a service fails or there is + a significant delay in boot. Defaults to + , unless is passed + as kernel command line option, in which case it defaults to + auto. + + + + systemd.log_target= + systemd.log_level= + systemd.log_color= + systemd.log_location= + + Controls log output, with the same effect as + the $SYSTEMD_LOG_TARGET, + $SYSTEMD_LOG_LEVEL, + $SYSTEMD_LOG_COLOR, + $SYSTEMD_LOG_LOCATION environment variables + described above. + + + + systemd.default_standard_output= + systemd.default_standard_error= + Controls default standard output and error + output for services, with the same effect as the + and + command line + arguments described above, respectively. + + + + systemd.setenv= + + 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. + + + + systemd.machine_id= + + 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. + + + + quiet + + Turn off status output at boot, much like + systemd.show_status=false 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. + + + + + debug + + Turn on debugging output. This is equivalent + to systemd.log_level=debug. 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. + + + + emergency + -b + + Boot into emergency mode. This is equivalent + to systemd.unit=emergency.target and + provided for compatibility reasons and to be easier to + type. + + + + rescue + single + s + S + 1 + + Boot into rescue mode. This is equivalent to + systemd.unit=rescue.target and provided for + compatibility reasons and to be easier to + type. + + + + 2 + 3 + 4 + 5 + + Boot into the specified legacy SysV runlevel. + These are equivalent to + systemd.unit=runlevel2.target, + systemd.unit=runlevel3.target, + systemd.unit=runlevel4.target, and + systemd.unit=runlevel5.target, + respectively, and provided for compatibility reasons and to be + easier to type. + + + + locale.LANG= + locale.LANGUAGE= + locale.LC_CTYPE= + locale.LC_NUMERIC= + locale.LC_TIME= + locale.LC_COLLATE= + locale.LC_MONETARY= + locale.LC_MESSAGES= + locale.LC_PAPER= + locale.LC_NAME= + locale.LC_ADDRESS= + locale.LC_TELEPHONE= + locale.LC_MEASUREMENT= + locale.LC_IDENTIFICATION= + + Set the system locale to use. This overrides + the settings in /etc/locale.conf. For + more information, see + locale.conf5 + and + locale7. + + + + + For other kernel command line parameters understood by + components of the core OS, please refer to + kernel-command-line7. + + + + Sockets and FIFOs + + + + /run/systemd/notify + + Daemon status notification socket. This is an + AF_UNIX datagram socket and is used to + implement the daemon notification logic as implemented by + sd_notify3. + + + + + /run/systemd/private + + Used internally as communication channel + between + systemctl1 + and the systemd process. This is an + AF_UNIX stream socket. This interface is + private to systemd and should not be used in external + projects. + + + + /dev/initctl + + Limited compatibility support for the SysV + client interface, as implemented by the + systemd-initctl.service unit. This is a + named pipe in the file system. This interface is obsolete and + should not be used in new applications. + + + + + + See Also + + The systemd Homepage, + systemd-system.conf5, + locale.conf5, + systemctl1, + journalctl1, + systemd-notify1, + daemon7, + sd-daemon3, + systemd.unit5, + systemd.special5, + pkg-config1, + kernel-command-line7, + bootup7, + systemd.directives7 + + + + diff --git a/src/grp-timedate/systemd-timedated/systemd-timedated.service.xml b/src/grp-timedate/systemd-timedated/systemd-timedated.service.xml new file mode 100644 index 0000000000..e44163aefb --- /dev/null +++ b/src/grp-timedate/systemd-timedated/systemd-timedated.service.xml @@ -0,0 +1,85 @@ + + + + + + + + + systemd-timedated.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-timedated.service + 8 + + + + systemd-timedated.service + systemd-timedated + Time and date bus mechanism + + + + systemd-timedated.service + /usr/lib/systemd/systemd-timedated + + + + Description + + systemd-timedated is a system service + that may be used as a mechanism to change the system clock and + timezone, as well as to enable/disable NTP time synchronization. + systemd-timedated is automatically activated + on request and terminates itself when it is unused. + + The tool + timedatectl1 + is a command line client to this service. + + See the + developer documentation for information about the APIs + systemd-timedated provides. + + + + See Also + + systemd1, + timedatectl1, + localtime5, + hwclock8 + + + + diff --git a/src/grp-timedate/timedatectl/timedatectl.xml b/src/grp-timedate/timedatectl/timedatectl.xml new file mode 100644 index 0000000000..415e2c799a --- /dev/null +++ b/src/grp-timedate/timedatectl/timedatectl.xml @@ -0,0 +1,253 @@ + + + + + + + + + timedatectl + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + timedatectl + 1 + + + + timedatectl + Control the system time and date + + + + + timedatectl OPTIONS COMMAND + + + + + Description + + timedatectl may be used to query and + change the system clock and its settings. + + Use + systemd-firstboot1 + to initialize the system time zone for mounted (but not booted) + system images. + + + + Options + + The following options are understood: + + + + + + Do not query the user for authentication for + privileged operations. + + + + + + If set-local-rtc is invoked + and this option is passed, the system clock is synchronized + from the RTC again, taking the new setting into account. + Otherwise, the RTC is synchronized from the system + clock. + + + + + + + + + + + The following commands are understood: + + + + status + + Show current settings of the system clock and + RTC, including whether network time synchronization is + on. Note that whether network time synchronization is on + simply reflects whether the + systemd-timesyncd.service unit is + enabled. Even if this command shows the status as off, a + different service might still synchronize the clock with the + network. + + + + set-time [TIME] + + Set the system clock to the specified time. + This will also update the RTC time accordingly. The time may + be specified in the format "2012-10-30 + 18:17:16". + + + + set-timezone [TIMEZONE] + + Set the system time zone to the specified + value. Available timezones can be listed with + list-timezones. If the RTC is configured to + be in the local time, this will also update the RTC time. This + call will alter the /etc/localtime + symlink. See + localtime5 + for more information. + + + + list-timezones + + List available time zones, one per line. + Entries from the list can be set as the system timezone with + set-timezone. + + + + set-local-rtc [BOOL] + + Takes a boolean argument. If + 0, the system is configured to maintain the + RTC in universal time. If 1, it will + maintain the RTC in local time instead. Note that maintaining + the RTC in the local timezone is not fully supported and will + create various problems with time zone changes and daylight + saving adjustments. If at all possible, keep the RTC in UTC + mode. Note that invoking this will also synchronize the RTC + from the system clock, unless + is passed (see above). + This command will change the 3rd line of + /etc/adjtime, as documented in + hwclock8. + + + + + set-ntp [BOOL] + + Takes a boolean argument. Controls whether + network time synchronization is active and enabled (if + available). This enables and starts, or disables and stops the + systemd-timesyncd.service unit. It does + not affect the state of any other, unrelated network time + synchronization services that might be installed on the + system. This command is hence mostly equivalent to: + systemctl enable --now + systemd-timesyncd.service and systemctl + disable --now systemd-timesyncd.service, but is + protected by a different access policy. + + Note that even if time synchronization is turned off + with this command, another unrelated system service might + still synchronize the clock with the network. Also note that, + strictly speaking, + systemd-timesyncd.service does more than + just network time synchronization, as it ensures a monotonic + clock on systems without RTC even if no network is + available. See + systemd-timesyncd.service8 + for details about this. + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure + code otherwise. + + + + + + Examples + Show current settings: + $ timedatectl + Local time: Di 2015-04-07 16:26:56 CEST + Universal time: Di 2015-04-07 14:26:56 UTC + RTC time: Di 2015-04-07 14:26:56 + Time zone: Europe/Berlin (CEST, +0200) + Network time on: yes +NTP synchronized: yes + RTC in local TZ: no + + + Enable network time synchronization: + $ timedatectl set-ntp true +==== AUTHENTICATING FOR org.freedesktop.timedate1.set-ntp === +Authentication is required to control whether network time synchronization shall be enabled. +Authenticating as: user +Password: ******** +==== AUTHENTICATION COMPLETE === + + $ systemctl status systemd-timesyncd.service +● systemd-timesyncd.service - Network Time Synchronization + Loaded: loaded (/usr/lib/systemd/system/systemd-timesyncd.service; enabled) + Active: active (running) since Mo 2015-03-30 14:20:38 CEST; 5s ago + Docs: man:systemd-timesyncd.service(8) + Main PID: 595 (systemd-timesyn) + Status: "Using Time Server 216.239.38.15:123 (time4.google.com)." + CGroup: /system.slice/systemd-timesyncd.service + └─595 /usr/lib/systemd/systemd-timesyncd +... + + + + + See Also + + systemd1, + hwclock8, + date1, + localtime5, + systemctl1, + systemd-timedated.service8, + systemd-timesyncd.service8, + systemd-firstboot1 + + + + diff --git a/src/grp-udev/hwdb/hwdb.xml b/src/grp-udev/hwdb/hwdb.xml new file mode 100644 index 0000000000..2b1e60fb22 --- /dev/null +++ b/src/grp-udev/hwdb/hwdb.xml @@ -0,0 +1,85 @@ + + + + + + hwdb + systemd + + + Developer + Kay + Sievers + kay@vrfy.org + + + Developer + Tom + Gundersen + teg@jklm.no + + + + + + hwdb + 7 + + + + hwdb + Hardware Database + + + Description + The hardware database is a key-value store for associating modalias-like keys to + udev-property-like values. It is used primarily by udev to add the relevant properties + to matching devices, but it can also be queried directly. + + + Hardware Database Files + The hwdb files are read from the files located in the + system hwdb directory /usr/lib/udev/hwdb.d and + the local administration directory /etc/udev/hwdb.d. + All hwdb 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 /etc + have the highest priority and take precedence over files with the same + name in /usr/lib. This can be used to override a + system-supplied hwdb file with a local file if needed; + a symlink in /etc with the same name as a hwdb file in + /usr/lib, pointing to /dev/null, + disables the hwdb file entirely. hwdb files must have the extension + .hwdb; other extensions are ignored. + + The hwdb file contains data records consisting of matches and + associated key-value pairs. Every record in the hwdb starts with one or + more match strings, specifying a shell glob to compare the database + lookup string against. Multiple match lines are specified in additional + consecutive lines. Every match line is compared individually, and they are + combined by OR. Every match line must start at the first character of + the line. + + The match lines are followed by one or more key-value pair lines, which + are recognized by a leading space character. The key name and value are separated + by =. An empty line signifies the end + of a record. Lines beginning with # are ignored. + + The content of all hwdb files is read by + systemd-hwdb8 + and compiled to a binary database located at /etc/udev/hwdb.bin, + or alternatively /usr/lib/udev/hwdb.bin if you want ship the compiled + database in an immutable image. + During runtime, only the binary database is used. + + + + See Also + + + systemd-hwdb8 + + + + diff --git a/src/grp-udev/systemd-hwdb/systemd-hwdb.xml b/src/grp-udev/systemd-hwdb/systemd-hwdb.xml new file mode 100644 index 0000000000..2b363c77f2 --- /dev/null +++ b/src/grp-udev/systemd-hwdb/systemd-hwdb.xml @@ -0,0 +1,93 @@ + + + + + + systemd-hwdb + systemd + + + Developer + Kay + Sievers + kay@vrfy.org + + + Developer + Tom + Gundersen + teg@jklm.no + + + + + + systemd-hwdb + 8 + + + + systemd-hwdbhardware database management tool + + + + + systemd-hwdb options update + + + systemd-hwdb options query modalias + + + + Description + systemd-hwdb expects a command and command + specific arguments. It manages the binary hardware database. + + + Options + + + + + + Print help text. + + + + + + Generate in /usr/lib/udev instead of /etc/udev. + + + + + + + Alternate root path in the filesystem. + + + + + systemd-hwdb + <arg choice="opt"><replaceable>options</replaceable></arg> + update + Update the binary database. + + + systemd-hwdb + <arg choice="opt"><replaceable>options</replaceable></arg> + query + <arg><replaceable>MODALIAS</replaceable></arg> + + Query database and print result. + + + + + See Also + + hwdb7 + + + diff --git a/src/grp-udev/systemd-udevd/systemd-udevd.service.xml b/src/grp-udev/systemd-udevd/systemd-udevd.service.xml new file mode 100644 index 0000000000..243fd06471 --- /dev/null +++ b/src/grp-udev/systemd-udevd/systemd-udevd.service.xml @@ -0,0 +1,188 @@ + + + + + + + systemd-udevd.service + systemd + + + Developer + Kay + Sievers + kay@vrfy.org + + + + + + systemd-udevd.service + 8 + + + + systemd-udevd.service + systemd-udevd-control.socket + systemd-udevd-kernel.socket + systemd-udevd + Device event managing daemon + + + + systemd-udevd.service + systemd-udevd-control.socket + systemd-udevd-kernel.socket + + + /usr/lib/systemd/systemd-udevd + + + + + + + + + + + + + Description + systemd-udevd listens to kernel uevents. + For every event, systemd-udevd executes matching instructions + specified in udev rules. See + udev7 + . + + The behavior of the daemon can be configured using + udev.conf5, + its command line options, environment variables, and on the kernel + command line, or changed dynamically with udevadm + control. + + + + Options + + + + + Detach and run in the background. + + + + + + + Print debug messages to standard error. + + + + + + + Limit the number of events executed in parallel. + + + + + + + Delay the execution of RUN + instructions by the given number of seconds. This option + might be useful when debugging system crashes during + coldplug caused by loading non-working kernel + modules. + + + + + + + Set the number of seconds to wait for events to finish. After + this time, the event will be terminated. The default is 180 seconds. + + + + + + + Specify when systemd-udevd should resolve names of users and groups. + When set to (the default), names will be + resolved when the rules are parsed. When set to + , names will be resolved for every event. + When set to , names will never be resolved + and all devices will be owned by root. + + + + + + + + + + + + + Kernel command line + + Parameters starting with "rd." will be read when + systemd-udevd is used in an initrd. + + udev.log-priority= + rd.udev.log-priority= + + Set the log level. + + + + udev.children-max= + rd.udev.children-max= + + Limit the number of events executed in parallel. + + + + udev.exec-delay= + rd.udev.exec-delay= + + Delay the execution of RUN instructions by the given + number of seconds. This option might be useful when + debugging system crashes during coldplug caused by loading + non-working kernel modules. + + + + udev.event-timeout= + rd.udev.event-timeout= + + Wait for events to finish up to the given number + of seconds. This option might be useful if events are + terminated due to kernel drivers taking too long to initialize. + + + + net.ifnames= + + Network interfaces are renamed to give them predictable names + when possible. It is enabled by default; specifying 0 disables it. + + + + + + + + See Also + + udev.conf5, + udev7, + udevadm8 + + + diff --git a/src/grp-udev/udev.conf.xml b/src/grp-udev/udev.conf.xml new file mode 100644 index 0000000000..e104e53f5d --- /dev/null +++ b/src/grp-udev/udev.conf.xml @@ -0,0 +1,94 @@ + + + + + + + + + udev.conf + systemd + + + Developer + Kay + Sievers + kay@vrfy.org + + + + + + udev.conf + 5 + + + + udev.conf + Configuration for device event managing daemon + + + + /etc/udev/udev.conf + + + + Description + + + systemd-udevd8 + expects its main configuration file at + /etc/udev/udev.conf. It consists of a set + of variables allowing the user to override default udev + values. All empty lines or lines beginning with '#' are + ignored. The following variables can be set: + + + + + udev_log + + + The log level. Valid values are the numerical + syslog priorities or their textual representations: + , and + . + + + + + + In addition, systemd-udevd can be configured + by command line options and the kernel command line (see + systemd-udevd8). + + + + + See Also + + systemd-udevd8, + udev7, + udevadm8 + + + diff --git a/src/grp-udev/udev.xml b/src/grp-udev/udev.xml new file mode 100644 index 0000000000..dd5563605c --- /dev/null +++ b/src/grp-udev/udev.xml @@ -0,0 +1,755 @@ + + + + + + udev + systemd + + + Developer + Greg + Kroah-Hartmann + greg@kroah.com + + + Developer + Kay + Sievers + kay@vrfy.org + + + + + + udev + 7 + + + + udev + Dynamic device management + + + Description + udev supplies the system software with device events, manages permissions + of device nodes and may create additional symlinks in the /dev + directory, or renames network interfaces. The kernel usually just assigns unpredictable + device names based on the order of discovery. Meaningful symlinks or network device + names provide a way to reliably identify devices based on their properties or + current configuration. + + The udev daemon, systemd-udevd.service + 8, receives device uevents directly from + the kernel whenever a device is added or removed from the system, or it changes its + state. When udev receives a device event, it matches its configured set of rules + against various device attributes to identify the device. Rules that match may + provide additional device information to be stored in the udev database or + to be used to create meaningful symlink names. + + All device information udev processes is stored in the udev database and + sent out to possible event subscribers. Access to all stored data and the event + sources is provided by the library libudev. + + + Rules Files + The udev rules are read from the files located in the + system rules directory /usr/lib/udev/rules.d, + the volatile runtime directory /run/udev/rules.d + and the local administration directory /etc/udev/rules.d. + All rules 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 /etc + have the highest priority, files in /run take precedence + over files with the same name in /usr/lib. This can be + used to override a system-supplied rules file with a local file if needed; + a symlink in /etc with the same name as a rules file in + /usr/lib, pointing to /dev/null, + disables the rules file entirely. Rule files must have the extension + .rules; other extensions are ignored. + + Every line in the rules file contains at least one key-value pair. + Except for empty lines or lines beginning with #, which are ignored. + There are two kinds of keys: match and assignment. + If all match keys match against their values, the rule gets applied and the + assignment keys get the specified values assigned. + + A matching rule may rename a network interface, add symlinks + pointing to the device node, or run a specified program as part of + the event handling. + + A rule consists of a comma-separated list of one or more key-value pairs. + Each key has a distinct operation, depending on the used operator. Valid + operators are: + + + == + + Compare for equality. + + + + + != + + Compare for inequality. + + + + + = + + Assign a value to a key. Keys that represent a list are reset + and only this single value is assigned. + + + + + += + + Add the value to a key that holds a list of entries. + + + + + -= + + Remove the value from a key that holds a list of entries. + + + + + := + + Assign a value to a key finally; disallow any later changes. + + + + + The following key names can be used to match against device properties. + Some of the keys also match against properties of the parent devices in sysfs, + not only the device that has generated the event. If multiple keys that match + a parent device are specified in a single rule, all these keys must match at + one and the same parent device. + + + ACTION + + Match the name of the event action. + + + + + DEVPATH + + Match the devpath of the event device. + + + + + KERNEL + + Match the name of the event device. + + + + + NAME + + Match the name of a network interface. It can be used once the + NAME key has been set in one of the preceding rules. + + + + + SYMLINK + + Match the name of a symlink targeting the node. It can + be used once a SYMLINK key has been set in one of the preceding + rules. There may be multiple symlinks; only one needs to match. + + + + + + SUBSYSTEM + + Match the subsystem of the event device. + + + + DRIVER + + Match the driver name of the event device. Only set this key for devices + which are bound to a driver at the time the event is generated. + + + + ATTR{filename} + + Match sysfs attribute values of the event device. Trailing + whitespace in the attribute values is ignored unless the specified match + value itself contains trailing whitespace. + + + SYSCTL{kernel parameter} + + Match a kernel parameter value. + + + + + + KERNELS + + Search the devpath upwards for a matching device name. + + + + + SUBSYSTEMS + + Search the devpath upwards for a matching device subsystem name. + + + + + DRIVERS + + Search the devpath upwards for a matching device driver name. + + + + + ATTRS{filename} + + Search the devpath upwards for a device with matching sysfs attribute values. + If multiple ATTRS matches are specified, all of them + must match on the same device. Trailing whitespace in the attribute values is ignored + unless the specified match value itself contains trailing whitespace. + + + + + TAGS + + Search the devpath upwards for a device with matching tag. + + + + + ENV{key} + + Match against a device property value. + + + + + TAG + + Match against a device tag. + + + + + TEST{octal mode mask} + + Test the existence of a file. An octal mode mask can be specified + if needed. + + + + + PROGRAM + + Execute a program to determine whether there + is a match; the key is true if the program returns + successfully. The device properties are made available to the + executed program in the environment. The program's standard output + is available in the RESULT key. + This can only be used for very short-running foreground tasks. For details, + see RUN. + + + + + RESULT + + Match the returned string of the last PROGRAM call. + This key can be used in the same or in any later rule after a + PROGRAM call. + + + + + Most of the fields support shell glob pattern matching and + alternate patterns. The following special characters are supported: + + + * + + Matches zero or more characters. + + + + ? + + Matches any single character. + + + + [] + + Matches any single character specified within the brackets. For + example, the pattern string tty[SR] + would match either ttyS or ttyR. + Ranges are also supported via the - character. + For example, to match on the range of all digits, the pattern + [0-9] could be used. If the first character + following the [ is a !, + any characters not enclosed are matched. + + + + | + + Separates alternative patterns. For example, the pattern string + abc|x* would match either abc + or x*. + + + + + The following keys can get values assigned: + + + NAME + + The name to use for a network interface. See + systemd.link5 + for a higher-level mechanism for setting the interface name. + The name of a device node cannot be changed by udev, only additional + symlinks can be created. + + + + + SYMLINK + + The name of a symlink targeting the node. Every matching rule adds + this value to the list of symlinks to be created. + The set of characters to name a symlink is limited. Allowed + characters are 0-9A-Za-z#+-.:=@_/, valid UTF-8 character + sequences, and \x00 hex encoding. All other + characters are replaced by a _ character. + Multiple symlinks may be specified by separating the names by the + space character. In case multiple devices claim the same name, the link + always points to the device with the highest link_priority. If the current + device goes away, the links are re-evaluated and the device with the + next highest link_priority becomes the owner of the link. If no + link_priority is specified, the order of the devices (and which one of + them owns the link) is undefined. + Symlink names must never conflict with the kernel's default device + node names, as that would result in unpredictable behavior. + + + + + + OWNER, GROUP, MODE + + The permissions for the device node. Every specified value overrides + the compiled-in default value. + + + + + SECLABEL{module} + + Applies the specified Linux Security Module label to the device node. + + + + + ATTR{key} + + The value that should be written to a sysfs attribute of the + event device. + + + + + SYSCTL{kernel parameter} + + The value that should be written to kernel parameter. + + + + + ENV{key} + + Set a device property value. Property names with a leading . + are neither stored in the database nor exported to events or + external tools (run by, for example, the PROGRAM + match key). + + + + + TAG + + Attach a tag to a device. This is used to filter events for users + of libudev's monitor functionality, or to enumerate a group of tagged + devices. The implementation can only work efficiently if only a few + tags are attached to a device. It is only meant to be used in + contexts with specific device filter requirements, and not as a + general-purpose flag. Excessive use might result in inefficient event + handling. + + + + + RUN{type} + + Add a program to the list of programs to be executed after + processing all the rules for a specific event, depending on + type: + + + program + + Execute an external program specified as the assigned + value. If no absolute path is given, the program is expected + to live in /usr/lib/udev; otherwise, the + absolute path must be specified. + This is the default if no type + is specified. + + + + builtin + + As program, but use one of the + built-in programs rather than an external one. + + + + The program name and following arguments are separated by spaces. + Single quotes can be used to specify arguments with spaces. + This can only be used for very short-running foreground tasks. Running an + event process for a long period of time may block all further events for + this or a dependent device. + Starting daemons or other long-running processes is not appropriate + for udev; the forked processes, detached or not, will be unconditionally + killed after the event handling has finished. + + + + + LABEL + + A named label to which a GOTO may jump. + + + + + GOTO + + Jumps to the next LABEL with a matching name. + + + + + IMPORT{type} + + Import a set of variables as device properties, + depending on type: + + + program + + Execute an external program specified as the assigned + value and, if it returns successfully, + import its output, which must be in environment key + format. Path specification, command/argument separation, + and quoting work like in RUN. + + + + builtin + + Similar to program, but use one of the + built-in programs rather than an external one. + + + + file + + Import a text file specified as the assigned value, the content + of which must be in environment key format. + + + + db + + Import a single property specified as the assigned value from the + current device database. This works only if the database is already populated + by an earlier event. + + + + cmdline + + Import a single property from the kernel command line. For simple flags + the value of the property is set to 1. + + + + parent + + Import the stored keys from the parent device by reading + the database entry of the parent device. The value assigned to + is used as a filter of key names + to import (with the same shell glob pattern matching used for + comparisons). + + + + This can only be used for very short-running foreground tasks. For details + see . + + + + + OPTIONS + + Rule and device options: + + + + + Specify the priority of the created symlinks. Devices with higher + priorities overwrite existing symlinks of other devices. The default is 0. + + + + + + Usually, control and other possibly unsafe characters are replaced + in strings used for device naming. The mode of replacement can be specified + with this option. + + + + + + Apply the permissions specified in this rule to the + static device node with the specified name. Also, for every + tag specified in this rule, create a symlink + in the directory + /run/udev/static_node-tags/tag + pointing at the static device node with the specified name. + Static device node creation is performed by systemd-tmpfiles + before systemd-udevd is started. The static nodes might not + have a corresponding kernel device; they are used to trigger + automatic kernel module loading when they are accessed. + + + + + + Watch the device node with inotify; when the node is + closed after being opened for writing, a change uevent is + synthesized. + + + + + + Disable the watching of a device node with inotify. + + + + + + + + The NAME, SYMLINK, + PROGRAM, OWNER, + GROUP, MODE, and + RUN fields support simple string substitutions. + The RUN substitutions are performed after all rules + have been processed, right before the program is executed, allowing for + the use of device properties set by earlier matching rules. For all other + fields, substitutions are performed while the individual rule is being + processed. The available substitutions are: + + + , + + The kernel name for this device. + + + + + , + + The kernel number for this device. For example, + sda3 has kernel number 3. + + + + + + , + + The devpath of the device. + + + + + , + + The name of the device matched while searching the devpath + upwards for , , + , and . + + + + + + + + The driver name of the device matched while searching the + devpath upwards for , + , , and + . + + + + + + , + + The value of a sysfs attribute found at the device where + all keys of the rule have matched. If the matching device does not + have such an attribute, and a previous , + , , or + test selected a parent device, then the + attribute from that parent device is used. + + If the attribute is a symlink, the last element of the + symlink target is returned as the value. + + + + + + , + + A device property value. + + + + + , + + The kernel major number for the device. + + + + + , + + The kernel minor number for the device. + + + + + , + + The string returned by the external program requested with + PROGRAM. + A single part of the string, separated by a space character, may be selected + by specifying the part number as an attribute: %c{N}. + If the number is followed by the + character, this part plus all remaining parts + of the result string are substituted: %c{N+}. + + + + + , + + The node name of the parent device. + + + + + + + The current name of the device. If not changed by a rule, it is the + name of the kernel device. + + + + + + + A space-separated list of the current symlinks. The value is + only set during a remove event or if an earlier rule assigned a value. + + + + + , + + The udev_root value. + + + + + , + + The sysfs mount point. + + + + + , + + The name of the device node. + + + + + + + The % character itself. + + + + + + + The $ character itself. + + + + + + + See Also + + + systemd-udevd.service8 + , + + udevadm8 + , + + systemd.link5 + + + + diff --git a/src/grp-udev/udevadm/udevadm.xml b/src/grp-udev/udevadm/udevadm.xml new file mode 100644 index 0000000000..8c1abd2770 --- /dev/null +++ b/src/grp-udev/udevadm/udevadm.xml @@ -0,0 +1,576 @@ + + + + + + udevadm + systemd + + + Developer + Kay + Sievers + kay@vrfy.org + + + + + + udevadm + 8 + + + + udevadmudev management tool + + + + + udevadm + + + + + + udevadm info options + + + udevadm trigger options + + + udevadm settle options + + + udevadm control command + + + udevadm monitor options + + + udevadm test options devpath + + + udevadm test-builtin options command devpath + + + + Description + udevadm expects a command and command + specific options. It controls the runtime behavior of + systemd-udevd, requests kernel events, manages + the event queue, and provides simple debugging mechanisms. + + + Options + + + + + Print debug messages to standard error. + + + + + + Print version number. + + + + + + + Print help text. + + + + + udevadm info + <arg choice="opt"><replaceable>options</replaceable></arg> + <arg choice="opt"><replaceable>devpath</replaceable>|<replaceable>file</replaceable></arg> + + + Queries the udev database for device information + stored in the udev database. It can also query the properties + of a device from its sysfs representation to help creating udev + rules that match this device. + + + + + + Query the database for the specified type of device + data. It needs the or + to identify the specified device. + Valid TYPEs are: + name, symlink, + path, property, + all. + + + + + + + The /sys path of the device to + query, e.g. + /sys/class/block/sda. + Note that this option usually is not very useful, since + udev can guess the type of the + argument, so udevadm + --devpath=/class/block/sda is equivalent to + udevadm /sys/class/block/sda. + + + + + + + The name of the device node or a symlink to query, + e.g. /dev/sda. + Note that this option usually is not very useful, since + udev can guess the type of the + argument, so udevadm --name=sda is + equivalent to udevadm /dev/sda. + + + + + + + Print absolute paths in name or symlink + query. + + + + + + + Print all sysfs properties of the specified device that can be used + in udev rules to match the specified device. It prints all devices + along the chain, up to the root of sysfs that can be used in udev rules. + + + + + + + Print output as key/value pairs. Values are enclosed in single quotes. + + + + + + + Add a prefix to the key name of exported values. + + + + + + + Print major/minor numbers of the underlying device, where the file + lives on. + + + + + + + Export the content of the udev database. + + + + + + + Cleanup the udev database. + + + + + + Print version. + + + + + + + Print help text. + + + + + In addition, an optional positional argument can be used + to specify a device name or a sys path. It must start with + /dev or /sys + respectively. + + + udevadm trigger + <arg choice="opt"><replaceable>options</replaceable></arg> + <arg choice="opt" rep="repeat"><replaceable>devpath</replaceable>|<replaceable>file</replaceable></arg> + Request device events from the kernel. Primarily used to replay events at system coldplug time. + + + + + + Print the list of devices which will be triggered. + + + + + + + Do not actually trigger the event. + + + + + + + Trigger a specific type of devices. Valid types are: + devices, subsystems. + The default value is devices. + + + + + + + Type of event to be triggered. The default value is + change. + + + + + + + Trigger events for devices which belong to a + matching subsystem. This option can be specified multiple + times and supports shell style pattern matching. + + + + + + + Do not trigger events for devices which belong to a matching subsystem. This option + can be specified multiple times and supports shell style pattern matching. + + + + + + + Trigger events for devices with a matching sysfs + attribute. If a value is specified along with the + attribute name, the content of the attribute is matched + against the given value using shell style pattern + matching. If no value is specified, the existence of the + sysfs attribute is checked. This option can be specified + multiple times. + + + + + + + Do not trigger events for devices with a matching + sysfs attribute. If a value is specified along with the + attribute name, the content of the attribute is matched + against the given value using shell style pattern + matching. If no value is specified, the existence of the + sysfs attribute is checked. This option can be specified + multiple times. + + + + + + + Trigger events for devices with a matching property + value. This option can be specified multiple times and + supports shell style pattern matching. + + + + + + + Trigger events for devices with a matching tag. This + option can be specified multiple times. + + + + + + + Trigger events for devices with a matching sys + device path. This option can be specified multiple times + and supports shell style pattern matching. + + + + + + Trigger events for devices with a matching + device path. This option can be specified multiple + times. + + + + + + + Trigger events for all children of a given + device. + + + + + + + Print help text. + + + + + In addition, optional positional arguments can be used + to specify device names or sys paths. They must start with + /dev or /sys + respectively. + + + udevadm settle + <arg choice="opt"><replaceable>options</replaceable></arg> + + Watches the udev event queue, and exits if all current events are handled. + + + + + + Maximum number of seconds to wait for the event + queue to become empty. The default value is 120 seconds. A + value of 0 will check if the queue is empty and always + return immediately. + + + + + + + Stop waiting if file exists. + + + + + + + Print help text. + + + + + + udevadm control <replaceable>command</replaceable> + Modify the internal state of the running udev daemon. + + + + + + Signal and wait for systemd-udevd to exit. + + + + + + + Set the internal log level of + systemd-udevd. Valid values are the + numerical syslog priorities or their textual + representations: , + , , + , , + , , and + . + + + + + + + Signal systemd-udevd to stop executing new events. Incoming events + will be queued. + + + + + + + Signal systemd-udevd to enable the execution of events. + + + + + + + Signal systemd-udevd to reload the rules files and other databases like the kernel + module index. Reloading rules and databases does not apply any changes to already + existing devices; the new configuration will only be applied to new events. + + + + + + + Set a global property for all events. + + + + + value + + Set the maximum number of events, systemd-udevd will handle at the + same time. + + + + seconds + + The maximum number of seconds to wait for a reply from systemd-udevd. + + + + + + + Print help text. + + + + + + udevadm monitor + <arg choice="opt"><replaceable>options</replaceable></arg> + + Listens to the kernel uevents and events sent out by a udev rule + and prints the devpath of the event to the console. It can be used to analyze the + event timing, by comparing the timestamps of the kernel uevent and the udev event. + + + + + + + Print the kernel uevents. + + + + + + + Print the udev event after the rule processing. + + + + + + + Also print the properties of the event. + + + + + + + Filter events by subsystem[/devtype]. Only udev events with a matching subsystem value will pass. + + + + + + + Filter events by property. Only udev events with a given tag attached will pass. + + + + + + + Print help text. + + + + + + udevadm test + <arg choice="opt"><replaceable>options</replaceable></arg> + <arg><replaceable>devpath</replaceable></arg> + + Simulate a udev event run for the given device, and print debug output. + + + + + + The action string. + + + + + + + Specify when udevadm should resolve names of users + and groups. When set to early (the + default), names will be resolved when the rules are + parsed. When set to late, names will + be resolved for every event. When set to + never, names will never be resolved + and all devices will be owned by root. + + + + + + + Print help text. + + + + + + udevadm test-builtin + <arg choice="opt"><replaceable>options</replaceable></arg> + <arg><replaceable>command</replaceable></arg> + <arg><replaceable>devpath</replaceable></arg> + + Run a built-in command COMMAND + for device DEVPATH, and print debug + output. + + + + + + Print help text. + + + + + + + + See Also + + udev7 + , + + systemd-udevd.service8 + + + diff --git a/src/grp-utils/systemd-escape/systemd-escape.xml b/src/grp-utils/systemd-escape/systemd-escape.xml new file mode 100644 index 0000000000..dbb3869a24 --- /dev/null +++ b/src/grp-utils/systemd-escape/systemd-escape.xml @@ -0,0 +1,178 @@ + + + + + + + + + systemd-escape + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-escape + 1 + + + + systemd-escape + Escape strings for usage in system unit names + + + + + systemd-escape + OPTIONS + STRING + + + + + Description + + systemd-escape may be used to escape + strings for inclusion in systemd unit names. The command may be + used to escape and to undo escaping of strings. + + The command takes any number of strings on the command line, + and will process them individually, one after another. It will + output them separated by spaces to stdout. + + By default, this command will escape the strings passed, + unless is passed which results in the + inverse operation being applied. If is given, a + special mode of escaping is applied instead, which assumes the + string is already escaped but will escape everything that + appears obviously non-escaped. + + + + Options + + The following options are understood: + + + + + + Appends the specified unit type suffix to the + escaped string. Takes one of the unit types supported by + systemd, such as .service or + .mount. May not be used in conjunction with + , or + . + + + + + + Inserts the escaped strings in a unit name + template. Takes a unit name template such as + foobar@.service May not be used in + conjunction with , + or + . + + + + + + + When escaping or unescaping a string, assume + it refers to a file system path. This enables special + processing of the initial / of the + path. + + + + + + Instead of escaping the specified strings, + undo the escaping, reversing the operation. May not be used in + conjunction with , + or + . + + + + + + Like , but only + escape characters that are obviously not escaped yet, and + possibly automatically append an appropriate unit type suffix + to the string. May not be used in conjunction with + , or + . + + + + + + + + + + Examples + + Escape a single string: + $ systemd-escape 'Hallöchen, Meister' +Hall\xc3\xb6chen\x2c\x20Meister + + To undo escaping on a single string: + $ systemd-escape -u 'Hall\xc3\xb6chen\x2c\x20Meister' +Hallöchen, Meister + + To generate the mount unit for a path: + $ systemd-escape -p --suffix=mount "/tmp//waldi/foobar/" +tmp-waldi-foobar.mount + + To generate instance names of three strings + $ systemd-escape --template=systemd-nspawn@.service 'My Container 1' 'containerb' 'container/III' +systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + See Also + + systemd1, + systemctl1 + + + + diff --git a/src/grp-utils/systemd-notify/systemd-notify.xml b/src/grp-utils/systemd-notify/systemd-notify.xml new file mode 100644 index 0000000000..a5f4077166 --- /dev/null +++ b/src/grp-utils/systemd-notify/systemd-notify.xml @@ -0,0 +1,185 @@ + + + + + + + + + systemd-notify + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-notify + 1 + + + + systemd-notify + Notify service manager about start-up completion and other daemon status changes + + + + + systemd-notify OPTIONS VARIABLE=VALUE + + + + + Description + + systemd-notify may be called by daemon + scripts to notify the init system about status changes. It can be + used to send arbitrary information, encoded in an + environment-block-like list of strings. Most importantly, it can be + used for start-up completion notification. + + This is mostly just a wrapper around + sd_notify() and makes this functionality + available to shell scripts. For details see + sd_notify3. + + + The command line may carry a list of environment variables + to send as part of the status update. + + Note that systemd will refuse reception of status updates + from this command unless NotifyAccess=all is + set for the service unit this command is called from. + + + + + Options + + The following options are understood: + + + + + + Inform the init system about service start-up + completion. This is equivalent to systemd-notify + READY=1. For details about the semantics of this + option see + sd_notify3. + + + + + + Inform the init system about the main PID of + the daemon. Takes a PID as argument. If the argument is + omitted, the PID of the process that invoked + systemd-notify is used. This is equivalent + to systemd-notify MAINPID=$PID. For details + about the semantics of this option see + sd_notify3. + + + + + + Send a free-form status string for the daemon + to the init systemd. This option takes the status string as + argument. This is equivalent to systemd-notify + STATUS=.... For details about the semantics of this + option see + sd_notify3. + + + + + + Returns 0 if the system was booted up with + systemd, non-zero otherwise. If this option is passed, no + message is sent. This option is hence unrelated to the other + options. For details about the semantics of this option, see + sd_booted3. An + alternate way to check for this state is to call + systemctl1 + with the is-system-running command. It will + return offline if the system was not booted + with systemd. + + + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + Example + + + Start-up Notification and Status Updates + + A simple shell daemon that sends start-up notifications + after having set up its communication channel. During runtime it + sends further status updates to the init system: + + #!/bin/bash + +mkfifo /tmp/waldo +systemd-notify --ready --status="Waiting for data..." + +while : ; do + read a < /tmp/waldo + systemd-notify --status="Processing $a" + + # Do something with $a ... + + systemd-notify --status="Waiting for data..." +done + + + + + See Also + + systemd1, + systemctl1, + systemd.unit5, + sd_notify3, + sd_booted3 + + + + diff --git a/src/grp-utils/systemd-path/systemd-path.xml b/src/grp-utils/systemd-path/systemd-path.xml new file mode 100644 index 0000000000..e2b23eec51 --- /dev/null +++ b/src/grp-utils/systemd-path/systemd-path.xml @@ -0,0 +1,107 @@ + + + + + + + + + systemd-path + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-path + 1 + + + + systemd-path + List and query system and user paths + + + + + systemd-path OPTIONS NAME + + + + + Description + + systemd-path may be used to query system + and user paths. The tool makes many of the paths described in + file-hierarchy7 + available for querying. + + When invoked without arguments, a list of known paths and + their current values is shown. When at least one argument is + passed, the path with this name is queried and its value shown. + The variables whose name begins with search- + do not refer to individual paths, but instead to a list of + colon-separated search paths, in their order of precedence. + + + + Options + + The following options are understood: + + + + + + The printed paths are suffixed by the + specified string. + + + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + See Also + + systemd1, + file-hierarchy7 + + + + diff --git a/src/grp-utils/systemd-socket-activate/systemd-socket-activate.xml b/src/grp-utils/systemd-socket-activate/systemd-socket-activate.xml new file mode 100644 index 0000000000..5d7f157c72 --- /dev/null +++ b/src/grp-utils/systemd-socket-activate/systemd-socket-activate.xml @@ -0,0 +1,206 @@ + + + + + + + + + systemd-socket-activate + systemd + + + + Developer + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + systemd-socket-activate + 1 + + + + systemd-socket-activate + Test socket activation of daemons + + + + + systemd-socket-activate + OPTIONS + daemon + OPTIONS + + + + + Description + + systemd-socket-activate may be used to launch a socket-activated service binary from the command + line for testing purposes. It may also be used to launch individual instances of the service binary per connection. + + + The daemon to launch and its options should be specified + after options intended for systemd-socket-activate. + + + If the option is given, the socket file descriptor will be used as the standard + input and output of the launched process. Otherwise, standard input and output will be inherited, and sockets will + be passed through file descriptors 3 and higher. Sockets passed through $LISTEN_FDS to + systemd-socket-activate will be passed through to the daemon, in the original positions. Other sockets + specified with will use consecutive descriptors. By default, + systemd-socket-activate listens on a stream socket, use and + to listen on datagram or sequential packet sockets instead (see below). + + + + + Options + + + + + + Listen on this address. + Takes a string like 2000 or + 127.0.0.1:2001. + + + + + + + + Launch an instance of the service binary for each connection and pass the connection + socket. + + + + + + + Listen on a datagram socket (SOCK_DGRAM), instead of a stream socket + (SOCK_STREAM). May not be combined with . + + + + + + Listen on a sequential packet socket (SOCK_SEQPACKET), instead of a stream + socket (SOCK_STREAM). May not be combined with + . + + + + + + Use the inetd protocol for passing file descriptors, i.e. as standard input and standard + output, instead of the new-style protocol for passing file descriptors using $LISTEN_FDS + (see above). + + + + + + + Add this variable to the environment of the + launched process. If VAR is + followed by =, assume that it is a + variable–value pair. Otherwise, obtain the value from the + environment of systemd-socket-activate itself. + + + + + NAME:NAME... + + Specify names for the file descriptors passed. This is equivalent to setting + FileDescriptorName= in socket unit files, and enables use of + sd_listen_fds_with_names3. + Multiple entries may be specifies using separate options or by separating names with colons + (:) in one option. In case more names are given than descriptors, superflous ones willl be + ignored. In case less names are given than descriptors, the remaining file descriptors will be unnamed. + + + + + + + + + + Environment variables + + + $LISTEN_FDS + $LISTEN_PID + $LISTEN_FDNAMES + + See + sd_listen_fds3. + + + + $SYSTEMD_LOG_TARGET + $SYSTEMD_LOG_LEVEL + $SYSTEMD_LOG_COLOR + $SYSTEMD_LOG_LOCATION + + Same as in + systemd1. + + + + + + Examples + + + Run an echo server on port 2000 + + $ systemd-socket-activate -l 2000 --inetd -a cat + + + + Run a socket-activated instance of <citerefentry><refentrytitle>systemd-journal-gatewayd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + + $ systemd-socket-activate -l 19531 /usr/lib/systemd/systemd-journal-gatewayd + + + + + See Also + + systemd1, + systemd.socket5, + systemd.service5, + sd_listen_fds3, + sd_listen_fds_with_names3, + cat1 + + + diff --git a/src/libsystemd/sd-bus-errors.xml b/src/libsystemd/sd-bus-errors.xml new file mode 100644 index 0000000000..d2b81f4e4a --- /dev/null +++ b/src/libsystemd/sd-bus-errors.xml @@ -0,0 +1,309 @@ + + + + + + + + + sd-bus-errors + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd-bus-errors + 3 + + + + sd-bus-errors + SD_BUS_ERROR_FAILED + SD_BUS_ERROR_NO_MEMORY + SD_BUS_ERROR_SERVICE_UNKNOWN + SD_BUS_ERROR_NAME_HAS_NO_OWNER + SD_BUS_ERROR_NO_REPLY + SD_BUS_ERROR_IO_ERROR + SD_BUS_ERROR_BAD_ADDRESS + SD_BUS_ERROR_NOT_SUPPORTED + SD_BUS_ERROR_LIMITS_EXCEEDED + SD_BUS_ERROR_ACCESS_DENIED + SD_BUS_ERROR_AUTH_FAILED + SD_BUS_ERROR_NO_SERVER + SD_BUS_ERROR_TIMEOUT + SD_BUS_ERROR_NO_NETWORK + SD_BUS_ERROR_ADDRESS_IN_USE + SD_BUS_ERROR_DISCONNECTED + SD_BUS_ERROR_INVALID_ARGS + SD_BUS_ERROR_FILE_NOT_FOUND + SD_BUS_ERROR_FILE_EXISTS + SD_BUS_ERROR_UNKNOWN_METHOD + SD_BUS_ERROR_UNKNOWN_OBJECT + SD_BUS_ERROR_UNKNOWN_INTERFACE + SD_BUS_ERROR_UNKNOWN_PROPERTY + SD_BUS_ERROR_PROPERTY_READ_ONLY + SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN + SD_BUS_ERROR_INVALID_SIGNATURE + SD_BUS_ERROR_INCONSISTENT_MESSAGE + SD_BUS_ERROR_MATCH_RULE_NOT_FOUND + SD_BUS_ERROR_MATCH_RULE_INVALID + SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED + + Standard D-Bus error names + + + + + #include <systemd/sd-bus.h> + +#define SD_BUS_ERROR_FAILED "org.freedesktop.DBus.Error.Failed" +#define SD_BUS_ERROR_NO_MEMORY "org.freedesktop.DBus.Error.NoMemory" +#define SD_BUS_ERROR_SERVICE_UNKNOWN "org.freedesktop.DBus.Error.ServiceUnknown" +#define SD_BUS_ERROR_NAME_HAS_NO_OWNER "org.freedesktop.DBus.Error.NameHasNoOwner" +#define SD_BUS_ERROR_NO_REPLY "org.freedesktop.DBus.Error.NoReply" +#define SD_BUS_ERROR_IO_ERROR "org.freedesktop.DBus.Error.IOError" +#define SD_BUS_ERROR_BAD_ADDRESS "org.freedesktop.DBus.Error.BadAddress" +#define SD_BUS_ERROR_NOT_SUPPORTED "org.freedesktop.DBus.Error.NotSupported" +#define SD_BUS_ERROR_LIMITS_EXCEEDED "org.freedesktop.DBus.Error.LimitsExceeded" +#define SD_BUS_ERROR_ACCESS_DENIED "org.freedesktop.DBus.Error.AccessDenied" +#define SD_BUS_ERROR_AUTH_FAILED "org.freedesktop.DBus.Error.AuthFailed" +#define SD_BUS_ERROR_NO_SERVER "org.freedesktop.DBus.Error.NoServer" +#define SD_BUS_ERROR_TIMEOUT "org.freedesktop.DBus.Error.Timeout" +#define SD_BUS_ERROR_NO_NETWORK "org.freedesktop.DBus.Error.NoNetwork" +#define SD_BUS_ERROR_ADDRESS_IN_USE "org.freedesktop.DBus.Error.AddressInUse" +#define SD_BUS_ERROR_DISCONNECTED "org.freedesktop.DBus.Error.Disconnected" +#define SD_BUS_ERROR_INVALID_ARGS "org.freedesktop.DBus.Error.InvalidArgs" +#define SD_BUS_ERROR_FILE_NOT_FOUND "org.freedesktop.DBus.Error.FileNotFound" +#define SD_BUS_ERROR_FILE_EXISTS "org.freedesktop.DBus.Error.FileExists" +#define SD_BUS_ERROR_UNKNOWN_METHOD "org.freedesktop.DBus.Error.UnknownMethod" +#define SD_BUS_ERROR_UNKNOWN_OBJECT "org.freedesktop.DBus.Error.UnknownObject" +#define SD_BUS_ERROR_UNKNOWN_INTERFACE "org.freedesktop.DBus.Error.UnknownInterface" +#define SD_BUS_ERROR_UNKNOWN_PROPERTY "org.freedesktop.DBus.Error.UnknownProperty" +#define SD_BUS_ERROR_PROPERTY_READ_ONLY "org.freedesktop.DBus.Error.PropertyReadOnly" +#define SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN "org.freedesktop.DBus.Error.UnixProcessIdUnknown" +#define SD_BUS_ERROR_INVALID_SIGNATURE "org.freedesktop.DBus.Error.InvalidSignature" +#define SD_BUS_ERROR_INCONSISTENT_MESSAGE "org.freedesktop.DBus.Error.InconsistentMessage" +#define SD_BUS_ERROR_MATCH_RULE_NOT_FOUND "org.freedesktop.DBus.Error.MatchRuleNotFound" +#define SD_BUS_ERROR_MATCH_RULE_INVALID "org.freedesktop.DBus.Error.MatchRuleInvalid" +#define SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED \ + "org.freedesktop.DBus.Error.InteractiveAuthorizationRequired" + + + + + + Description + + In addition to the error names user programs define, D-Bus + knows a number of generic, standardized error names that are + listed below. + + In addition to this list, in sd-bus, the special error + namespace System.Error. is used to map + arbitrary GNU/Linux system errors (as defined by errno3) + to D-Bus errors and back. For example, the error + EUCLEAN is mapped to + System.Error.EUCLEAN and back. + + + + + SD_BUS_ERROR_FAILED + A generic error indication. See the error + message for further details. This error name should be + avoided, in favor of a more expressive error + name. + + + + SD_BUS_ERROR_NO_MEMORY + A memory allocation failed, and the requested + operation could not be completed. + + + + SD_BUS_ERROR_SERVICE_UNKNOWN + The contacted bus service is unknown and + cannot be activated. + + + + SD_BUS_ERROR_NAME_HAS_NO_OWNER + The specified bus service name currently has + no owner. + + + SD_BUS_ERROR_NO_REPLY + A message did not receive a reply. This error + is usually generated after a timeout. + + + SD_BUS_ERROR_IO_ERROR + Generic input/output error, for example when + accessing a socket or other I/O context. + + + SD_BUS_ERROR_BAD_ADDRESS + The specified D-Bus bus address string is + malformed. + + + SD_BUS_ERROR_NOT_SUPPORTED + The requested operation is not supported on + the local system. + + + SD_BUS_ERROR_LIMITS_EXCEEDED + Some limited resource has been + exhausted. + + + SD_BUS_ERROR_ACCESS_DENIED + Access to a resource has been denied due to security restrictions. + + + SD_BUS_ERROR_AUTH_FAILED + Authentication did not complete successfully. + + + SD_BUS_ERROR_NO_SERVER + Unable to connect to the specified server. + + + SD_BUS_ERROR_TIMEOUT + An operation timed out. Note that method calls + which timeout generate a + SD_BUS_ERROR_NO_REPLY. + + + SD_BUS_ERROR_NO_NETWORK + No network available to execute requested network operation on. + + + SD_BUS_ERROR_ADDRESS_IN_USE + The specified network address is already being listened on. + + + SD_BUS_ERROR_DISCONNECTED + The connection has been terminated. + + + SD_BUS_ERROR_INVALID_ARGS + One or more invalid arguments have been passed. + + + SD_BUS_ERROR_FILE_NOT_FOUND + The requested file could not be found. + + + SD_BUS_ERROR_FILE_EXISTS + The requested file already exists. + + + SD_BUS_ERROR_UNKNOWN_METHOD + The requested method does not exist in the selected interface. + + + SD_BUS_ERROR_UNKNOWN_OBJECT + The requested object does not exist in the selected service. + + + SD_BUS_ERROR_UNKNOWN_INTERFACE + The requested interface does not exist on the selected object. + + + SD_BUS_ERROR_UNKNOWN_PROPERTY + The requested property does not exist in the selected interface. + + + SD_BUS_ERROR_PROPERTY_READ_ONLY + A write operation was requested on a read-only property. + + + SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN + The requested PID is not known. + + + SD_BUS_ERROR_INVALID_SIGNATURE + The specified message signature is not + valid. + + + + SD_BUS_ERROR_INCONSISTENT_MESSAGE + The passed message does not validate + correctly. + + + SD_BUS_ERROR_MATCH_RULE_NOT_FOUND + The specified match rule does not exist. + + + SD_BUS_ERROR_MATCH_RULE_INVALID + The specified match rule is invalid. + + + SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED + Access to the requested operation is not + permitted. However, it might be available after interactive + authentication. This is usually returned by method calls + supporting a framework for additional interactive + authorization, when interactive authorization was not enabled + with the + sd_bus_message_set_allow_interactive_authorization3 + for the method call message. + + + + + + Notes + + The various error definitions described here are available + as a shared library, which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_error3, + sd_bus_message_set_allow_interactive_authorization3, + errno3, + strerror3 + + + + diff --git a/src/libsystemd/sd_booted.xml b/src/libsystemd/sd_booted.xml new file mode 100644 index 0000000000..4dd674b8ea --- /dev/null +++ b/src/libsystemd/sd_booted.xml @@ -0,0 +1,95 @@ + + + + + + + + + sd_booted + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_booted + 3 + + + + sd_booted + Test whether the system is running the systemd init system + + + + + #include <systemd/sd-daemon.h> + + + int sd_booted + void + + + + + + Description + sd_booted() checks whether the system + was booted up using the systemd init system. + + + + Return Value + + On failure, this call returns a negative errno-style error + code. If the system was booted up with systemd as init system, + this call returns a positive return value, zero otherwise. + + + + Notes + + + + Internally, this function checks whether the directory + /run/systemd/system/ exists. A simple check + like this can also be implemented trivially in shell or any other + language. + + + + See Also + + systemd1, + sd-daemon3 + + + + diff --git a/src/libsystemd/sd_bus_creds_get_pid.xml b/src/libsystemd/sd_bus_creds_get_pid.xml new file mode 100644 index 0000000000..4c05835568 --- /dev/null +++ b/src/libsystemd/sd_bus_creds_get_pid.xml @@ -0,0 +1,566 @@ + + + + + + + + + sd_bus_creds_get_pid + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_creds_get_pid + 3 + + + + sd_bus_creds_get_pid + sd_bus_creds_get_ppid + sd_bus_creds_get_tid + sd_bus_creds_get_uid + sd_bus_creds_get_euid + sd_bus_creds_get_suid + sd_bus_creds_get_fsuid + sd_bus_creds_get_gid + sd_bus_creds_get_egid + sd_bus_creds_get_sgid + sd_bus_creds_get_fsgid + sd_bus_creds_get_supplementary_gids + sd_bus_creds_get_comm + sd_bus_creds_get_tid_comm + sd_bus_creds_get_exe + sd_bus_creds_get_cmdline + sd_bus_creds_get_cgroup + sd_bus_creds_get_unit + sd_bus_creds_get_slice + sd_bus_creds_get_user_unit + sd_bus_creds_get_user_slice + sd_bus_creds_get_session + sd_bus_creds_get_owner_uid + sd_bus_creds_has_effective_cap + sd_bus_creds_has_permitted_cap + sd_bus_creds_has_inheritable_cap + sd_bus_creds_has_bounding_cap + sd_bus_creds_get_selinux_context + sd_bus_creds_get_audit_session_id + sd_bus_creds_get_audit_login_uid + sd_bus_creds_get_tty + sd_bus_creds_get_unique_name + sd_bus_creds_get_well_known_names + sd_bus_creds_get_description + + Retrieve fields from a credentials object + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_creds_get_pid + sd_bus_creds *c + pid_t *pid + + + + int sd_bus_creds_get_ppid + sd_bus_creds *c + pid_t *ppid + + + + int sd_bus_creds_get_tid + sd_bus_creds *c + pid_t *tid + + + + int sd_bus_creds_get_uid + sd_bus_creds *c + uid_t *uid + + + + int sd_bus_creds_get_euid + sd_bus_creds *c + uid_t *uid + + + + int sd_bus_creds_get_suid + sd_bus_creds *c + uid_t *uid + + + + int sd_bus_creds_get_fsuid + sd_bus_creds *c + uid_t *uid + + + + int sd_bus_creds_get_gid + sd_bus_creds *c + gid_t *gid + + + + int sd_bus_creds_get_egid + sd_bus_creds *c + gid_t *gid + + + + int sd_bus_creds_get_sgid + sd_bus_creds *c + gid_t *gid + + + + int sd_bus_creds_get_fsgid + sd_bus_creds *c + gid_t *gid + + + + int sd_bus_creds_get_supplementary_gids + sd_bus_creds *c + const gid_t **gids + + + + int sd_bus_creds_get_comm + sd_bus_creds *c + const char **comm + + + + int sd_bus_creds_get_tid_comm + sd_bus_creds *c + const char **comm + + + + int sd_bus_creds_get_exe + sd_bus_creds *c + const char **exe + + + + int sd_bus_creds_get_cmdline + sd_bus_creds *c + char ***cmdline + + + + int sd_bus_creds_get_cgroup + sd_bus_creds *c + const char **cgroup + + + + int sd_bus_creds_get_unit + sd_bus_creds *c + const char **unit + + + + int sd_bus_creds_get_slice + sd_bus_creds *c + const char **slice + + + + int sd_bus_creds_get_user_unit + sd_bus_creds *c + const char **unit + + + + int sd_bus_creds_get_user_slice + sd_bus_creds *c + const char **slice + + + + int sd_bus_creds_get_session + sd_bus_creds *c + const char **slice + + + + int sd_bus_creds_get_owner_uid + sd_bus_creds *c + uid_t *uid + + + + int sd_bus_creds_has_effective_cap + sd_bus_creds *c + int capability + + + + int sd_bus_creds_has_permitted_cap + sd_bus_creds *c + int capability + + + + int sd_bus_creds_has_inheritable_cap + sd_bus_creds *c + int capability + + + + int sd_bus_creds_has_bounding_cap + sd_bus_creds *c + int capability + + + + int sd_bus_creds_get_selinux_context + sd_bus_creds *c + const char **context + + + + int sd_bus_creds_get_audit_session_id + sd_bus_creds *c + uint32_t *sessionid + + + + int sd_bus_creds_get_audit_login_uid + sd_bus_creds *c + uid_t *loginuid + + + + int sd_bus_creds_get_tty + sd_bus_creds *c + const char **tty + + + + int sd_bus_creds_get_unique_name + sd_bus_creds *c + const char **name + + + + int sd_bus_creds_get_well_known_names + sd_bus_creds *c + char ***name + + + + int sd_bus_creds_get_description + sd_bus_creds *c + const char **name + + + + + + + Description + + These functions return credential information from an + sd_bus_creds object. Credential objects may + be created with + sd_bus_creds_new_from_pid3, + in which case they describe the credentials of the process + identified by the specified PID, with + sd_bus_get_name_creds3, + in which case they describe the credentials of a bus peer + identified by the specified bus name, with + sd_bus_get_owner_creds3, + in which case they describe the credentials of the creator of a + bus, or with + sd_bus_message_get_creds3, + in which case they describe the credentials of the sender of the + message. + + Not all credential fields are part of every + sd_bus_creds object. Use + sd_bus_creds_get_mask3 + to determine the mask of fields available. + + sd_bus_creds_get_pid() will retrieve + the PID (process identifier). Similarly, + sd_bus_creds_get_ppid() will retrieve the + parent PID. Note that PID 1 has no parent process, in which case + -ENXIO is returned. + + sd_bus_creds_get_tid() will retrieve the + TID (thread identifier). + + sd_bus_creds_get_uid() will retrieve + the numeric UID (user identifier). Similarly, + sd_bus_creds_get_euid() returns the effective + UID, sd_bus_creds_get_suid() the saved UID + and sd_bus_creds_get_fsuid() the file system + UID. + + sd_bus_creds_get_gid() will retrieve the + numeric GID (group identifier). Similarly, + sd_bus_creds_get_egid() returns the effective + GID, sd_bus_creds_get_sgid() the saved GID + and sd_bus_creds_get_fsgid() the file system + GID. + + sd_bus_creds_get_supplementary_gids() + will retrieve the supplementary GIDs list. + + sd_bus_creds_get_comm() will retrieve the + comm field (truncated name of the executable, as stored in + /proc/pid/comm). + + + sd_bus_creds_get_tid_comm() will retrieve + the comm field of the thread (as stored in + /proc/pid/task/tid/comm). + + + sd_bus_creds_get_exe() will retrieve + the path to the program executable (as stored in the + /proc/pid/exe + link, but with the (deleted) suffix removed). Note + that kernel threads do not have an executable path, in which case + -ENXIO is returned. + + sd_bus_creds_get_cmdline() will + retrieve an array of command line arguments (as stored in + /proc/pid/cmdline). Note + that kernel threads do not have a command line, in which case + -ENXIO is returned. + + sd_bus_creds_get_cgroup() will retrieve + the cgroup path. See cgroups.txt. + + + sd_bus_creds_get_unit() will retrieve + the systemd unit name (in the system instance of systemd) that the + process is a part of. See + systemd.unit5. For + processes that are not part of a unit, returns -ENXIO. + + + sd_bus_creds_get_user_unit() will + retrieve the systemd unit name (in the user instance of systemd) + that the process is a part of. See + systemd.unit5. For + processes that are not part of a user unit, returns -ENXIO. + + + sd_bus_creds_get_slice() will retrieve + the systemd slice (a unit in the system instance of systemd) that + the process is a part of. See + systemd.slice5. Similarly, + sd_bus_creds_get_user_slice() retrieves the + systemd slice of the process, in the user instance of systemd. + + + sd_bus_creds_get_session() will + retrieve the identifier of the login session that the process is + a part of. See + systemd-logind.service8. For + processes that are not part of a session, returns -ENXIO. + + + sd_bus_creds_get_owner_uid() will + retrieve the numeric UID (user identifier) of the user who owns + the login session that the process is a part of. See + systemd-logind.service8. + For processes that are not part of a session, returns -ENXIO. + + + sd_bus_creds_has_effective_cap() will check whether the capability specified by + capability was set in the effective capabilities mask. A positive return value means that it + was set, zero means that it was not set, and a negative return value indicates an error. See capabilities7 and the + AmbientCapabilities= and CapabilityBoundingSet= settings in + systemd.exec5. + + + sd_bus_creds_has_permitted_cap() is + similar to sd_bus_creds_has_effective_cap(), + but will check the permitted capabilities mask. + + sd_bus_creds_has_inheritable_cap() is + similar to sd_bus_creds_has_effective_cap(), + but will check the inheritable capabilities mask. + + sd_bus_creds_has_bounding_cap() is + similar to sd_bus_creds_has_effective_cap(), + but will check the bounding capabilities mask. + + sd_bus_creds_get_selinux_context() will + retrieve the SELinux security context (label) of the process. + + sd_bus_creds_get_audit_session_id() + will retrieve the audit session identifier of the process. Returns + -ENXIO for processes that are not part of an audit session. + + sd_bus_creds_get_audit_login_uid() will + retrieve the audit user login identifier (the identifier of the + user who is "responsible" for the session). Returns -ENXIO for + processes that are not part of an audit session. + + sd_bus_creds_get_tty() will retrieve + the controlling TTY, without the prefixing "/dev/". Returns -ENXIO + for processes that have no controlling TTY. + + sd_bus_creds_get_unique_name() will + retrieve the D-Bus unique name. See The + D-Bus specification. + + sd_bus_creds_get_well_known_names() will + retrieve the set of D-Bus well-known names. See The + D-Bus specification. + + sd_bus_creds_get_description() will + retrieve a descriptive name of the bus connection of the + peer. This name is useful to discern multiple bus connections by + the same peer, and may be altered by the peer with the + sd_bus_set_description3 + call. + + All functions that take a const + char** parameter will store the answer there as an + address of a NUL-terminated string. It will be valid as long as + c remains valid, and should not be freed or + modified by the caller. + + All functions that take a char*** + parameter will store the answer there as an address of an array + of strings. Each individual string is NUL-terminated, and the + array is NULL-terminated as a whole. It will be valid as long as + c remains valid, and should not be freed or + modified by the caller. + + + + Return Value + + On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error code. + + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENODATA + + The given field is not available in the + credentials object c. + + + + + -ENXIO + + The given field is not specified for the described + process or peer. This will be returned by + sd_bus_get_unit(), + sd_bus_get_slice(), + sd_bus_get_user_unit(), + sd_bus_get_user_slice(), + sd_bus_get_session(), and + sd_bus_get_owner_uid() if the process is + not part of a systemd system unit, systemd user unit, systemd + slice, or logind session. It will also be returned by + sd_bus_creds_get_exe() and + sd_bus_creds_get_cmdline() for kernel + threads (since these are not started from an executable binary, + nor have a command line), and by + sd_bus_creds_get_audit_session_id() and + sd_bus_creds_get_audit_login_uid() when + the process is not part of an audit session, and + sd_bus_creds_get_tty() if the process has + no controlling TTY. + + + + + + -EINVAL + + Specified pointer parameter is NULL. + + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + sd_bus_creds_get_pid() and the other + functions described here are available as a shared library, which + can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_creds_new_from_pid2, + fork2, + execve2, + credentials7, + free3, + proc5, + systemd.journal-fields7 + + + + diff --git a/src/libsystemd/sd_bus_creds_new_from_pid.xml b/src/libsystemd/sd_bus_creds_new_from_pid.xml new file mode 100644 index 0000000000..082f7b67db --- /dev/null +++ b/src/libsystemd/sd_bus_creds_new_from_pid.xml @@ -0,0 +1,353 @@ + + + + + + + + + sd_bus_creds_new_from_pid + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_creds_new_from_pid + 3 + + + + sd_bus_creds_new_from_pid + sd_bus_creds_get_mask + sd_bus_creds_get_augmented_mask + sd_bus_creds_ref + sd_bus_creds_unref + sd_bus_creds_unrefp + + Retrieve credentials object for the specified PID + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_creds_new_from_pid + pid_t pid + uint64_t creds_mask + sd_bus_creds **ret + + + + uint64_t sd_bus_creds_get_mask + const sd_bus_creds *c + + + + uint64_t sd_bus_creds_get_augmented_mask + const sd_bus_creds *c + + + + sd_bus_creds *sd_bus_creds_ref + sd_bus_creds *c + + + + sd_bus_creds *sd_bus_creds_unref + sd_bus_creds *c + + + + void sd_bus_creds_unrefp + sd_bus_creds **c + + + + + SD_BUS_CREDS_PID, + SD_BUS_CREDS_PPID, + SD_BUS_CREDS_TID, + SD_BUS_CREDS_UID, + SD_BUS_CREDS_EUID, + SD_BUS_CREDS_SUID, + SD_BUS_CREDS_FSUID, + SD_BUS_CREDS_GID, + SD_BUS_CREDS_EGID, + SD_BUS_CREDS_SGID, + SD_BUS_CREDS_FSGID, + SD_BUS_CREDS_SUPPLEMENTARY_GIDS, + SD_BUS_CREDS_COMM, + SD_BUS_CREDS_TID_COMM, + SD_BUS_CREDS_EXE, + SD_BUS_CREDS_CMDLINE, + SD_BUS_CREDS_CGROUP, + SD_BUS_CREDS_UNIT, + SD_BUS_CREDS_SLICE, + SD_BUS_CREDS_USER_UNIT, + SD_BUS_CREDS_USER_SLICE, + SD_BUS_CREDS_SESSION, + SD_BUS_CREDS_OWNER_UID, + SD_BUS_CREDS_EFFECTIVE_CAPS, + SD_BUS_CREDS_PERMITTED_CAPS, + SD_BUS_CREDS_INHERITABLE_CAPS, + SD_BUS_CREDS_BOUNDING_CAPS, + SD_BUS_CREDS_SELINUX_CONTEXT, + SD_BUS_CREDS_AUDIT_SESSION_ID, + SD_BUS_CREDS_AUDIT_LOGIN_UID, + SD_BUS_CREDS_TTY, + SD_BUS_CREDS_UNIQUE_NAME, + SD_BUS_CREDS_WELL_KNOWN_NAMES, + SD_BUS_CREDS_DESCRIPTION, + SD_BUS_CREDS_AUGMENT, + _SD_BUS_CREDS_ALL + + + + + Description + + sd_bus_creds_new_from_pid() creates a + new credentials object and fills it with information about the + process pid. The pointer to this object + will be stored in the ret pointer. Note that + credential objects may also be created and retrieved via + sd_bus_get_name_creds3, + sd_bus_get_owner_creds3 + and + sd_bus_message_get_creds3. + + The information that will be stored is determined by + creds_mask. It may contain a subset of ORed + constants SD_BUS_CREDS_PID, + SD_BUS_CREDS_PPID, + SD_BUS_CREDS_TID, + SD_BUS_CREDS_UID, + SD_BUS_CREDS_EUID, + SD_BUS_CREDS_SUID, + SD_BUS_CREDS_FSUID, + SD_BUS_CREDS_GID, + SD_BUS_CREDS_EGID, + SD_BUS_CREDS_SGID, + SD_BUS_CREDS_FSGID, + SD_BUS_CREDS_SUPPLEMENTARY_GIDS, + SD_BUS_CREDS_COMM, + SD_BUS_CREDS_TID_COMM, + SD_BUS_CREDS_EXE, + SD_BUS_CREDS_CMDLINE, + SD_BUS_CREDS_CGROUP, + SD_BUS_CREDS_UNIT, + SD_BUS_CREDS_SLICE, + SD_BUS_CREDS_USER_UNIT, + SD_BUS_CREDS_USER_SLICE, + SD_BUS_CREDS_SESSION, + SD_BUS_CREDS_OWNER_UID, + SD_BUS_CREDS_EFFECTIVE_CAPS, + SD_BUS_CREDS_PERMITTED_CAPS, + SD_BUS_CREDS_INHERITABLE_CAPS, + SD_BUS_CREDS_BOUNDING_CAPS, + SD_BUS_CREDS_SELINUX_CONTEXT, + SD_BUS_CREDS_AUDIT_SESSION_ID, + SD_BUS_CREDS_AUDIT_LOGIN_UID, + SD_BUS_CREDS_TTY, + SD_BUS_CREDS_UNIQUE_NAME, + SD_BUS_CREDS_WELL_KNOWN_NAMES, and + SD_BUS_CREDS_DESCRIPTION. Use the special + value _SD_BUS_CREDS_ALL to request all + supported fields. The SD_BUS_CREDS_AUGMENT + constant may not be ORed into the mask for invocations of + sd_bus_creds_new_from_pid(). + + Fields can be retrieved from the credentials object using + sd_bus_creds_get_pid3 + and other functions which correspond directly to the constants + listed above. + + A mask of fields which were actually successfully retrieved + can be retrieved with + sd_bus_creds_get_mask(). If the credentials + object was created with + sd_bus_creds_new_from_pid(), this will be a + subset of fields requested in creds_mask. + + + Similar to sd_bus_creds_get_mask(), the + function sd_bus_creds_get_augmented_mask() + returns a bitmask of field constants. The mask indicates which + credential fields have been retrieved in a non-atomic fashion. For + credential objects created via + sd_bus_creds_new_from_pid(), this mask will be + identical to the mask returned by + sd_bus_creds_get_mask(). However, for + credential objects retrieved via + sd_bus_get_name_creds(), this mask will be set + for the credential fields that could not be determined atomically + at peer connection time, and which were later added by reading + augmenting credential data from + /proc. Similarly, for credential objects + retrieved via sd_bus_get_owner_creds(), the + mask is set for the fields that could not be determined atomically + at bus creation time, but have been augmented. Similarly, for + credential objects retrieved via + sd_bus_message_get_creds(), the mask is set + for the fields that could not be determined atomically at message + sending time, but have been augmented. The mask returned by + sd_bus_creds_get_augmented_mask() is always a + subset of (or identical to) the mask returned by + sd_bus_creds_get_mask() for the same + object. The latter call hence returns all credential fields + available in the credential object, the former then marks the + subset of those that have been augmented. Note that augmented + fields are unsuitable for authorization decisions, as they may be + retrieved at different times, thus being subject to races. Hence, + augmented fields should be used exclusively for informational + purposes. + + + sd_bus_creds_ref() creates a new + reference to the credentials object c. This + object will not be destroyed until + sd_bus_creds_unref() has been called as many + times plus once more. Once the reference count has dropped to zero, + c cannot be used anymore, so further + calls to sd_bus_creds_ref(c) or + sd_bus_creds_unref(c) are illegal. + + sd_bus_creds_unref() destroys a reference + to c. + + sd_bus_creds_unrefp() is similar to + sd_bus_creds_unref() but takes a pointer to a + pointer to an sd_bus_creds object. This call is useful in + conjunction with GCC's and LLVM's Clean-up + Variable Attribute. Note that this function is defined as + inline function. + + sd_bus_creds_ref(), + sd_bus_creds_unref() and + sd_bus_creds_unrefp() execute no operation if + the passed in bus credentials object is + NULL. + + + + + Return Value + + On success, sd_bus_creds_new_from_pid() + returns 0 or a positive integer. On failure, it returns a negative + errno-style error code. + + sd_bus_creds_get_mask() returns the + mask of successfully acquired fields. + + sd_bus_creds_get_augmented_mask() + returns the mask of fields that have been augmented from data in + /proc, and are thus not suitable for + authorization decisions. + + sd_bus_creds_ref() always returns the + argument. + + sd_bus_creds_unref() always returns + NULL. + + + + Reference ownership + + Function sd_bus_creds_new_from_pid() + creates a new object and the caller owns the sole reference. When + not needed anymore, this reference should be destroyed with + sd_bus_creds_unref3. + + + + + Errors + + Returned errors may indicate the following problems: + + + + + -ESRCH + + Specified pid could not + be found. + + + + -EINVAL + + Specified parameter is invalid + (NULL in case of output + parameters). + + + + -ENOMEM + + Memory allocation failed. + + + + -EOPNOTSUPP + + One of the requested fields is unknown to the local system. + + + + + + Notes + + sd_bus_creds_new_from_pid() and the + other calls described here are available as a shared library, + which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_creds_get_pid3, + sd_bus_get_name_creds3, + sd_bus_get_owner_creds3, + sd_bus_message_get_creds3 + + + + diff --git a/src/libsystemd/sd_bus_default.xml b/src/libsystemd/sd_bus_default.xml new file mode 100644 index 0000000000..6d5a90de72 --- /dev/null +++ b/src/libsystemd/sd_bus_default.xml @@ -0,0 +1,312 @@ + + + + + + + + + sd_bus_default + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_default + 3 + + + + sd_bus_default + sd_bus_default_user + sd_bus_default_system + + sd_bus_open + sd_bus_open_user + sd_bus_open_system + sd_bus_open_system_remote + sd_bus_open_system_machine + + Acquire a connection to a system or user bus + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_default + sd_bus **bus + + + + int sd_bus_default_user + sd_bus **bus + + + + int sd_bus_default_system + sd_bus **bus + + + + int sd_bus_open + sd_bus **bus + + + + int sd_bus_open_user + sd_bus **bus + + + + int sd_bus_open_system + sd_bus **bus + + + + int sd_bus_open_system_remote + sd_bus **bus + const char *host + + + + int sd_bus_open_system_machine + sd_bus **bus + const char *machine + + + + + + + Description + + sd_bus_default() acquires a bus + connection object to the user bus when invoked in user context, or + to the system bus otherwise. The connection object is associated + with the calling thread. Each time the function is invoked from + the same thread, the same object is returned, but its reference + count is increased by one, as long as at least one reference is + kept. When the last reference to the connection is dropped (using + the + sd_bus_unref3 + call), the connection is terminated. Note that the connection is + not automatically terminated when the associated thread ends. It + is important to drop the last reference to the bus connection + explicitly before the thread ends, as otherwise, the connection will + leak. Also, queued but unread or unwritten messages keep the + bus referenced, see below. + + sd_bus_default_user() returns a user + bus connection object associated with the calling thread. + sd_bus_default_system() is similar, but + connects to the system bus. Note that + sd_bus_default() is identical to these two + calls, depending on the execution context. + + sd_bus_open() creates a new, + independent bus connection to the user bus when invoked in user + context, or the system bus + otherwise. sd_bus_open_user() is similar, but + connects only to the user bus. + sd_bus_open_system() does the same, but + connects to the system bus. In contrast to + sd_bus_default(), + sd_bus_default_user(), and + sd_bus_default_system(), these calls return + new, independent connection objects that are not associated with + the invoking thread and are not shared between multiple + invocations. It is recommended to share connections per thread to + efficiently make use the available resources. Thus, it is + recommended to use sd_bus_default(), + sd_bus_default_user() and + sd_bus_default_system() to connect to the + user or system buses. + + If the $DBUS_SESSION_BUS_ADDRESS environment + variable is set + (cf. environ7), + it will be used as the address of the user bus. This variable can + contain multiple addresses separated by ;. If + this variable is not set, a suitable default for the default user + D-Bus instance will be used. + + If the $DBUS_SYSTEM_BUS_ADDRESS + environment variable is set, it will be used as the address of the + system bus. This variable uses the same syntax as + $DBUS_SESSION_BUS_ADDRESS. If this variable is + not set, a suitable default for the default system D-Bus instance + will be used. + + sd_bus_open_system_remote() connects to + the system bus on the specified host using + ssh1. host + consists of an optional user name followed by the + @ symbol, and the hostname. + + + sd_bus_open_system_machine() connects + to the system bus in the specified machine, + where machine is the name of a local + container. See + machinectl1 + for more information about the "machine" concept. Note that + connections into local containers are only available to privileged + processes at this time. + + These calls allocate a bus connection object and initiate + the connection to a well-known bus of some form. An alternative to + using these high-level calls is to create an unconnected bus + object with + sd_bus_new3 + and to connect it with + sd_bus_start3. + + + + + + Reference ownership + The functions sd_bus_open(), + sd_bus_open_user(), + sd_bus_open_system(), + sd_bus_open_system_remote(), and + sd_bus_open_system_machine() return a new + connection object and the caller owns the sole reference. When not + needed anymore, this reference should be destroyed with + sd_bus_unref3. + + + The functions sd_bus_default(), + sd_bus_default_user() and + sd_bus_default_system() do not necessarily + create a new object, but increase the connection reference of an + existing connection object by one. Use + sd_bus_unref3 + to drop the reference. + + Queued but unwritten/unread messages also keep a reference + to their bus connection object. For this reason, even if an + application dropped all references to a bus connection, it might + not get destroyed right away. Until all incoming queued + messages are read, and until all outgoing unwritten messages are + written, the bus object will stay + alive. sd_bus_flush() may be used to write + all outgoing queued messages so they drop their references. To + flush the unread incoming messages, use + sd_bus_close(), which will also close the bus + connection. When using the default bus logic, it is a good idea to + first invoke sd_bus_flush() followed by + sd_bus_close() when a thread or process + terminates, and thus its bus connection object should be + freed. + + The life cycle of the default bus connection should be the + responsibility of the code that creates/owns the thread the + default bus connection object is associated with. Library code + should neither call sd_bus_flush() nor + sd_bus_close() on default bus objects unless + it does so in its own private, self-allocated thread. Library code + should not use the default bus object in other threads unless it + is clear that the program using it will life cycle the bus + connection object and flush and close it before exiting from the + thread. In libraries where it is not clear that the calling + program will life cycle the bus connection object, it is hence + recommended to use sd_bus_open_system() + instead of sd_bus_default_system() and + related calls. + + + + Return Value + + On success, these calls return 0 or a positive + integer. On failure, these calls return a negative + errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + The specified parameters are invalid. + + + + -ENOMEM + + Memory allocation failed. + + + + -ESOCKTNOSUPPORT + + The protocol version required to connect to the selected bus is not supported. + + + + In addition, any further connection-related errors may be + by returned. See sd_bus_send3. + + + + Notes + + sd_bus_open_user() and the other + functions described here are available as a shared library, which + can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_new3, + sd_bus_ref3, + sd_bus_unref3, + ssh1, + systemd-machined.service8, + machinectl1 + + + + diff --git a/src/libsystemd/sd_bus_error.xml b/src/libsystemd/sd_bus_error.xml new file mode 100644 index 0000000000..c2d7ee389b --- /dev/null +++ b/src/libsystemd/sd_bus_error.xml @@ -0,0 +1,389 @@ + + + + + + + + + sd_bus_error + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_error + 3 + + + + sd_bus_error + SD_BUS_ERROR_MAKE_CONST + SD_BUS_ERROR_NULL + sd_bus_error_free + sd_bus_error_set + sd_bus_error_setf + sd_bus_error_set_const + sd_bus_error_set_errno + sd_bus_error_set_errnof + sd_bus_error_set_errnofv + sd_bus_error_get_errno + sd_bus_error_copy + sd_bus_error_is_set + sd_bus_error_has_name + + sd-bus error handling + + + + + #include <systemd/sd-bus.h> + + typedef struct { + const char *name; + const char *message; + ... +} sd_bus_error; + + + SD_BUS_ERROR_MAKE_CONST(name, message) + + + SD_BUS_ERROR_NULL + + + + void sd_bus_error_free + sd_bus_error *e + + + + int sd_bus_error_set + sd_bus_error *e + const char *name + const char *message + + + + int sd_bus_error_setf + sd_bus_error *e + const char *name + const char *format + ... + + + + int sd_bus_error_set_const + sd_bus_error *e + const char *name + const char *message + + + + int sd_bus_error_set_errno + sd_bus_error *e + int error + + + + int sd_bus_error_set_errnof + sd_bus_error *e + int error + const char *format + ... + + + + int sd_bus_error_set_errnofv + sd_bus_error *e + int error + const char *format + va_list ap + + + + int sd_bus_error_get_errno + const sd_bus_error *e + + + + int sd_bus_error_copy + sd_bus_error *dst + const sd_bus_error *e + + + + int sd_bus_error_is_set + const sd_bus_error *e + + + + int sd_bus_error_has_name + const sd_bus_error *e + const char *name + + + + + + + Description + + The sd_bus_error structure carries + information about a D-Bus error condition. The functions described + below may be used to set and query fields in this structure. The + name field contains a short identifier + of an error. It should follow the rules for error names described + in the D-Bus specification, subsection Valid + Names. A number of common, standardized error names are + described in + sd-bus-errors3, + but additional domain-specific errors may be defined by + applications. The message field usually + contains a human-readable string describing the details, but might + be NULL. An unset sd_bus_error structure + should have both fields initialized to NULL. Set an error + structure to SD_BUS_ERROR_NULL in order to + reset both fields to NULL. When no longer necessary, resources + held by the sd_bus_errorstructure should + be destroyed with sd_bus_error_free(). + + sd_bus_error_set() sets an error + structure to the specified name and message strings. The strings + will be copied into internal, newly allocated memory. It is + essential to free the error structure again when it is not + required anymore (see above). The function will return an + errno-like negative value (see errno3) + determined from the specified error name. Various well-known + D-Bus errors are converted to well-known errno + counterparts, and the other ones to -EIO. See + sd-bus-errors3 + for a list of well-known error names. Additional error mappings + may be defined with + sd_bus_error_add_map3. If + e is NULL, no error structure is initialized, + but the error is still converted into an + errno-style error. If + name is NULL, it is + assumed that no error occurred, and 0 is returned. This means that + this function may be conveniently used in a + return statement. If + message is NULL, no message is set. This + call can fail if no memory may be allocated for the name and + message strings, in which case an + SD_BUS_ERROR_NO_MEMORY error might be set + instead and -ENOMEM be returned. Do not use this call on error + structures that are already initialized. If you intend to reuse an + error structure, free the old data stored in it with + sd_bus_error_free() first. + + sd_bus_error_setf() is similar to + sd_bus_error_set(), but takes a printf3 + format string and corresponding arguments to generate the + message field. + + sd_bus_error_set_const() is similar to + sd_bus_error_set(), but the string parameters + are not copied internally, and must hence remain constant and + valid for the lifetime of e. Use this call + to avoid memory allocations when setting error structures. Since + this call does not allocate memory, it will not fail with an + out-of-memory condition as + sd_bus_error_set() can, as described + above. Alternatively, the + SD_BUS_ERROR_MAKE_CONST() macro may be used + to generate a literal, constant bus error structure + on-the-fly. + + sd_bus_error_set_errno() will set + name from an + errno-like value that is converted to a D-Bus + error. strerror_r3 + will be used to set message. Well-known + D-Bus error names will be used for name + if applicable, otherwise a name in the + System.Error. namespace will be generated. The + sign of the specified error number is ignored. The absolute value + is used implicitly. The call always returns a negative value, for + convenient usage in return statements. This + call might fail due to lack of memory, in which case an + SD_BUS_ERROR_NO_MEMORY error is set instead, + and -ENOMEM is returned. + + sd_bus_error_set_errnof() is similar to + sd_bus_error_set_errno(), but in addition to + error, takes a printf3 + format string and corresponding arguments. The + message field will be generated from + format and the arguments. + + sd_bus_error_set_errnofv() is similar to + sd_bus_error_set_errnof(), but takes the + format string parameters as va_arg3 + parameter list. + + sd_bus_error_get_errno() converts the + name field of an error structure to an + errno-like (positive) value using the same + rules as sd_bus_error_set(). If + e is NULL, 0 will be + returned. + + sd_bus_error_copy() will initialize + dst using the values in + e. If the strings in + e were set using + sd_bus_set_error_const(), they will be shared. + Otherwise, they will be copied. Returns a converted + errno-like, negative error code. + + sd_bus_error_is_set() will return a + non-zero value if e is + non-NULL and an error has been set, + false otherwise. + + sd_bus_error_has_name() will return a + non-zero value if e is + non-NULL and an error with the same + name has been set, + false otherwise. + + sd_bus_error_free() will destroy + resources held by e. The parameter itself + will not be deallocated, and must be free3d + by the caller if necessary. The function may also be called safely + on unset errors (error structures with both fields set to NULL), + in which case it performs no operation. This call will reset the + error structure after freeing the data, so that all fields are set + to NULL. The structure may be reused afterwards. + + + + Return Value + + The functions sd_bus_error_set(), + sd_bus_error_setf(), and + sd_bus_error_set_const(), when successful, + return the negative errno value corresponding to the + name parameter. The functions + sd_bus_error_set_errno(), + sd_bus_error_set_errnof() and + sd_bus_error_set_errnofv(), when successful, + return the negative value of the error + parameter. If an error occurs, one of the negative error values + listed below will be returned. + + sd_bus_error_get_errno() returns + false when e is + NULL, and a positive errno value mapped from + e->name otherwise. + + sd_bus_error_copy() returns 0 or a + positive integer on success, and a negative error value converted + from the error name otherwise. + + sd_bus_error_is_set() returns a + non-zero value when e and the + name field are + non-NULL, zero otherwise. + + sd_bus_error_has_name() returns a + non-zero value when e is + non-NULL and the + name field is equal to + name, zero otherwise. + + + + Reference ownership + sd_bus_error is not reference + counted. Users should destroy resources held by it by calling + sd_bus_error_free(). Usually, error structures + are allocated on the stack or passed in as function parameters, + but they may also be allocated dynamically, in which case it is + the duty of the caller to free3 + the memory held by the structure itself after freeing its contents + with sd_bus_error_free(). + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + Error was already set in + sd_bus_error structure when one the + error-setting functions was called. + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + sd_bus_set_error() and other functions + described here are available as a shared library, which can be + compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd-bus-errors3, + sd_bus_error_add_map3, + errno3, + strerror_r3 + + + + diff --git a/src/libsystemd/sd_bus_error_add_map.xml b/src/libsystemd/sd_bus_error_add_map.xml new file mode 100644 index 0000000000..7dc1ef6c90 --- /dev/null +++ b/src/libsystemd/sd_bus_error_add_map.xml @@ -0,0 +1,173 @@ + + + + + + + + + sd_bus_error_add_map + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_bus_error_add_map + 3 + + + + sd_bus_error_add_map + sd_bus_error_map + SD_BUS_ERROR_MAP + SD_BUS_ERROR_END + + Additional sd-dbus error mappings + + + + + #include <systemd/sd-bus.h> + + typedef struct { + const char *name; + int code; + ... +} sd_bus_error_map; + + + + + SD_BUS_ERROR_MAP(name, code) + + + SD_BUS_ERROR_MAP_END + + + + int sd_bus_error_add_map + const sd_bus_map *map + + + + + + Description + + The sd_bus_error_add_map() call may be + used to register additional mappings for converting D-Bus errors + to GNU/Linux errno-style errors. The mappings + defined with this call are consulted by calls such as + sd_bus_error_set3 + or + sd_bus_error_get_errno3. By + default, a number of generic, standardized mappings are known, as + documented in + sd-bus-errors3. Use + this call to add further, application-specific mappings. + + The function takes a pointer to an array of + sd_bus_error_map structures. A reference + to the specified array is added to the lookup tables for error + mappings. Note that the structure is not copied, and that it is hence + essential that the array stays available and constant during the + entire remaining runtime of the process. + + The mapping array should be put together with a series of + SD_BUS_ERROR_MAP() macro invocations that + take a literal name string and a (positive) + errno-style error number. The last entry of the + array should be an invocation of the + SD_BUS_ERROR_MAP_END macro. The array should not be + put together without use of these two macros. + + Note that the call is idempotent: it is safe to invoke it + multiple times with the parameter, which will only add the passed + mapping array once. + + Note that the memory allocated by this call is not intended + to be freed during the lifetime of the process. It should not be + freed explicitly. + + + + Return Value + + sd_bus_error_add_map() returns a + positive value when the new array was added to the lookup + tables. It returns zero when the same array was already added + before. On error, a negative errno-style error + code is returned. See below for known error codes. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + The specified mapping array is invalid. + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + The various error definitions described here are available + as a shared library, which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_error3, + sd-bus-errors3, + errno3, + strerror_r3 + + + + diff --git a/src/libsystemd/sd_bus_message_append.xml b/src/libsystemd/sd_bus_message_append.xml new file mode 100644 index 0000000000..77fce02eae --- /dev/null +++ b/src/libsystemd/sd_bus_message_append.xml @@ -0,0 +1,264 @@ + + + + + + + + + sd_bus_message_append + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_message_append + 3 + + + + sd_bus_message_append + + Attach fields to a D-Bus message based on a type + string + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_append + sd_bus_message *m + const char *types + ... + + + + + + Description + + The sd_bus_message_append() function + appends a sequence of fields to the D-Bus message object + m. The type string + types describes the types of the field + arguments that follow. For each type specified in the type string, + one or more arguments need to be specified, in the same order as + declared in the type string. + + The type string is composed of the elements shown in the + table below. It contains zero or more single "complete types". + Each complete type may be one of the basic types or a fully + described container type. A container type may be a structure with + the contained types, a variant, an array with its element type, or + a dictionary entry with the contained types. The type string is + NUL-terminated. + + In case of a basic type, one argument of the corresponding + type is expected. + + A structure is denoted by a sequence of complete types + between ( and ). This + sequence cannot be empty — it must contain at least one type. + Arguments corresponding to this nested sequence follow the same + rules as if they were not nested. + + A variant is denoted by v. Corresponding + arguments must begin with a type string denoting a complete type, + and following that, arguments corresponding to the specified type. + + + An array is denoted by a followed by a + complete type. Corresponding arguments must begin with the number of + entries in the array, followed by the entries themselves, + matching the element type of the array. + + A dictionary is an array of dictionary entries, denoted by + a followed by a pair of complete types between + { and }. The first of those + types must be a basic type. Corresponding arguments must begin + with the number of dictionary entries, followed by a pair of + values for each entry matching the element type of + the dictionary entries. + + For further details on the D-Bus type system, please consult + the D-Bus + Specification. + + + Item type specifiers + + + + + + + + + + a + SD_BUS_TYPE_ARRAY + array + determined by array type and size + int, followed by array contents + + + + v + SD_BUS_TYPE_VARIANT + variant + determined by the type argument + signature string, followed by variant contents + + + + ( + SD_BUS_TYPE_STRUCT_BEGIN + array start + determined by the nested types + structure contents + + + ) + SD_BUS_TYPE_STRUCT_END + array end + + + + { + SD_BUS_TYPE_DICT_ENTRY_BEGIN + dictionary entry start + determined by the nested types + dictionary contents + + + } + SD_BUS_TYPE_DICT_ENTRY_END + dictionary entry end + + + +
+ + + + + Types String Grammar + + types ::= complete_type* +complete_type ::= basic_type | variant | structure | array | dictionary +basic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" | + "b" | "h" | + "s" | "o" | "g" +variant ::= "v" +structure ::= "(" complete_type+ ")" +array ::= "a" complete_type +dictionary ::= "a" "{" basic_type complete_type "}" + + + + + Examples + + Append a single basic type (the string a string): + + + sd_bus_message *m; +... +sd_bus_message_append(m, "s", "a string"); + + Append all types of integers: + + uint8_t y = 1; +int16_t n = 2; +uint16_t q = 3; +int32_t i = 4; +uint32_t u = 5; +int32_t x = 6; +uint32_t t = 7; +double d = 8.0; +sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d); + + Append a structure composed of a string and a D-Bus path: + + sd_bus_message_append(m, "(so)", "a string", "/a/path"); + + + Append an array of UNIX file descriptors: + + sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO); + + + Append a variant, with the real type "g" (signature), + and value "sdbusisgood": + + sd_bus_message_append(m, "v", "g", "sdbusisgood"); + + Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}: + + + sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL); + + + + + Return Value + + On success, this call returns 0 or a positive + integer. On failure, this call returns a negative + errno-style error code. + + + + + + Notes + + sd_bus_open_user() and other functions + described here are available as a shared library, which can be + compiled and linked to with the + libsystemd-bus pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append_basic3, + sd_bus_message_append_array3 + + + + diff --git a/src/libsystemd/sd_bus_message_append_array.xml b/src/libsystemd/sd_bus_message_append_array.xml new file mode 100644 index 0000000000..27db2a96c3 --- /dev/null +++ b/src/libsystemd/sd_bus_message_append_array.xml @@ -0,0 +1,213 @@ + + + + + + + + + sd_bus_message_append_array + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_message_append_array + 3 + + + + sd_bus_message_append_array + sd_bus_message_append_array_memfd + sd_bus_message_append_array_iovec + sd_bus_message_append_array_space + + Append an array of fields to a D-Bus + message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_append_array + sd_bus_message *m + char type + char void *ptr + size_t size + + + + int sd_bus_message_append_array_memfd + sd_bus_message *m + char type + int memfd + uint64_t offset + uint64_t size + + + + int sd_bus_message_append_array_iovec + sd_bus_message *m + char type + const struct iovec *iov + unsigned n + + + + int sd_bus_message_append_array_space + char type + size_t size + void **ptr + + + + + + Description + + The sd_bus_message_append_array() + function appends an array to a D-Bus message + m. A container will be opened, the array + contents appended, and the container closed. The parameter + type determines how the pointer + p is interpreted. + type must be one of the "trivial" types + y, n, q, + i, u, x, + t, d (but not + b), as defined by the Basic + Types section of the D-Bus specification, and listed in + sd_bus_message_append_basic3. + Pointer p must point to an array of size + size bytes containing items of the + respective type. Size size must be a + multiple of the size of the type type. As a + special case, p may be + NULL, if size is 0. + The memory pointed to by p is copied into + the memory area containing the message and stays in possession of + the caller. The caller may hence freely change the data after this + call without affecting the message the array was appended + to. + + The sd_bus_message_append_array_memfd() + function appends an array of a trivial type to message + m, similar to + sd_bus_message_append_array(). The contents + of the memory file descriptor memfd + starting at the specified offset and of the specified size is + used as the contents of the array. The offset and size must be a + multiple of the size of the type + type. However, as a special exception, if + the offset is specified as zero and the size specified as + UINT64_MAX the full memory file descriptor contents is used. The + memory file descriptor is sealed by this call if it has not been + sealed yet, and cannot be modified after this call. See + memfd_create2 + for details about memory file descriptors. Appending arrays with + memory file descriptors enables efficient zero-copy data transfer, + as the memory file descriptor may be passed as-is to the + destination, without copying the memory in it to the destination + process. Not all protocol transports support passing memory file + descriptors between participants, in which case this call will + automatically fall back to copying. Also, as memory file + descriptor passing is inefficient for smaller amounts of data, + copying might still be enforced even where memory file descriptor + passing is supported. + + The sd_bus_message_append_array_iovec() + function appends an array of a trivial type to the message + m, similar to + sd_bus_message_append_array(). Contents of + the I/O vector array iov are used as the + contents of the array. The total size of + iov payload (the sum of + iov_len fields) must be a multiple of + the size of the type type. The + iov argument must point to + n I/O vector structures. Each structure may + have the iov_base field set, in which + case the memory pointed to will be copied into the message, or + unset (set to zero), in which case a block of zeros of length + iov_len bytes will be inserted. The + memory pointed at by iov may be changed + after this call. + + The sd_bus_message_append_array_space() + function appends space for an array of a trivial type to message + m. It behaves the same as + sd_bus_message_append_array(), but instead of + copying items to the message, it returns a pointer to the + destination area to the caller in pointer + p. The caller should subsequently write the + array contents to this memory. Modifications to the memory + pointed to should only occur until the next operation on the bus + message is invoked. Most importantly, the memory should not be + altered anymore when another field has been added to the message + or the message has been sealed. + + + + Return Value + + On success, these calls return 0 or a positive integer. On + failure, they return a negative errno-style error code. + + + + + + Notes + + sd_bus_append_array() and other + functions described here are available as a shared library, which + can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append3, + sd_bus_message_append_basic3, + memfd_create2, + The D-Bus specification + + + + diff --git a/src/libsystemd/sd_bus_message_append_basic.xml b/src/libsystemd/sd_bus_message_append_basic.xml new file mode 100644 index 0000000000..276953af69 --- /dev/null +++ b/src/libsystemd/sd_bus_message_append_basic.xml @@ -0,0 +1,295 @@ + + + + + + + + + sd_bus_message_append_basic + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_message_append_basic + 3 + + + + sd_bus_message_append_basic + + Attach a single field to a message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_append_basic + sd_bus_message *m + char type + const void *p + + + + + + Description + + sd_bus_message_append_basic() appends a + single field to the message m. The + parameter type determines how the pointer + p is interpreted. + type must be one of the basic types as + defined by the Basic + Types section of the D-Bus specification, and listed in + the table below. + + + + Item type specifiers + + + + + + + + + + Specifier + Constant + Description + Size + Expected C Type + + + + + y + SD_BUS_TYPE_BYTE + unsigned integer + 1 byte + uint8_t + + + + b + SD_BUS_TYPE_BOOLEAN + boolean + 4 bytes + int + + + + n + SD_BUS_TYPE_INT16 + signed integer + 2 bytes + int16_t + + + + q + SD_BUS_TYPE_UINT16 + unsigned integer + 2 bytes + uint16_t + + + + i + SD_BUS_TYPE_INT32 + signed integer + 4 bytes + int32_t + + + + u + SD_BUS_TYPE_UINT32 + unsigned integer + 4 bytes + uint32_t + + + + x + SD_BUS_TYPE_INT64 + signed integer + 8 bytes + int64_t + + + + t + SD_BUS_TYPE_UINT64 + unsigned integer + 8 bytes + uint64_t + + + + d + SD_BUS_TYPE_DOUBLE + floating-point + 8 bytes + double + + + + s + SD_BUS_TYPE_STRING + Unicode string + variable + char[] + + + + o + SD_BUS_TYPE_OBJECT_PATH + object path + variable + char[] + + + + g + SD_BUS_TYPE_SIGNATURE + signature + variable + char[] + + + + h + SD_BUS_TYPE_UNIX_FD + UNIX file descriptor + 4 bytes + int + + + +
+ + The value of the parameter is copied into a memory area held + by the message object, stays in the possession of the caller and + may hence be freely changed after this call without affecting the + bus message it has been added to. If type + is h (UNIX file descriptor), the descriptor is + duplicated by this call and the passed descriptor stays in + possession of the caller. + + For types s, o, and + g, the parameter p is + interpreted as a pointer to a NUL-terminated + character sequence. As a special case, a NULL + pointer is interpreted as an empty string. The string should be + valid Unicode string encoded as UTF-8. In case of the two latter + types, the additional requirements for a D-Bus object path or + type signature should be satisfied. Those requirements should be + verified by the recipient of the message. + + + + + Return Value + + On success, this call returns 0 or a positive integer. On + failure, it returns a negative errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + Specified parameter is invalid. + + + + + -EPERM + + Message has been sealed. + + + + + -ESTALE + + Message is in invalid state. + + + + + -ENXIO + + Message cannot be appended to. + + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + The sd_bus_append_basic() function + described here is available as a shared library, which can be + compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append3, + The D-Bus specification + + + + diff --git a/src/libsystemd/sd_bus_message_append_string_memfd.xml b/src/libsystemd/sd_bus_message_append_string_memfd.xml new file mode 100644 index 0000000000..9e99999bf3 --- /dev/null +++ b/src/libsystemd/sd_bus_message_append_string_memfd.xml @@ -0,0 +1,153 @@ + + + + + + + + + sd_bus_message_append_string_memfd + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_message_append_string_memfd + 3 + + + + sd_bus_message_append_string_memfd + sd_bus_message_append_string_iovec + sd_bus_message_append_string_space + + Attach a string to a message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_append_string_memfd + sd_bus_message *m + int memfd + + + + int sd_bus_message_append_string_iovec + sd_bus_message *m + const struct iovec *iov + unsigned n + + + + int sd_bus_message_append_string_space + sd_bus_message *m + size_t size + char **s + + + + + + Description + + The functions + sd_bus_message_append_string_memfd and + sd_bus_message_append_string_iovec can be + used to append a single string (item of type s) + to message m. + + In case of + sd_bus_message_append_string_memfd, the + contents of memfd are the string. They must + satisfy the same constraints as described for the + s type in + sd_bus_message_append_basic3. + + In case of + sd_bus_message_append_string_iovec, the + payload of iov is the string. It must + satisfy the same constraints as described for the + s type in + sd_bus_message_append_basic3. + + The iov argument must point to + n struct iovec + structures. Each structure may have the + iov_base field set, in which case the + memory pointed to will be copied into the message, or unset, in + which case a block of spaces (ASCII 32) of length + iov_len will be inserted. The + memory pointed at by iov may be changed + after this call. + + The + sd_bus_message_append_string_space function appends + space for a string to message m. It behaves + similar to sd_bus_message_append_basic with + type s, but instead of copying a string into + the message, it returns a pointer to the destination area to + the caller in pointer p. Space for the string + of length size plus the terminating + NUL is allocated. + + + + Return Value + + On success, those calls return 0 or a positive integer. On + failure, they returns a negative errno-style error code. + + + + + + Notes + + The functions described here are available as a shared library, + which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append_basic3, + The D-Bus specification + + + + diff --git a/src/libsystemd/sd_bus_message_append_strv.xml b/src/libsystemd/sd_bus_message_append_strv.xml new file mode 100644 index 0000000000..0f77adcc8b --- /dev/null +++ b/src/libsystemd/sd_bus_message_append_strv.xml @@ -0,0 +1,116 @@ + + + + + + + + + sd_bus_message_append_strv + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_message_append_strv + 3 + + + + sd_bus_message_append_strv + + Attach an array of strings to a message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_append_strv + sd_bus_message *m + char **l + + + + + + Description + + The sd_bus_message_append function can be + used to append an array of strings to message + m. The parameter l + shall point to a NULL-terminated array of pointers + to NUL-terminated strings. Each string must + satisfy the same constraints as described for the + s type in + sd_bus_message_append_basic3. + + + The memory pointed at by p and the + contents of the strings themselves are copied into the memory area + containing the message and may be changed after this call. Note + that the signature of l parameter is to be + treated as const char *const *, and the contents + will not be modified. + + + + Return Value + + On success, this call returns 0 or a positive integer. On + failure, a negative errno-style error code is returned. + + + + + + Notes + + The sd_bus_append_append_strv() function + described here is available as a shared library, which can be + compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append3, + sd_bus_message_append_array3, + The D-Bus specification + + + + diff --git a/src/libsystemd/sd_bus_message_get_cookie.xml b/src/libsystemd/sd_bus_message_get_cookie.xml new file mode 100644 index 0000000000..3328eead3d --- /dev/null +++ b/src/libsystemd/sd_bus_message_get_cookie.xml @@ -0,0 +1,146 @@ + + + + + + + + + sd_bus_message_get_cookie + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_bus_message_get_cookie + 3 + + + + sd_bus_message_get_cookie + sd_bus_message_get_reply_cookie + Returns the transaction cookie of a message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_get_cookie + sd_bus_message *message + uint64_t *cookie + + + + int sd_bus_message_get_reply_cookie + sd_bus_message *message + uint64_t *cookie + + + + + + Description + + sd_bus_message_get_cookie() returns the + transaction cookie of a message. The cookie uniquely identifies a + message within each bus peer, but is not globally unique. It is + assigned when a message is sent. + + sd_bus_message_get_reply_cookie() + returns the transaction cookie of the message the specified + message is a response to. When a reply message is generated for a + method call message, its cookie is copied over into this field. + Note that while every message that is transferred is identified by + a cookie, only response messages carry a reply cookie + field. + + Both functions take a message object as first parameter and + a place to store the 64-bit cookie in. + + + + Return Value + + On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error + code. + + On success, the cookie/reply cookie is returned in the + specified 64-bit unsigned integer variable. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + A specified parameter + is invalid. + + + + -ENODATA + + No cookie has been assigned to this message. + This either indicates that the message has not been sent yet + and hence has no cookie assigned, or that the message is not a + method response message and hence carries a reply cookie + field. + + + + + + Notes + + The sd_bus_message_get_cookie() and + sd_bus_message_get_reply_cookie() interfaces + are available as a shared library, which can be compiled and + linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_new3 + + + + diff --git a/src/libsystemd/sd_bus_message_get_monotonic_usec.xml b/src/libsystemd/sd_bus_message_get_monotonic_usec.xml new file mode 100644 index 0000000000..2c0a8a5d54 --- /dev/null +++ b/src/libsystemd/sd_bus_message_get_monotonic_usec.xml @@ -0,0 +1,181 @@ + + + + + + + + + sd_bus_message_get_monotonic_usec + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_bus_message_get_monotonic_usec + 3 + + + + sd_bus_message_get_monotonic_usec + sd_bus_message_get_realtime_usec + sd_bus_message_get_seqnum + Retrieve the sender timestamps and sequence number of a message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_get_monotonic_usec + sd_bus_message *message + uint64_t *usec + + + + int sd_bus_message_get_realtime_usec + sd_bus_message *message + uint64_t *usec + + + + int sd_bus_message_get_seqnum + sd_bus_message *message + uint64_t *seqnum + + + + + + Description + + sd_bus_message_get_monotonic_usec() + returns the monotonic timestamp of the time the message was sent. + This value is in microseconds since the + CLOCK_MONOTONIC epoch, see + clock_gettime2 + for details. + + Similarly, + sd_bus_message_get_realtime_usec() returns + the realtime (wallclock) timestamp of the time the message was + sent. This value is in microseconds since Jan 1st, 1970, i.e. in + the CLOCK_REALTIME clock. + + sd_bus_message_get_seqnum() returns the + kernel-assigned sequence number of the message. The kernel assigns + a global, monotonically increasing sequence number to all messages + transmitted on the local system, at the time the message was sent. + This sequence number is useful for determining message send order, + even across different buses of the local system. The sequence + number combined with the boot ID of the system (as returned by + sd_id128_get_boot3) + is a suitable globally unique identifier for bus messages. + + Note that the sending order and receiving order of messages + might differ, in particular for broadcast messages. This means + that the sequence number and the timestamps of messages a client + reads are not necessarily monotonically increasing. + + These timestamps and the sequence number are attached to + each message by the kernel and cannot be manipulated by the + sender. + + Note that these timestamps are only available on some bus + transports, and only after support for them has been negotiated + with the + sd_bus_negotiate_timestamp3 + call. + + + + Return Value + + On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error + code. + + On success, the timestamp or sequence number is returned in + the specified 64-bit unsigned integer variable. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + A specified parameter is + invalid. + + + + -ENODATA + + No timestamp or sequence number information is + attached to the passed message. This error is returned if the + underlying transport does not support timestamping or + assigning of sequence numbers, or if this feature has not been + negotiated with + sd_bus_negotiate_timestamp3. + + + + + + Notes + + The + sd_bus_message_get_monotonic_usec(), + sd_bus_message_get_realtime_usec(), and + sd_bus_message_get_seqnum() interfaces are + available as a shared library, which can be compiled and linked to + with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_new3, + sd_bus_negotiate_timestamp3, + clock_gettime2, + sd_id128_get_boot3 + + + + diff --git a/src/libsystemd/sd_bus_negotiate_fds.xml b/src/libsystemd/sd_bus_negotiate_fds.xml new file mode 100644 index 0000000000..a538b13cf0 --- /dev/null +++ b/src/libsystemd/sd_bus_negotiate_fds.xml @@ -0,0 +1,200 @@ + + + + + + + + + sd_bus_negotiate_fds + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_bus_negotiate_fds + 3 + + + + sd_bus_negotiate_fds + sd_bus_negotiate_timestamp + sd_bus_negotiate_creds + + Control feature negotiation on bus connections + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_negotiate_fds + sd_bus *bus + int b + + + + int sd_bus_negotiate_timestamp + sd_bus *bus + int b + + + + int sd_bus_negotiate_creds + sd_bus *bus + int b + uint64_t mask + + + + + + Description + + sd_bus_negotiate_fds() controls whether + file descriptor passing shall be negotiated for the specified bus + connection. It takes a bus object and a boolean, which, when true, + enables file descriptor passing, and, when false, disables + it. Note that not all transports and servers support file + descriptor passing. In particular, networked transports generally + do not support file descriptor passing. To find out whether file + descriptor passing is available after negotiation, use + sd_bus_can_send3 + and pass SD_BUS_TYPE_UNIX_FD. Note that file + descriptor passing is always enabled for both sending and + receiving or for neither, but never only in one direction. By + default, file descriptor passing is negotiated for all + connections. + + Note that when bus activation is used, it is highly + recommended to set the + setting in the .busname unit file to the same + setting as negotiated by the program ultimately activated. By + default, file descriptor passing is enabled for both. + + sd_bus_negotiate_timestamps() controls + whether implicit sender timestamps shall be attached automatically + to all incoming messages. Takes a bus object and a boolean, which, + when true, enables timestamping, and, when false, disables it. + Use + sd_bus_message_get_monotonic_usec3, + sd_bus_message_get_realtime_usec3, + sd_bus_message_get_seqnum3 + to query the timestamps of incoming messages. If negotiation is + disabled or not supported, these calls will fail with + -ENODATA. Note that not all transports + support timestamping of messages. Specifically, timestamping is + only available on the kdbus transport, but not on dbus1. The + timestamping is applied by the kernel and cannot be manipulated by + userspace. By default, message timestamping is not negotiated for + connections. + + sd_bus_negotiate_creds() controls + whether and which implicit sender credentials shall be attached + automatically to all incoming messages. Takes a bus object and a + boolean indicating whether to enable or disable the credential + parts encoded in the bit mask value argument. Note that not all + transports support attaching sender credentials to messages, or do + not support all types of sender credential parameters, or might + suppress them under certain circumstances for individual + messages. Specifically, implicit sender credentials on messages + are only fully supported on kdbus transports, and dbus1 only + supports SD_BUS_CREDS_UNIQUE_NAME. The sender + credentials are attached by the kernel and cannot be manipulated + by userspace, and are thus suitable for authorization + decisions. By default, only + SD_BUS_CREDS_WELL_KNOWN_NAMES and + SD_BUS_CREDS_UNIQUE_NAME are enabled. In + fact, these two credential fields are always sent along and cannot + be turned off. + + The sd_bus_negotiate_fds() function may + be called only before the connection has been started with + sd_bus_start3. Both + sd_bus_negotiate_timestamp() and + sd_bus_negotiate_creds() may also be called + after a connection has been set up. Note that, when operating on a + connection that is shared between multiple components of the same + program (for example via + sd_bus_default3), + it is highly recommended to only enable additional per message + metadata fields, but never disable them again, in order not to + disable functionality needed by other components. + + + + Return Value + + On success, these functions return 0 or a + positive integer. On failure, they return a negative errno-style + error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EPERM + + The bus connection has already been started. + + + + + + Notes + + sd_bus_negotiate_fds() and the other + functions described here are available as a shared library, which + can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_start3, + sd_bus_message_can_send3, + sd_bus_message_get_monotonic_usec3, + sd_bus_message_get_realtime_usec3, + sd_bus_message_get_seqnum3, + sd_bus_message_get_creds3, + systemd.busname5 + + + + diff --git a/src/libsystemd/sd_bus_new.xml b/src/libsystemd/sd_bus_new.xml new file mode 100644 index 0000000000..d281b5dd44 --- /dev/null +++ b/src/libsystemd/sd_bus_new.xml @@ -0,0 +1,189 @@ + + + + + + + + + sd_bus_new + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_new + 3 + + + + sd_bus_new + sd_bus_ref + sd_bus_unref + sd_bus_unrefp + + Create a new bus object and create or destroy references to it + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_new + sd_bus **bus + + + + sd_bus *sd_bus_ref + sd_bus *bus + + + + sd_bus *sd_bus_unref + sd_bus *bus + + + + void sd_bus_unrefp + sd_bus **bus + + + + + + Description + + sd_bus_new() creates a new bus + object. This object is reference-counted, and will be destroyed + when all references are gone. Initially, the caller of this + function owns the sole reference and the bus object will not be + connected to any bus. To connect it to a bus, make sure + to set an address with + sd_bus_set_address3 + or a related call, and then start the connection with + sd_bus_start3. + + In most cases, it is a better idea to invoke + sd_bus_default_user3, + sd_bus_default_system3 + or related calls instead of the more low-level + sd_bus_new() and + sd_bus_start(). The higher-level calls not + only allocate a bus object but also start the connection to a + well-known bus in a single function invocation. + + sd_bus_ref() increases the reference + counter of bus by one. + + sd_bus_unref() decreases the reference + counter of bus by one. Once the reference + count has dropped to zero, bus is destroyed + and cannot be used anymore, so further calls to + sd_bus_ref() or + sd_bus_unref() are illegal. + + sd_bus_unrefp() is similar to + sd_bus_unref() but takes a pointer to a + pointer to an sd_bus object. This call is useful in + conjunction with GCC's and LLVM's Clean-up + Variable Attribute. Note that this function is defined as + inline function. Use a declaration like the following, in order to + allocate a bus object that is freed automatically as the code + block is left: + + { + __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL; + int r; + … + r = sd_bus_default(&bus); + if (r < 0) + fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r)); + … +} + + sd_bus_ref(), + sd_bus_unref() and + sd_bus_unrefp() execute no operation if the + passed in bus object is NULL. + + + + Return Value + + On success, sd_bus_new() returns 0 or a + positive integer. On failure, it returns a negative errno-style + error code. + + sd_bus_ref() always returns the argument. + + + sd_bus_unref() always returns + NULL. + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + sd_bus_new() and other functions + described here are available as a shared library, which can be + compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_default_user3, + sd_bus_default_system3, + sd_bus_open_user3, + sd_bus_open_system3 + + + + diff --git a/src/libsystemd/sd_bus_path_encode.xml b/src/libsystemd/sd_bus_path_encode.xml new file mode 100644 index 0000000000..3088243e45 --- /dev/null +++ b/src/libsystemd/sd_bus_path_encode.xml @@ -0,0 +1,188 @@ + + + + + + + + + sd_bus_path_encode + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_path_encode + 3 + + + + sd_bus_path_encode + sd_bus_path_encode_many + sd_bus_path_decode + sd_bus_path_decode_many + + Convert an external identifier into an object path and back + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_path_encode + const char *prefix + const char *external_id + char **ret_path + + + + int sd_bus_path_encode_many + char **out + const char *path_template + ... + + + + int sd_bus_path_decode + const char *path + const char *prefix + char **ret_external_id + + + + int sd_bus_path_decode_many + const char *path + const char *path_template + ... + + + + + + Description + + sd_bus_path_encode() and + sd_bus_path_decode() convert external + identifier strings into object paths and back. These functions are + useful to map application-specific string identifiers of any kind + into bus object paths in a simple, reversible and safe way. + + sd_bus_path_encode() takes a bus path + prefix and an external identifier string as arguments, plus a + place to store the returned bus path string. The bus path prefix + must be a valid bus path, starting with a slash + /, and not ending in one. The external + identifier string may be in any format, may be the empty string, + and has no restrictions on the charset — however, it must + always be NUL-terminated. The returned string + will be the concatenation of the bus path prefix plus an escaped + version of the external identifier string. This operation may be + reversed with sd_bus_decode(). It is + recommended to only use external identifiers that generally + require little escaping to be turned into valid bus path + identifiers (for example, by sticking to a 7-bit ASCII character + set), in order to ensure the resulting bus path is still short and + easily processed. + + sd_bus_path_decode() reverses the + operation of sd_bus_path_encode() and thus + regenerates an external identifier string from a bus path. It + takes a bus path and a prefix string, plus a place to store the + returned external identifier string. If the bus path does not + start with the specified prefix, 0 is returned and the returned + string is set to NULL. Otherwise, the + string following the prefix is unescaped and returned in the + external identifier string. + + The escaping used will replace all characters which are + invalid in a bus object path by _, followed by a + hexadecimal value. As a special case, the empty string will be + replaced by a lone _. + + sd_bus_path_encode_many() works like + its counterpart sd_bus_path_encode(), but + takes a path template as argument and encodes multiple labels + according to its embedded directives. For each + % character found in the template, the caller + must provide a string via varargs, which will be encoded and + embedded at the position of the % character. + Any other character in the template is copied verbatim into the + encoded path. + + sd_bus_path_decode_many() does the + reverse of sd_bus_path_encode_many(). It + decodes the passed object path according to the given + path template. For each % character in the + template, the caller must provide an output storage + (char **) via varargs. The decoded label + will be stored there. Each % character will + only match the current label. It will never match across labels. + Furthermore, only a single directive is allowed per label. + If NULL is passed as output storage, the + label is verified but not returned to the caller. + + + + Return Value + + On success, sd_bus_path_encode() + returns positive or 0, and a valid bus path in the return + argument. On success, sd_bus_path_decode() + returns a positive value if the prefixed matched, or 0 if it + did not. If the prefix matched, the external identifier is returned + in the return parameter. If it did not match, NULL is returned in + the return parameter. On failure, a negative errno-style error + number is returned by either function. The returned strings must + be + free3'd + by the caller. + + + + Notes + + sd_bus_path_encode() and + sd_bus_path_decode() are available as a + shared library, which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + free3 + + + + diff --git a/src/libsystemd/sd_bus_request_name.xml b/src/libsystemd/sd_bus_request_name.xml new file mode 100644 index 0000000000..f07ae09555 --- /dev/null +++ b/src/libsystemd/sd_bus_request_name.xml @@ -0,0 +1,213 @@ + + + + + + + + + sd_bus_request_name + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_bus_request_name + 3 + + + + sd_bus_request_name + sd_bus_release_name + Request or release a well-known service name on a bus + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_request_name + sd_bus *bus + const char *name + uint64_t flags + + + + int sd_bus_release_name + sd_bus *bus + const char *name + + + + + + Description + + sd_bus_request_name() requests a + well-known service name on a bus. It takes a bus connection, a + valid bus name and a flags parameter. The flags parameter is a + combination of the following flags: + + + + SD_BUS_NAME_ALLOW_REPLACEMENT + + After acquiring the name successfully, permit + other peers to take over the name when they try to acquire it + with the SD_BUS_NAME_REPLACE_EXISTING flag + set. If SD_BUS_NAME_ALLOW_REPLACEMENT is + not set on the original request, such a request by other peers + will be denied. + + + + SD_BUS_NAME_REPLACE_EXISTING + + Take over the name if it is already acquired + by another peer, and that other peer has permitted takeover by + setting SD_BUS_NAME_ALLOW_REPLACEMENT while + acquiring it. + + + + SD_BUS_NAME_QUEUE + + Queue the acquisition of the name when the + name is already taken. + + + + sd_bus_release_name() releases an + acquired well-known name. It takes a bus connection and a valid + bus name as parameters. + + + + Return Value + + On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error + code. + + If SD_BUS_NAME_QUEUE is specified, + sd_bus_request_name() will return 0 when the + name is already taken by another peer and the client has been + added to the queue for the name. In that case, the caller can + subscribe to NameOwnerChanged signals to be + notified when the name is successfully acquired. + sd_bus_request_name() returns > 0 when the + name has immediately been acquired successfully. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EALREADY + + The caller already is the owner of the + specified name. + + + + -EEXIST + + The name has already been acquired by a + different peer, and SD_BUS_NAME_REPLACE_EXISTING was not + specified or the other peer did not specify + SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring the + name. + + + + -ESRCH + + It was attempted to release a name that is + currently not registered on the bus. + + + + -EADDRINUSE + + It was attempted to release a name that is + owned by a different peer on the bus. + + + + -EINVAL + + A specified parameter is invalid. This is also + generated when the requested name is a special service name + reserved by the D-Bus specification, or when the operation is + requested on a connection that does not refer to a + bus. + + + + -ENOTCONN + + The bus connection has been + disconnected. + + + + -ECHILD + + The bus connection has been created in a + different process than the current one. + + + + + + Notes + + The sd_bus_acquire_name() and + sd_bus_release_name() interfaces are + available as a shared library, which can be compiled and linked to + with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_new3 + + + + diff --git a/src/libsystemd/sd_event_add_child.xml b/src/libsystemd/sd_event_add_child.xml new file mode 100644 index 0000000000..bc732db7fa --- /dev/null +++ b/src/libsystemd/sd_event_add_child.xml @@ -0,0 +1,246 @@ + + + + + + + + + sd_event_add_child + systemd + + + + More text + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_event_add_child + 3 + + + + sd_event_add_child + sd_event_source_get_child_pid + sd_event_child_handler_t + + Add a child process state change event source to an event loop + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_child_handler_t) + sd_event_source *s + const siginfo_t *si + void *userdata + + + + int sd_event_add_child + sd_event *event + sd_event_source **source + pid_t pid + int options + sd_event_child_handler_t handler + void *userdata + + + + int sd_event_source_get_child_pid + sd_event_source *source + pid_t *pid + + + + + + + Description + + sd_event_add_child() adds a new child + process state change event source to an event loop. The event loop + object is specified in the event parameter, + the event source object is returned in the + source parameter. The + pid parameter specifies the PID of the + process to watch. The handler must + reference a function to call when the process changes state. The + handler function will be passed the + userdata pointer, which may be chosen + freely by the caller. The handler also receives a pointer to a + siginfo_t structure containing + information about the child process event. The + options parameter determines which state + changes will be watched for. It must contain an OR-ed mask of + WEXITED (watch for the child process + terminating), WSTOPPED (watch for the child + process being stopped by a signal), and + WCONTINUED (watch for the child process being + resumed by a signal). See waitid2 + for further information. + + Only a single handler may be installed for a specific + child process. The handler is enabled for a single event + (SD_EVENT_ONESHOT), but this may be changed + with + sd_event_source_set_enabled3. + If the handler function returns a negative error code, it will be + disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. + + + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even when there's still a + reference to it kept, consider setting the event source to + SD_EVENT_OFF with + sd_event_source_set_enabled3. + + If the second parameter of + sd_event_add_child() is passed as NULL no + reference to the event source object is returned. In this case the + event source is considered "floating", and will be destroyed + implicitly when the event loop itself is destroyed. + + Note that the handler function is + invoked at a time where the child process is not reaped yet (and + thus still is exposed as a zombie process by the kernel). However, + the child will be reaped automatically after the function + returns. Child processes for which no child process state change + event sources are installed will not be reaped by the event loop + implementation. + + If both a child process state change event source and a + SIGCHLD signal event source is installed in + the same event loop, the configured event source priorities decide + which event source is dispatched first. If the signal handler is + processed first, it should leave the child processes for which + child process state change event sources are installed unreaped. + + sd_event_source_get_child_pid() + retrieves the configured PID of a child process state change event + source created previously with + sd_event_add_child(). It takes the event + source object as the source parameter and a + pointer to a pid_t variable to return the process ID + in. + + + + + Return Value + + On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate an object. + + + + -EINVAL + + An invalid argument has been passed. This includes + specifying an empty mask in options or a mask + which contains values different than a combination of + WEXITED, WSTOPPED, and + WCONTINUED. + + + + + + -EBUSY + + A handler is already installed for this + child process. + + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + -EDOM + + The passed event source is not a child process event source. + + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_now3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + waitid2 + + + + diff --git a/src/libsystemd/sd_event_add_defer.xml b/src/libsystemd/sd_event_add_defer.xml new file mode 100644 index 0000000000..d9ebd3b179 --- /dev/null +++ b/src/libsystemd/sd_event_add_defer.xml @@ -0,0 +1,216 @@ + + + + + + + + + sd_event_add_defer + systemd + + + + More text + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_event_add_defer + 3 + + + + sd_event_add_defer + sd_event_add_post + sd_event_add_exit + sd_event_handler_t + + Add static event sources to an event loop + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_handler_t) + sd_event_source *s + void *userdata + + + + int sd_event_add_defer + sd_event *event + sd_event_source **source + sd_event_handler_t handler + void *userdata + + + + int sd_event_add_post + sd_event *event + sd_event_source **source + sd_event_handler_t handler + void *userdata + + + + int sd_event_add_exit + sd_event *event + sd_event_source **source + sd_event_handler_t handler + void *userdata + + + + + + + Description + + These three functions add new static event sources to an + event loop. The event loop object is specified in the + event parameter, the event source object is + returned in the source parameter. The event + sources are enabled statically and will "fire" when the event loop + is run and the conditions described below are met. The handler + function will be passed the userdata + pointer, which may be chosen freely by the caller. + + sd_event_add_defer() adds a new event + source that will be dispatched instantly, before the event loop + goes to sleep again and waits for new events. By default, the + handler will be called once + (SD_EVENT_ONESHOT). Note that if the event + source is set to SD_EVENT_ON the event loop + will never go to sleep again, but continuously call the handler, + possibly interleaved with other event sources. + + sd_event_add_post() adds a new event + source that is run before the event loop will sleep and wait + for new events, but only after at least one other non-post event + source was dispatched. By default, the source is enabled + permanently (SD_EVENT_ON). Note that this + event source type will still allow the event loop to go to sleep + again, even if set to SD_EVENT_ON, as long as + no other event source is ever triggered. + + sd_event_add_exit() adds a new event + source that will be dispatched when the event loop is terminated + with sd_event_exit3. + + The + sd_event_source_set_enabled3 + function may be used to enable the event source permanently + (SD_EVENT_ON) or to make it fire just once + (SD_EVENT_ONESHOT). + + If the handler function returns a negative error code, it + will be disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. + + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even when there's still a + reference to it kept, consider setting the event source to + SD_EVENT_OFF with + sd_event_source_set_enabled3. + + If the second parameter of these functions is passed as + NULL no reference to the event source object is returned. In this + case the event source is considered "floating", and will be + destroyed implicitly when the event loop itself is + destroyed. + + + + Return Value + + On success, this functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate an object. + + + + -EINVAL + + An invalid argument has been passed. + + + + -ESTALE + + The event loop is already terminated. + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_now3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + sd_event_exit3 + + + + diff --git a/src/libsystemd/sd_event_add_io.xml b/src/libsystemd/sd_event_add_io.xml new file mode 100644 index 0000000000..c3749164cd --- /dev/null +++ b/src/libsystemd/sd_event_add_io.xml @@ -0,0 +1,300 @@ + + + + + + + + + sd_event_add_io + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_add_io + 3 + + + + sd_event_add_io + sd_event_source_get_io_events + sd_event_source_set_io_events + sd_event_source_get_io_revents + sd_event_source_get_io_fd + sd_event_source_set_io_fd + sd_event_source + sd_event_io_handler_t + + Add an I/O event source to an event loop + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_io_handler_t) + sd_event_source *s + int fd + uint32_t revents + void *userdata + + + + int sd_event_add_io + sd_event *event + sd_event_source **source + int fd + uint32_t events + sd_event_io_handler_t handler + void *userdata + + + + int sd_event_source_get_io_events + sd_event_source *source + uint32_t *events + + + + int sd_event_source_set_io_events + sd_event_source *source + uint32_t events + + + + int sd_event_source_get_io_revents + sd_event_source *source + uint32_t *revents + + + + int sd_event_source_get_io_fd + sd_event_source *source + + + + int sd_event_source_set_io_fd + sd_event_source *source + int fd + + + + + + + Description + + sd_event_add_io() adds a new I/O event + source to an event loop. The event loop object is specified in the + event parameter, the event source object is + returned in the source parameter. The + fd parameter takes the UNIX file descriptor + to watch, which may refer to a socket, a FIFO, a message queue, a + serial connection, a character device, or any other file descriptor + compatible with Linux + epoll7. The + events parameter takes a bit mask of events + to watch for, a combination of the following event flags: + EPOLLIN, EPOLLOUT, + EPOLLRDHUP, EPOLLPRI, + and EPOLLET, see + epoll_ctl2 + for details. The handler shall reference a + function to call when the event source is triggered. The + userdata pointer will be passed to the + handler function, and may be chosen freely by the caller. The + handler will also be passed the file descriptor the event was seen + on, as well as the actual event flags. It's generally a subset of + the events watched, however may additionally include + EPOLLERR and EPOLLHUP. + + + By default, an event source will stay enabled + continuously (SD_EVENT_ON), but this may be + changed with + sd_event_source_set_enabled3. + If the handler function returns a negative error code, it will be + disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. Note + that an event source set to SD_EVENT_ON will + fire continuously unless data is read from or written to the file + descriptor to reset the mask of events seen. + + + Setting the I/O event mask to watch for to 0 does not mean + that the event source won't be triggered anymore, as + EPOLLHUP and EPOLLERR + may be triggered even with a zero event mask. To temporarily + disable an I/O event source use + sd_event_source_set_enabled3 + with SD_EVENT_OFF instead. + + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even if it is still referenced, + disable the event source using + sd_event_source_set_enabled3 + with SD_EVENT_OFF. + + If the second parameter of + sd_event_add_io() is + NULL no reference to the event source object + is returned. In this case the event source is considered + "floating", and will be destroyed implicitly when the event loop + itself is destroyed. + + It is recommended to use + sd_event_add_io() only in conjunction with + file descriptors that have O_NONBLOCK set, to + ensure that all I/O operations from invoked handlers are properly + asynchronous and non-blocking. Using file descriptors without + O_NONBLOCK might result in unexpected + starvation of other event sources. See + fcntl2 + for details on enabling O_NONBLOCK mode. + + sd_event_source_get_io_events() retrieves + the configured mask of watched I/O events of an event source created + previously with sd_event_add_io(). It takes + the event source object and a pointer to a variable to store the + mask in. + + sd_event_source_set_io_events() + configures the mask of watched I/O events of an event source created + previously with sd_event_add_io(). It takes the + event source object and the new event mask. + + sd_event_source_get_io_revents() + retrieves the I/O event mask of currently seen but undispatched + events from an event source created previously with + sd_event_add_io(). It takes the event source + object and a pointer to a variable to store the event mask + in. When called from a handler function on the handler's event + source object this will return the same mask as passed to the + handler's revents parameter. This call is + primarily useful to check for undispatched events of an event + source from the handler of an unrelated (possibly higher priority) + event source. Note the relation between + sd_event_source_get_pending() and + sd_event_source_get_io_revents(): both + functions will report non-zero results when there's an event + pending for the event source, but the former applies to all event + source types, the latter only to I/O event sources. + + sd_event_source_get_io_fd() retrieves + the UNIX file descriptor of an event source created previously + with sd_event_add_io(). It takes the event + source object and returns the non-negative file descriptor + or a negative error number on error (see below). + + sd_event_source_set_io_fd() + changes the UNIX file descriptor of an I/O event source created + previously with sd_event_add_io(). It takes + the event source object and the new file descriptor. + + + + Return Value + + On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + + Errors + + Returned values may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate an object. + + + + -EINVAL + + An invalid argument has been passed. + + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + -EDOM + + The passed event source is not an I/O event source. + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_now3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + sd_event_source_get_pending3, + epoll_ctl3, + epoll7 + + + + diff --git a/src/libsystemd/sd_event_add_signal.xml b/src/libsystemd/sd_event_add_signal.xml new file mode 100644 index 0000000000..e98f1d2682 --- /dev/null +++ b/src/libsystemd/sd_event_add_signal.xml @@ -0,0 +1,221 @@ + + + + + + + + + sd_event_add_signal + systemd + + + + More text + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_event_add_signal + 3 + + + + sd_event_add_signal + sd_event_source_get_signal + sd_event_signal_handler_t + + Add a UNIX process signal event source to an event + loop + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_signal_handler_t) + sd_event_source *s + const struct signalfd_siginfo *si + void *userdata + + + + int sd_event_add_signal + sd_event *event + sd_event_source **source + int signal + sd_event_signal_handler_t handler + void *userdata + + + + int sd_event_source_get_signal + sd_event_source *source + + + + + + + Description + + sd_event_add_signal() adds a new UNIX + process signal event source to an event loop. The event loop + object is specified in the event parameter, + and the event source object is returned in the + source parameter. The + signal parameter specifies the numeric + signal to be handled (see signal7). + The handler parameter must reference a + function to call when the signal is received or be + NULL. The handler function will be passed + the userdata pointer, which may be chosen + freely by the caller. The handler also receives a pointer to a + signalfd_siginfo structure containing + information about the received signal. See signalfd2 + for further information. + + Only a single handler may be installed for a specific + signal. The signal will be unblocked by this call, and must be + blocked before this function is called in all threads (using + sigprocmask2). If + the handler is not specified (handler is + NULL), a default handler which causes the + program to exit cleanly will be used. + + By default, the event source is enabled permanently + (SD_EVENT_ON), but this may be changed with + sd_event_source_set_enabled3. + If the handler function returns a negative error code, it will be + disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. + + + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even if it is still referenced, + disable the event source using + sd_event_source_set_enabled3 + with SD_EVENT_OFF. + + If the second parameter of + sd_event_add_signal() is + NULL no reference to the event source object + is returned. In this case the event source is considered + "floating", and will be destroyed implicitly when the event loop + itself is destroyed. + + sd_event_source_get_signal() returns + the configured signal number of an event source created previously + with sd_event_add_signal(). It takes the + event source object as the source + parameter. + + + + Return Value + + On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate an object. + + + + -EINVAL + + An invalid argument has been passed. + + + + -EBUSY + + A handler is already installed for this + signal or the signal was not blocked previously. + + + + -ESTALE + + The event loop is already terminated. + + + + -ECHILD + + The event loop has been created in a different process. + + + + -EDOM + + The passed event source is not a signal event source. + + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_now3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_source_set_enabled3, + sd_event_source_set_description3, + sd_event_source_set_userdata3, + signal7, + signalfd2 + + + + diff --git a/src/libsystemd/sd_event_add_time.xml b/src/libsystemd/sd_event_add_time.xml new file mode 100644 index 0000000000..a2c0d54b56 --- /dev/null +++ b/src/libsystemd/sd_event_add_time.xml @@ -0,0 +1,313 @@ + + + + + + + + + sd_event_add_time + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_add_time + 3 + + + + sd_event_add_time + sd_event_source_get_time + sd_event_source_set_time + sd_event_source_get_time_accuracy + sd_event_source_set_time_accuracy + sd_event_source_get_time_clock + sd_event_time_handler_t + + Add a timer event source to an event loop + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_time_handler_t) + sd_event_source *s + uint64_t usec + void *userdata + + + + int sd_event_add_time + sd_event *event + sd_event_source **source + clockid_t clock + uint64_t usec + uint64_t accuracy + sd_event_time_handler_t handler + void *userdata + + + + int sd_event_source_get_time + sd_event_source *source + uint64_t *usec + + + + int sd_event_source_set_time + sd_event_source *source + uint64_t usec + + + + int sd_event_source_get_time_accuracy + sd_event_source *source + uint64_t *usec + + + + int sd_event_source_set_time_accuracy + sd_event_source *source + uint64_t usec + + + + int sd_event_source_get_time_clock + sd_event_source *source + clockid_t *clock + + + + + + + Description + + sd_event_add_time() adds a new timer event source to an event loop. The event loop + object is specified in the event parameter, the event source object is returned in the + source parameter. The clock parameter takes a clock identifier, one + of CLOCK_REALTIME, CLOCK_MONOTONIC, CLOCK_BOOTTIME, + CLOCK_REALTIME_ALARM, or CLOCK_BOOTTIME_ALARM. See + timerfd_create2 for details + regarding the various types of clocks. The usec parameter specifies the earliest time, in + microseconds (µs), relative to the clock's epoch, when the timer shall be triggered. If a time already in the past + is specified (including 0), this timer source "fires" immediately and is ready to be + dispatched. If the paramater is specified as UINT64_MAX the timer event will never elapse, + which may be used as an alternative to explicitly disabling a timer event source with + sd_event_source_set_enabled3. The + accuracy parameter specifies an additional accuracy value in µs specifying how much the + timer event may be delayed. Use 0 to select the default accuracy (250ms). Use 1µs for maximum + accuracy. Consider specifying 60000000µs (1min) or larger for long-running events that may be delayed + substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively, + improving power efficiency. The handler parameter shall reference a function to call when + the timer elapses. The handler function will be passed the userdata pointer, which may be + chosen freely by the caller. The handler is also passed the configured trigger time, even if it is actually called + slightly later, subject to the specified accuracy value, the kernel timer slack (see + prctl2), and additional + scheduling latencies. To query the actual time the handler was called use + sd_event_now3. + + By default, the timer will elapse once + (SD_EVENT_ONESHOT), but this may be changed + with + sd_event_source_set_enabled3. + If the handler function returns a negative error code, it will be + disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. Note + that a timer event set to SD_EVENT_ON will + fire continuously unless its configured time is updated using + sd_event_source_set_time(). + + + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even if it is still referenced, + disable the event source using + sd_event_source_set_enabled3 + with SD_EVENT_OFF. + + If the second parameter of + sd_event_add_time() is + NULL no reference to the event source object + is returned. In this case the event source is considered + "floating", and will be destroyed implicitly when the event loop + itself is destroyed. + + If the handler to + sd_event_add_time() is + NULL, and the event source fires, this will + be considered a request to exit the event loop. In this case, the + userdata parameter, cast to an integer, is + used for the exit code passed to + sd_event_exit3. + + Use CLOCK_BOOTTIME_ALARM and + CLOCK_REALTIME_ALARM to define event sources + that may wake up the system from suspend. + + In order to set up relative timers (that is, relative to the + current time), retrieve the current time via + sd_event_now3, + add the desired timespan to it, and use the result as + the usec parameter to + sd_event_add_time(). + + In order to set up repetitive timers (that is, timers that + are triggered in regular intervals), set up the timer normally, + for the first invocation. Each time the event handler is invoked, + update the timer's trigger time with + sd_event_source_set_time3 for the next timer + iteration, and reenable the timer using + sd_event_source_set_enabled(). To calculate + the next point in time to pass to + sd_event_source_set_time(), either use as + base the usec parameter passed to the timer + callback, or the timestamp returned by + sd_event_now(). In the former case timer + events will be regular, while in the latter case the scheduling + latency will keep accumulating on the timer. + + sd_event_source_get_time() retrieves + the configured time value of an event source created + previously with sd_event_add_time(). It takes + the event source object and a pointer to a variable to store the + time in, relative to the selected clock's epoch, in µs. + + sd_event_source_set_time() changes the + time of an event source created previously with + sd_event_add_time(). It takes the event + source object and a time relative to the selected clock's epoch, + in µs. + + sd_event_source_get_time_accuracy() + retrieves the configured accuracy value of a event source + created previously with sd_event_add_time(). It + takes the event source object and a pointer to a variable to store + the accuracy in. The accuracy is specified in µs. + + sd_event_source_set_time_accuracy() + changes the configured accuracy of a timer event source created + previously with sd_event_add_time(). It takes + the event source object and accuracy, in µs. + + sd_event_source_get_time_clock() + retrieves the configured clock of a event source created + previously with sd_event_add_time(). It takes + the event source object and a pointer to a variable to store the + clock identifier in. + + + + Return Value + + On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + + Errors + + Returned values may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate an object. + + + + -EINVAL + + An invalid argument has been passed. + + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + -EOPNOTSUPP + + The selected clock is not supported by the event loop implementation. + + + + + -EDOM + + The passed event source is not a timer event source. + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_now3, + sd_event_add_io3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + clock_gettime2, + timerfd_create2, + prctl2 + + + + diff --git a/src/libsystemd/sd_event_exit.xml b/src/libsystemd/sd_event_exit.xml new file mode 100644 index 0000000000..9846a3eaf4 --- /dev/null +++ b/src/libsystemd/sd_event_exit.xml @@ -0,0 +1,163 @@ + + + + + + + + + sd_event_exit + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_exit + 3 + + + + sd_event_exit + sd_event_get_exit_code + + Ask the event loop to exit + + + + + #include <systemd/sd-event.h> + + + int sd_event_exit + sd_event *event + int code + + + + int sd_event_get_exit_code + sd_event *event + int *code + + + + + + + Description + + sd_event_exit() requests the event loop + specified in the event event loop object to + exit. The code parameter may be any integer + value and is returned as-is by + sd_event_loop3 + after the last event loop iteration. It may also be queried + using sd_event_get_exit_code(), see + below. + + When exiting is requested the event loop will stop listening + for and dispatching regular event sources. Instead it will proceed + with executing only event sources registered with + sd_event_add_exit3 + in the order defined by their priority. After all exit event + sources have been dispatched the event loop is terminated. + + If sd_event_exit() is invoked a second + time while the event loop is still processing exit event sources, + the exit code stored in the event loop object is updated, but + otherwise no further operation is executed. + + sd_event_get_exit_code() may be used to + query the exit code passed into + sd_event_exit() earlier. + + While the full positive and negative integer ranges may be used + for the exit code, care should be taken not pick exit codes that + conflict with regular exit codes returned by + sd_event_loop(), if these exit codes shall be + distinguishable. + + + + Return Value + + On success, sd_event_exit() and + sd_event_get_exit_code() return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + The event loop object or error code pointer are invalid. + + + + + -ECHILD + + The event loop was created in a different process. + + + + -ESTALE + + The event loop has exited already and all exit handlers are already processed. + + + + -ENODATA + + The event loop has not been requested to exit yet. + + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_add_exit3 + + + + diff --git a/src/libsystemd/sd_event_get_fd-glib-example.c b/src/libsystemd/sd_event_get_fd-glib-example.c new file mode 100644 index 0000000000..8f3168d0ea --- /dev/null +++ b/src/libsystemd/sd_event_get_fd-glib-example.c @@ -0,0 +1,68 @@ +/*** + Copyright 2014 Tom Gundersen + + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation files + (the "Software"), to deal in the Software without restriction, + including without limitation the rights to use, copy, modify, merge, + publish, distribute, sublicense, and/or sell copies of the Software, + and to permit persons to whom the Software is furnished to do so, + subject to the following conditions: + + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS + BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. +***/ + +#include + +typedef struct SDEventSource { + GSource source; + GPollFD pollfd; + sd_event *event; +} SDEventSource; + +static gboolean event_prepare(GSource *source, gint *timeout_) { + return sd_event_prepare(((SDEventSource *)source)->event) > 0; +} + +static gboolean event_check(GSource *source) { + return sd_event_wait(((SDEventSource *)source)->event, 0) > 0; +} + +static gboolean event_dispatch(GSource *source, GSourceFunc callback, gpointer user_data) { + return sd_event_dispatch(((SDEventSource *)source)->event) > 0; +} + +static void event_finalize(GSource *source) { + sd_event_unref(((SDEventSource *)source)->event); +} + +static GSourceFuncs event_funcs = { + .prepare = event_prepare, + .check = event_check, + .dispatch = event_dispatch, + .finalize = event_finalize, +}; + +GSource *g_sd_event_create_source(sd_event *event) { + SDEventSource *source; + + source = (SDEventSource *)g_source_new(&event_funcs, sizeof(SDEventSource)); + + source->event = sd_event_ref(event); + source->pollfd.fd = sd_event_get_fd(event); + source->pollfd.events = G_IO_IN | G_IO_HUP | G_IO_ERR; + + g_source_add_poll((GSource *)source, &source->pollfd); + + return (GSource *)source; +} diff --git a/src/libsystemd/sd_event_get_fd.xml b/src/libsystemd/sd_event_get_fd.xml new file mode 100644 index 0000000000..982f279657 --- /dev/null +++ b/src/libsystemd/sd_event_get_fd.xml @@ -0,0 +1,140 @@ + + + + + + + + + sd_event_get_fd + systemd + + + + More text + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_event_get_fd + 3 + + + + sd_event_get_fd + + Obtain a file descriptor to poll for event loop events + + + + + #include <systemd/sd-event.h> + + + int sd_event_get_fd + sd_event *event + + + + + + + Description + + sd_event_get_fd() returns the file + descriptor that an event loop object returned by the + sd_event_new3 + function uses to wait for events. This file descriptor may itself + be polled for + POLLIN/EPOLLIN + events. This makes it possible to embed an + sd-event3 + event loop into another, possibly foreign, event loop. + + The returned file descriptor refers to an epoll7 + object. It is recommended not to alter it by invoking + epoll_ctl2 + on it, in order to avoid interference with the event loop's inner + logic and assumptions. + + + + Return Value + + On success, sd_event_get_fd() returns a + non-negative file descriptor. On failure, it returns a negative + errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + event is not a valid + pointer to an sd_event structure. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + + Examples + + + Integration in the GLib event loop + + + + + + + + + See Also + + + sd-event3, + sd_event_new3, + sd_event_wait3, + epoll_ctl3, + epoll7 + + + + diff --git a/src/libsystemd/sd_event_new.xml b/src/libsystemd/sd_event_new.xml new file mode 100644 index 0000000000..2c23b00a8c --- /dev/null +++ b/src/libsystemd/sd_event_new.xml @@ -0,0 +1,245 @@ + + + + + + + + + sd_event_new + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_new + 3 + + + + sd_event_new + sd_event_default + sd_event_ref + sd_event_unref + sd_event_unrefp + sd_event_get_tid + sd_event + + Acquire and release an event loop object + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event sd_event; + + + int sd_event_new + sd_event **event + + + + int sd_event_default + sd_event **event + + + + sd_event *sd_event_ref + sd_event *event + + + + sd_event *sd_event_unref + sd_event *event + + + + void sd_event_unrefp + sd_event **event + + + + int sd_event_get_tid + sd_event *event + pid_t *tid + + + + + + + Description + + sd_event_new() allocates a new event + loop object. The event loop object is returned in the + event parameter. After use, drop + the returned reference with + sd_event_unref(). When the last reference is + dropped, the object is freed. + + sd_event_default() acquires a reference + to the default event loop object of the calling thread, possibly + allocating a new object if no default event loop object has been + allocated yet for the thread. After use, drop the returned + reference with sd_event_unref(). When the + last reference is dropped, the event loop is freed. If this + function is called while the object returned from a previous call + from the same thread is still referenced, the same object is + returned again, but the reference is increased by one. It is + recommended to use this call instead of + sd_event_new() in order to share event loop + objects between various components that are dispatched in the same + thread. All threads have exactly either zero or one default event loop + objects associated, but never more. + + After allocating an event loop object, add event sources to + it with + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3 + or + sd_event_add_defer3, + and then execute the event loop using + sd_event_run3. + + sd_event_ref() increases the reference + count of the specified event loop object by one. + + sd_event_unref() decreases the + reference count of the specified event loop object by one. If + the count hits zero, the object is freed. Note that it + is freed regardless of whether it is the default event loop object for a + thread or not. This means that allocating an event loop with + sd_event_default(), then releasing it, and + then acquiring a new one with + sd_event_default() will result in two + distinct objects. Note that, in order to free an event loop object, + all remaining event sources of the event loop also need to be + freed as each keeps a reference to it. + + sd_event_unrefp() is similar to + sd_event_unref() but takes a pointer to a + pointer to an sd_event object. This call is useful in + conjunction with GCC's and LLVM's Clean-up + Variable Attribute. Note that this function is defined as + inline function. Use a declaration like the following, + in order to allocate an event loop object that is freed + automatically as the code block is left: + + { + __attribute__((cleanup(sd_event_unrefp)) sd_event *event = NULL; + int r; + … + r = sd_event_default(&event); + if (r < 0) + fprintf(stderr, "Failed to allocate event loop: %s\n", strerror(-r)); + … +} + + sd_event_ref(), + sd_event_unref() and + sd_event_unrefp() execute no operation if the + passed in event loop object is NULL. + + sd_event_get_tid() retrieves the thread + identifier ("TID") of the thread the specified event loop object + is associated with. This call is only supported for event loops + allocated with sd_event_default(), and + returns the identifier for the thread the event loop is the + default event loop of. See gettid2 + for more information on thread identifiers. + + + + Return Value + + On success, sd_event_new() and + sd_event_default() return 0 or a positive + integer. On failure, they return a negative errno-style error + code. sd_event_ref() always returns a pointer + to the event loop object passed + in. sd_event_unref() always returns + NULL. + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate the object. + + + + -EMFILE + + The maximum number of event loops has been allocated. + + + + + -ENXIO + + sd_event_get_tid() was + invoked on an event loop object that was not allocated with + sd_event_default(). + + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_add_post3, + sd_event_add_exit3, + sd_event_run3, + gettid2 + + + + diff --git a/src/libsystemd/sd_event_now.xml b/src/libsystemd/sd_event_now.xml new file mode 100644 index 0000000000..2c83b0bcb5 --- /dev/null +++ b/src/libsystemd/sd_event_now.xml @@ -0,0 +1,146 @@ + + + + + + + + + sd_event_now + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_now + 3 + + + + sd_event_now + + Retrieve current event loop iteration timestamp + + + + + #include <systemd/sd-event.h> + + + int sd_event_now + sd_event *event + clockid_t clock + uint64_t *usec + + + + + + + Description + + sd_event_now() returns the time when + the most recent event loop iteration began. A timestamp + is taken right after returning from the event sleep, and before + dispatching any event sources. The event + parameter specifies the event loop object to retrieve the timestamp + from. The clock parameter specifies the clock to + retrieve the timestamp for, and is one of + CLOCK_REALTIME (or equivalently + CLOCK_REALTIME_ALARM), + CLOCK_MONOTONIC, or + CLOCK_BOOTTIME (or equivalently + CLOCK_BOOTTIME_ALARM), see + clock_gettime2 + for more information on the various clocks. The retrieved + timestamp is stored in the usec parameter, + in µs since the clock's epoch. If this function is invoked before + the first event loop iteration, the current time is returned, as + reported by clock_gettime(). To distinguish + this case from a regular invocation the return value will be + positive, and zero when the returned timestamp refers to an actual + event loop iteration. + + + + Return Value + + If the first event loop iteration has not run yet + sd_event_now() writes current time to + usec and returns a positive return value. + Otherwise, it will write the requested timestamp to usec + and return 0. On failure, the call returns a negative errno-style + error code. + + + + Errors + + Returned values may indicate the following problems: + + + + -EINVAL + + An invalid parameter was + passed. + + + + + -EOPNOTSUPP + + Unsupported clock type. + + + + + -ECHILD + + The event loop object was created in a + different process. + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_add_time3, + clock_gettime2 + + + + diff --git a/src/libsystemd/sd_event_run.xml b/src/libsystemd/sd_event_run.xml new file mode 100644 index 0000000000..5b68959165 --- /dev/null +++ b/src/libsystemd/sd_event_run.xml @@ -0,0 +1,190 @@ + + + + + + + + + sd_event_run + systemd + + + + Developer + Tom + Gundersen + teg@jklm.no + + + + + + sd_event_run + 3 + + + + sd_event_run + sd_event_loop + + Run an event loop + + + + + #include <systemd/sd-event.h> + + + int sd_event_run + sd_event *event + uint64_t usec + + + + int sd_event_loop + sd_event *event + + + + + + Description + + sd_event_run() may be used to run a single + iteration of the event loop specified in the + event parameter. The function waits until an event to + process is available, and dispatches the registered handler for + it. The usec parameter specifies the + maximum time (in microseconds) to wait for an event. Use + (uint64_t) -1 to specify an infinite + timeout. + + sd_event_loop() invokes + sd_event_run() in a loop, thus implementing + the actual event loop. The call returns as soon as exiting was + requested using + sd_event_exit3. + + The event loop object event is + created with + sd_event_new3. + Events sources to wait for and their handlers may be registered + with + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_add_post3 + and + sd_event_add_exit3. + + + For low-level control of event loop execution, use + sd_event_prepare3, + sd_event_wait3 + and + sd_event_dispatch3 + which are wrapped by sd_event_run(). Along + with + sd_event_get_fd3, + these functions allow integration of an + sd-event3 + event loop into foreign event loop implementations. + + + + Return Value + + On failure, these functions return a negative errno-style + error code. sd_event_run() returns a + positive, non-zero integer if an event source was dispatched, and + zero when the specified timeout hit before an event source has + seen any event, and hence no event source was + dispatched. sd_event_loop() returns the exit + code specified when invoking + sd_event_exit(). + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + The event parameter is + invalid or NULL. + + + + -EBUSY + + The event loop object is not in the right + state (see + sd_event_prepare3 + for an explanation of possible states). + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + Other errors are possible, too. + + + + + + See Also + + + systemd1, + sd_event_new3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_add_exit3, + sd_event_add_post3, + sd_event_exit3, + sd_event_get_fd3, + sd_event_wait3, + GLib Main Event Loop. + + + + diff --git a/src/libsystemd/sd_event_set_watchdog.xml b/src/libsystemd/sd_event_set_watchdog.xml new file mode 100644 index 0000000000..cbc5bc0836 --- /dev/null +++ b/src/libsystemd/sd_event_set_watchdog.xml @@ -0,0 +1,177 @@ + + + + + + + + + sd_event_set_watchdog + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_set_watchdog + 3 + + + + sd_event_set_watchdog + sd_event_get_watchdog + + Enable event loop watchdog support + + + + + #include <systemd/sd-event.h> + + + int sd_event_set_watchdog + sd_event *event + int b + + + + int sd_event_get_watchdog + sd_event *event + + + + + + + Description + + sd_event_set_watchdog() may be used to + enable or disable automatic watchdog notification support in the + event loop object specified in the event + parameter. Specifically, depending on the b + boolean argument this will make sure the event loop wakes up in + regular intervals and sends watchdog notification messages to the + service manager, if this was requested by the service + manager. Watchdog support is determined with + sd_watchdog_enabled3, + and watchdog messages are sent with + sd_notify3. See + the WatchdogSec= setting in + systemd.service5 + for details on how to enable watchdog support for a service and + the protocol used. The wake-up interval is chosen as half the + watchdog timeout declared by the service manager via the + $WATCHDOG_USEC environment variable. If the + service manager did not request watchdog notifications, or if the + process was not invoked by the service manager this call with a + true b parameter executes no + operation. Passing a false b parameter will + disable the automatic sending of watchdog notification messages if + it was enabled before. Newly allocated event loop objects have + this feature disabled. + + The first watchdog notification message is sent immediately + when set_event_set_watchdog() is invoked with + a true b parameter. + + The watchdog logic is designed to allow the service manager + to automatically detect services that ceased processing of + incoming events, and thus appear "hung". Watchdog notifications + are sent out only at the beginning of each event loop + iteration. If an event source dispatch function blocks for an + excessively long time and does not return execution to the event + loop quickly, this might hence cause the notification message to + be delayed, and possibly result in abnormal program termination, + as configured in the service unit file. + + sd_event_get_watchdog() may be used to + determine whether watchdog support was previously requested by a + call to sd_event_set_watchdog() with a true + b parameter and successfully + enabled. + + + + Return Value + + On success, sd_event_set_watchdog() and + sd_event_get_watchdog() return a non-zero + positive integer if the service manager requested watchdog support + and watchdog support was successfully enabled. They return zero if + the service manager did not request watchdog support, or if + watchdog support was explicitly disabled with a false + b parameter. On failure, they return a + negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -ECHILD + + The event loop has been created in a different process. + + + + -EINVAL + + The passed event loop object was invalid. + + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_add_post3, + sd_event_add_exit3, + sd_watchdog_enabled3, + sd_notify3, + systemd.service5 + + + + diff --git a/src/libsystemd/sd_event_source_get_event.xml b/src/libsystemd/sd_event_source_get_event.xml new file mode 100644 index 0000000000..2fdbd411bd --- /dev/null +++ b/src/libsystemd/sd_event_source_get_event.xml @@ -0,0 +1,100 @@ + + + + + + + + + sd_event_source_get_event + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_get_event + 3 + + + + sd_event_source_get_event + + Retrieve the event loop of an event source + + + + + #include <systemd/sd-event.h> + + + sd_event* sd_event_source_get_event + sd_event_source *source + + + + + + + Description + + sd_event_source_get_event() may be used + to retrieve the event loop object the event source object specified + as source is associated with. The event + loop object is specified when creating an event source object with + calls such as + sd_event_add_io3 + or + sd_event_add_time3. + + + + Return Value + + On success, sd_event_source_get_event() + returns the associated event loop object. On failure, it returns + NULL. + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_userdata3 + + + + diff --git a/src/libsystemd/sd_event_source_get_pending.xml b/src/libsystemd/sd_event_source_get_pending.xml new file mode 100644 index 0000000000..7f88bd1b87 --- /dev/null +++ b/src/libsystemd/sd_event_source_get_pending.xml @@ -0,0 +1,167 @@ + + + + + + + + + sd_event_source_get_pending + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_get_pending + 3 + + + + sd_event_source_get_pending + + Determine pending state of event sources + + + + + #include <systemd/sd-event.h> + + + int sd_event_source_get_pending + sd_event_source *source + + + + + + + Description + + sd_event_source_get_pending() may be + used to determine whether the event source object specified as + source has seen events but has not been + dispatched yet (and thus is marked "pending"). + + Event source objects initially are not marked pending, when + they are created with calls such as + sd_event_add_io3, + sd_event_add_time3, + with the exception of those created with + sd_event_add_defer3 + which are immediately marked pending, and + sd_event_add_exit3 + for which the "pending" concept is not defined. For details see + the respective manual pages. + + In each event loop iteration one event source of those + marked pending is dispatched, in the order defined by the event + source priority, as set with + sd_event_source_set_priority3. + + For I/O event sources, as created with + sd_event_add_io3, + the call + sd_event_source_get_io_revents3 + may be used to query the type of event pending in more + detail. + + + + + Return Value + + On success, + sd_event_source_get_pending() returns an + integer greater than zero when the event source is marked pending, + and zero when the event source is not marked pending. On failure, + it returns a negative errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + source is not a valid + pointer to an sd_event_source + object. + + + + -EDOM + + source refers to an + event source object created with + sd_event_add_exit3. + + + + -ENOMEM + + Not enough memory. + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_unref3 + + + + diff --git a/src/libsystemd/sd_event_source_set_description.xml b/src/libsystemd/sd_event_source_set_description.xml new file mode 100644 index 0000000000..b9488a622f --- /dev/null +++ b/src/libsystemd/sd_event_source_set_description.xml @@ -0,0 +1,170 @@ + + + + + + + + + sd_event_source_set_description + systemd + + + + More text + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_event_source_set_description + 3 + + + + sd_event_source_set_description + sd_event_source_get_description + + Set or retrieve descriptive names of event sources + + + + + #include <systemd/sd-event.h> + + + int sd_event_source_set_description + sd_event_source *source + const char *description + + + + int sd_event_source_get_description + sd_event_source *source + const char **description + + + + + + + Description + + sd_event_source_set_description() may + be used to set an arbitrary descriptive name for the event source + object specified as source. This name will + be used in debugging messages generated by + sd-event3 + for this event source, and may be queried using + sd_event_source_get_description() for + debugging purposes. The description parameter shall + point to a NUL-terminated string or be + NULL. In the latter case, the descriptive + name will be unset. The string is copied internally, hence the + description argument is not referenced + after the function returns. + + sd_event_source_get_description() may + be used to query the current descriptive name assigned to the + event source object source. It returns a + pointer to the current name in description, + stored in memory internal to the event source. The memory is + invalidated when the event source is destroyed or the descriptive + name is changed. + + Event source objects generally have no description set when + they are created, except for UNIX signal event sources created + with + sd_event_add_signal3, + whose descriptive name is initialized to the signal's C constant + name (e.g. SIGINT or + SIGTERM). + + + + Return Value + + On success, sd_event_source_set_description() and + sd_event_source_get_description() return a + non-negative integer. On failure, they return a negative + errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + source is not a valid + pointer to an sd_event_source + object or the description argument for + sd_event_source_get_description() is + NULL. + + + + -ENOMEM + + Not enough memory to copy the + name. + + + + -ECHILD + + The event loop has been created in a different process. + + + + + -ENXIO + + No name was set for the event + source. + + + + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_userdata3 + + + + diff --git a/src/libsystemd/sd_event_source_set_enabled.xml b/src/libsystemd/sd_event_source_set_enabled.xml new file mode 100644 index 0000000000..6844f29a49 --- /dev/null +++ b/src/libsystemd/sd_event_source_set_enabled.xml @@ -0,0 +1,179 @@ + + + + + + + + + sd_event_source_set_enabled + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_set_enabled + 3 + + + + sd_event_source_set_enabled + sd_event_source_get_enabled + SD_EVENT_ON + SD_EVENT_OFF + SD_EVENT_ONESHOT + + Enable or disable event sources + + + + + #include <systemd/sd-event.h> + + enum { + SD_EVENT_OFF = 0, + SD_EVENT_ON = 1, + SD_EVENT_ONESHOT = -1, +}; + + + int sd_event_source_set_enabled + sd_event_source *source + int enabled + + + + int sd_event_source_get_enabled + sd_event_source *source + int *enabled + + + + + + + Description + + sd_event_source_set_enabled() may be + used to enable or disable the event source object specified as + source. The enabled + parameter takes one of SD_EVENT_ON (to + enable), SD_EVENT_OFF (to disable) or + SD_EVENT_ONESHOT. If invoked with + SD_EVENT_ONESHOT the event source will be + enabled but automatically reset to + SD_EVENT_OFF after the event source was + dispatched once. + + Event sources that are disabled will not result in event + loop wakeups and will not be dispatched, until they are enabled + again. + + sd_event_source_get_enabled() may be + used to query whether the event source object + source is currently enabled or not. It + returns the enablement state in + enabled. + + Event source objects are enabled when they are first created + with calls such as + sd_event_add_io3, + sd_event_add_time3. However, + depending on the event source type they are enabled continuously + (SD_EVENT_ON) or only for a single invocation + of the event source handler + (SD_EVENT_ONESHOT). For details see the + respective manual pages. + + As event source objects stay active and may be dispatched as + long as there is at least one reference to them, in many cases it + is a good idea to combine a call to + sd_event_source_unref3 + with a prior call to + sd_event_source_set_enabled() with + SD_EVENT_OFF, to ensure the event source is + not dispatched again until all other remaining references are dropped. + + + + Return Value + + On success, sd_event_source_set_enabled() and + sd_event_source_get_enabled() return a + non-negative integer. On failure, they return a negative + errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + source is not a valid + pointer to an sd_event_source + object. + + + + -ENOMEM + + Not enough memory. + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_unref3 + + + + diff --git a/src/libsystemd/sd_event_source_set_prepare.xml b/src/libsystemd/sd_event_source_set_prepare.xml new file mode 100644 index 0000000000..24861d01d9 --- /dev/null +++ b/src/libsystemd/sd_event_source_set_prepare.xml @@ -0,0 +1,171 @@ + + + + + + + + + sd_event_source_set_prepare + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_set_prepare + 3 + + + + sd_event_source_set_prepare + + Set a preparation callback for event sources + + + + + #include <systemd/sd-event.h> + + + int sd_event_source_set_prepare + sd_event_source *source + sd_event_handler_t callback + + + + typedef int (*sd_event_handler_t) + sd_event_source *s + void *userdata + + + + + + + Description + + sd_event_source_set_prepare() may be + used to set a preparation callback for the event source object + specified as source. The callback function + specified as callback will be invoked + immediately before the event loop goes to sleep to wait for + incoming events. It is invoked with the user data pointer passed + when the event source was created. The callback function may be + used to reconfigure the precise events to wait for. If the + callback parameter is passed as NULL the + callback function is reset. + + Event source objects have no preparation callback associated + when they are first created with calls such as + sd_event_add_io3, + sd_event_add_time3. Preparation + callback functions are supported for all event source types with + the exception of those created with + sd_event_add_exit3. Preparation + callback functions are dispatched in the order indicated by the + event source's priority field, as set with + sd_event_source_set_priority3. Preparation + callbacks of disabled event sources (see + sd_event_source_set_enabled3) + are not invoked. + + + + Return Value + + On success, + sd_event_source_set_prepare() returns a + non-negative integer. On failure, it returns a negative + errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + source is not a valid + pointer to an sd_event_source + object. + + + + -ESTALE + + The event loop is already terminated. + + + + -ENOMEM + + Not enough memory. + + + + -ECHILD + + The event loop has been created in a different process. + + + + + -EDOM + + The specified event source has been created + with + sd_event_add_exit3. + + + + + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3 + + + + diff --git a/src/libsystemd/sd_event_source_set_priority.xml b/src/libsystemd/sd_event_source_set_priority.xml new file mode 100644 index 0000000000..8c9b39fe5e --- /dev/null +++ b/src/libsystemd/sd_event_source_set_priority.xml @@ -0,0 +1,189 @@ + + + + + + + + + sd_event_source_set_priority + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_set_priority + 3 + + + + sd_event_source_set_priority + sd_event_source_get_priority + SD_EVENT_PRIORITY_IMPORTANT + SD_EVENT_PRIORITY_NORMAL + SD_EVENT_PRIORITY_IDLE + + Set or retrieve the priority of event sources + + + + + #include <systemd/sd-event.h> + + enum { + SD_EVENT_SOURCE_IMPORTANT = -100, + SD_EVENT_SOURCE_NORMAL = 0, + SD_EVENT_SOURCE_IDLE = 100, +}; + + + int sd_event_source_set_priority + sd_event_source *source + int64_t priority + + + + int sd_event_source_get_priority + sd_event_source *source + int64_t *priority + + + + + + + Description + + sd_event_source_set_priority() may be + used to set the priority for the event source object specified as + source. The priority is specified as an + arbitrary signed 64bit integer. The priority is initialized to + SD_EVENT_PRIORITY_NORMAL (0) when the event + source is allocated with a call such as + sd_event_add_io3 + or + sd_event_add_time3, + and may be changed with this call. If multiple event sources have seen events at the same time, they are dispatched in the order indicated by the + event sources' priorities. Event sources with smaller priority + values are dispatched first. As well-known points of reference, + the constants SD_EVENT_PRIORITY_IMPORTANT + (-100), SD_EVENT_PRIORITY_NORMAL (0) and + SD_EVENT_PRIORITY_IDLE (100) may be used to + indicate event sources that shall be dispatched early, normally or + late. It is recommended to specify priorities based on these + definitions, and relative to them — however, the full 64bit + signed integer range is available for ordering event + sources. + + Priorities define the order in which event sources that have + seen events are dispatched. Care should be taken to ensure that + high-priority event sources (those with negative priority values + assigned) do not cause starvation of low-priority event sources + (those with positive priority values assigned). + + The order in which event sources with the same priority are + dispatched is undefined, but the event loop generally tries to + dispatch them in the order it learnt about events on them. As the + backing kernel primitives do not provide accurate information + about the order in which events occurred this is not necessarily + reliable. However, it is guaranteed that if events are seen on + multiple same-priority event sources at the same time, each one is + not dispatched again until all others have been dispatched + once. This behaviour guarantees that within each priority + particular event sources do not starve or dominate the event + loop. + + sd_event_source_get_priority() may be + used to query the current priority assigned to the event source + object source. + + + + Return Value + + On success, + sd_event_source_set_priority() and + sd_event_source_get_priority() return a + non-negative integer. On failure, they return a negative + errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + source is not a valid + pointer to an sd_event_source + object. + + + + -ENOMEM + + Not enough memory. + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3 + + + + diff --git a/src/libsystemd/sd_event_source_set_userdata.xml b/src/libsystemd/sd_event_source_set_userdata.xml new file mode 100644 index 0000000000..533d491b13 --- /dev/null +++ b/src/libsystemd/sd_event_source_set_userdata.xml @@ -0,0 +1,119 @@ + + + + + + + + + sd_event_source_set_userdata + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_set_userdata + 3 + + + + sd_event_source_set_userdata + sd_event_source_get_userdata + + Set or retrieve user data pointer of event sources + + + + + #include <systemd/sd-event.h> + + + void* sd_event_source_set_userdata + sd_event_source *source + void *userdata + + + + void* sd_event_source_get_userdata + sd_event_source *source + + + + + + + Description + + sd_event_source_set_userdata() may be + used to set an arbitrary user data pointer for the event source + object specified as source. The user data + pointer is usually specified when creating an event source object + with calls such as + sd_event_add_io3 + or + sd_event_add_time3, + and may be updated with this call. The user data pointer is also + passed to all handler callback functions associated with the event + source. The userdata parameter specifies + the new user data pointer to set, the function returns the + previous user data pointer. Note that NULL is + a valid user data pointer. + + sd_event_source_get_userdata() may be + used to query the current user data pointer assigned to the event + source object source. + + + + Return Value + + On success, + sd_event_source_set_userdata() and + sd_event_source_get_userdata() return the + previously set user data pointer. On failure, they return + NULL. + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_description3 + + + + diff --git a/src/libsystemd/sd_event_source_unref.xml b/src/libsystemd/sd_event_source_unref.xml new file mode 100644 index 0000000000..2c4d450763 --- /dev/null +++ b/src/libsystemd/sd_event_source_unref.xml @@ -0,0 +1,142 @@ + + + + + + + + + sd_event_source_unref + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_source_unref + 3 + + + + sd_event_source_unref + sd_event_source_unrefp + sd_event_source_ref + + Increase or decrease event source reference counters + + + + + #include <systemd/sd-event.h> + + + sd_event_source* sd_event_source_unref + sd_event_source *source + + + + void sd_event_source_unrefp + sd_event_source **source + + + + sd_event_source* sd_event_source_ref + sd_event_source *source + + + + + + + Description + + sd_event_source_unref() may be used to + decrement by one the reference counter of the event source object + specified as source. The reference counter + is initially set to one, when the event source is created with calls + such as + sd_event_add_io3 + or + sd_event_add_time3. When + the reference counter reaches zero it is removed from its event loop + object and destroyed. + + sd_event_source_unrefp() is similar to + sd_event_source_unref() but takes a pointer to a + pointer to an sd_event_source object. This call is useful in + conjunction with GCC's and LLVM's Clean-up + Variable Attribute. Note that this function is defined as + inline function. + + sd_event_source_ref() may be used + to increase by one the reference counter of the event source object + specified as source. + + sd_event_source_unref(), + sd_bus_creds_unrefp() and + sd_bus_creds_ref() execute no operation if + the passed event source object is + NULL. + + Note that event source objects stay alive and may be + dispatched as long as they have a reference counter greater than + zero. In order to drop a reference of an event source and make + sure the associated event source handler function is not called + anymore it is recommended to combine a call of + sd_event_source_unref() with a prior call to + sd_event_source_set_enabled() with + SD_EVENT_OFF. + + + + Return Value + + sd_event_source_unref() always returns + NULL. + sd_event_source_ref() always returns the + event source object passed in. + + + + + + See Also + + + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_enabled3 + + + + diff --git a/src/libsystemd/sd_event_wait.xml b/src/libsystemd/sd_event_wait.xml new file mode 100644 index 0000000000..f2aea00e98 --- /dev/null +++ b/src/libsystemd/sd_event_wait.xml @@ -0,0 +1,346 @@ + + + + + + + + + sd_event_wait + systemd + + + + Developer + Tom + Gundersen + teg@jklm.no + + + + + + sd_event_wait + 3 + + + + sd_event_wait + sd_event_prepare + sd_event_dispatch + sd_event_get_state + SD_EVENT_INITIAL + SD_EVENT_PREPARING + SD_EVENT_ARMED + SD_EVENT_PENDING + SD_EVENT_RUNNING + SD_EVENT_EXITING + SD_EVENT_FINISHED + + Low-level event loop operations + + + + + #include <systemd/sd-event.h> + + enum { + SD_EVENT_INITIAL, + SD_EVENT_PREPARING, + SD_EVENT_ARMED, + SD_EVENT_PENDING, + SD_EVENT_RUNNING, + SD_EVENT_EXITING, + SD_EVENT_FINISHED, +}; + + + int sd_event_prepare + sd_event *event + + + + int sd_event_wait + sd_event *event + uint64_t usec + + + + int sd_event_dispatch + sd_event *event + + + + int sd_event_get_state + sd_event *event + + + + + + + Description + + The low-level sd_event_prepare(), + sd_event_wait() and + sd_event_dispatch() functions may be used to + execute specific phases of an event loop. See + sd_event_run3 + and + sd_event_loop3 + for higher-level functions that execute individual but complete + iterations of an event loop or run it continuously. + + sd_event_prepare() checks for pending + events and arms necessary timers. If any events are ready to be + processed ("pending"), it returns a positive, non-zero value, and the caller + should process these events with + sd_event_dispatch(). + + sd_event_dispatch() dispatches the + highest priority event source that has a pending event. On + success, sd_event_dispatch() returns either + zero, which indicates that no further event sources may be + dispatched and exiting of the event loop was requested via + sd_event_exit3; + or a positive non-zero value, which means that an event source was + dispatched and the loop returned to its initial state, and the + caller should initiate the next event loop iteration by invoking + sd_event_prepare() again. + + In case sd_event_prepare() returned + zero, sd_event_wait() should be called to + wait for further events or a timeout. If any events are ready to + be processed, it returns a positive, non-zero value, and the + events should be dispatched with + sd_event_dispatch(). Otherwise, the event + loop returned to its initial state and the next event loop + iteration should be initiated by invoking + sd_event_prepare() again. + + sd_event_get_state() may be used to + determine the state the event loop is currently in. It returns one + of the states described below. + + All four functions take, as the first argument, the event + loop object event that has been created + with sd_event_new(). The timeout for + sd_event_wait() is specified in + usec in milliseconds. (uint64_t) + -1 may be used to specify an infinite timeout. + + + + State Machine + + The event loop knows the following states, that may be + queried with sd_event_get_state(). + + + + SD_EVENT_INITIAL + + The initial state the event loop is in, + before each event loop iteration. Use + sd_event_prepare() to transition the + event loop into the SD_EVENT_ARMED or + SD_EVENT_PENDING states. + + + + SD_EVENT_PREPARING + + An event source is currently being prepared, + i.e. the preparation handler is currently being executed, as + set with + sd_event_set_prepare3. This + state is only seen in the event source preparation handler + that is invoked from the + sd_event_prepare() call and is + immediately followed by SD_EVENT_ARMED or + SD_EVENT_PENDING. + + + + SD_EVENT_ARMED + + sd_event_prepare() has + been called and no event sources were ready to be + dispatched. Use sd_event_wait() to wait + for new events, and transition into + SD_EVENT_PENDING or back into + SD_EVENT_INITIAL. + + + + SD_EVENT_PENDING + + sd_event_prepare() or + sd_event_wait() have been called and + there were event sources with events pending. Use + sd_event_dispatch() to dispatch the + highest priority event source and transition back to + SD_EVENT_INITIAL, or + SD_EVENT_FINISHED. + + + + SD_EVENT_RUNNING + + A regular event source is currently being + dispatched. This state is only seen in the event source + handler that is invoked from the + sd_event_dispatch() call, and is + immediately followed by SD_EVENT_INITIAL + or SD_EVENT_FINISHED as soon the event + source handler returns. Note that during dispatching of exit + event sources the SD_EVENT_EXITING state + is seen instead. + + + + SD_EVENT_EXITING + + Similar to + SD_EVENT_RUNNING but is the state in + effect while dispatching exit event sources. It is followed by + SD_EVENT_INITIAL or + SD_EVENT_FINISHED as soon as the event + handler returns. + + + + SD_EVENT_FINISHED + + The event loop has exited. All exit event + sources have run. If the event loop is in this state it serves + no purpose anymore, and should be freed. + + + + + A simplified flow chart of the states and the calls to + transition between them is shown below. Note that + SD_EVENT_PREPARING, + SD_EVENT_RUNNING and + SD_EVENT_EXITING are not shown here. + + + INITIAL -<---<---<---<---<---<---<---<---<---<---<---<---\ + | | + | ^ + | | + v ret == 0 | + sd_event_prepare() >--->--->--->--->- ARMED | + | | ^ + | ret > 0 | | + | | | + v v ret == 0 | + PENDING <---<---<---<---<---< sd_event_wait() >--->--->--+ + | ret > 0 ^ + | | + | | + v | + sd_event_dispatch() >--->--->--->--->--->--->--->--->--->--->/ + | ret > 0 + | ret == 0 + | + v + FINISHED + + + + + Return Value + + On success, these functions return 0 or a positive integer. + On failure, they return a negative errno-style error code. In case + of sd_event_prepare() and + sd_event_wait(), a positive, non-zero return + code indicates that events are ready to be processed and zero + indicates that no events are ready. In case of + sd_event_dispatch(), a positive, non-zero + return code indicates that the event loop returned to its initial + state and zero indicates the event loop has + exited. sd_event_get_state() returns a + positive or zero state on success. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + The event parameter is + invalid or NULL. + + + + -EBUSY + + The event loop object is not in the right + state. + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + Other errors are possible, too. + + + + + + See Also + + + systemd1, + sd_event_new3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_add_exit3, + sd_event_add_post3, + sd_event_run3, + sd_event_get_fd3, + sd_event_source_set_prepare3 + + + + diff --git a/src/libsystemd/sd_get_seats.xml b/src/libsystemd/sd_get_seats.xml new file mode 100644 index 0000000000..37eb3fc894 --- /dev/null +++ b/src/libsystemd/sd_get_seats.xml @@ -0,0 +1,164 @@ + + + + + + + + + sd_get_seats + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_get_seats + 3 + + + + sd_get_seats + sd_get_sessions + sd_get_uids + sd_get_machine_names + Determine available seats, sessions, logged in users and virtual machines/containers + + + + + #include <systemd/sd-login.h> + + + int sd_get_seats + char ***seats + + + + int sd_get_sessions + char ***sessions + + + + int sd_get_uids + uid_t **users + + + + int sd_get_machine_names + char ***machines + + + + + + + Description + + sd_get_seats() may be used to determine + all currently available local seats. Returns a + NULL terminated array of seat identifiers. + The returned array and all strings it references need to be freed + with the libc + free3 + call after use. Note that instead of an empty array + NULL may be returned and should be considered + equivalent to an empty array. + + Similarly, sd_get_sessions() may be + used to determine all current login sessions. + + Similarly, sd_get_uids() may be used to + determine all Unix users who currently have login sessions. + + Similarly, sd_get_machine_names() may + be used to determine all current virtual machines and containers + on the system. + + Note that the returned lists are not sorted and in an + undefined order. + + + + Return Value + + On success, sd_get_seats(), + sd_get_sessions(), + sd_get_uids() and + sd_get_machine_names() return the number of + entries in the arrays. On failure, these calls return a negative + errno-style error code. + + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + An input parameter was invalid (out of range, + or NULL, where that is not accepted). + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + The sd_get_seats(), + sd_get_sessions(), + sd_get_uids() and + sd_get_machine_names() interfaces are + available as a shared library, which can be compiled and linked to + with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-login3, + sd_session_get_seat3 + + + + diff --git a/src/libsystemd/sd_id128_get_machine.xml b/src/libsystemd/sd_id128_get_machine.xml new file mode 100644 index 0000000000..2ad1f8f728 --- /dev/null +++ b/src/libsystemd/sd_id128_get_machine.xml @@ -0,0 +1,129 @@ + + + + + + + + + sd_id128_get_machine + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_id128_get_machine + 3 + + + + sd_id128_get_machine + sd_id128_get_boot + Retrieve 128-bit IDs + + + + + #include <systemd/sd-id128.h> + + + int sd_id128_get_machine + sd_id128_t *ret + + + + int sd_id128_get_boot + sd_id128_t *ret + + + + + + + Description + + sd_id128_get_machine() returns the + machine ID of the executing host. This reads and parses the + machine-id5 + file. This function caches the machine ID internally to make + retrieving the machine ID a cheap operation. + + sd_id128_get_boot() returns the boot ID + of the executing kernel. This reads and parses the + /proc/sys/kernel/random/boot_id file exposed + by the kernel. It is randomly generated early at boot and is + unique for every running kernel instance. See + random4 + for more information. This function also internally caches the + returned ID to make this call a cheap operation. + + Note that sd_id128_get_boot() always + returns a UUID v4 compatible ID. + sd_id128_get_machine() will also return a + UUID v4-compatible ID on new installations but might not on older. + It is possible to convert the machine ID into a UUID v4-compatible + one. For more information, see + machine-id5. + + For more information about the sd_id128_t + type see + sd-id1283. + + + + Return Value + + The two calls return 0 on success (in which case + ret is filled in), or a negative + errno-style error code. + + + + Notes + + The sd_id128_get_machine() and + sd_id128_get_boot() interfaces are available + as a shared library, which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-id1283, + machine-id5, + random4, + sd_id128_randomize3 + + + + diff --git a/src/libsystemd/sd_id128_randomize.xml b/src/libsystemd/sd_id128_randomize.xml new file mode 100644 index 0000000000..ab449d2937 --- /dev/null +++ b/src/libsystemd/sd_id128_randomize.xml @@ -0,0 +1,114 @@ + + + + + + + + + sd_id128_randomize + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_id128_randomize + 3 + + + + sd_id128_randomize + Generate 128-bit IDs + + + + + #include <systemd/sd-id128.h> + + + int sd_id128_randomize + sd_id128_t *ret + + + + + + + Description + + sd_id128_randomize() generates a new + randomized 128-bit ID and returns it in + ret. Every invocation returns a new + randomly generated ID. This uses the + /dev/urandom kernel random number + generator. + + Note that sd_id128_randomize() always + returns a UUID v4-compatible ID. + + For more information about the sd_id128_t + type, see + sd-id1283. + + journalctl1's + option may be used as a command line + front-end for sd_id128_randomize(). + + + + Return Value + + The call returns 0 on success (in which case + ret is filled in), or a negative + errno-style error code. + + + + Notes + + The sd_id128_randomize() interface is + available as a shared library, which can be compiled and linked to + with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-id1283, + machine-id5, + random4, + sd_id128_get_machine3 + + + + diff --git a/src/libsystemd/sd_id128_to_string.xml b/src/libsystemd/sd_id128_to_string.xml new file mode 100644 index 0000000000..e70c80892e --- /dev/null +++ b/src/libsystemd/sd_id128_to_string.xml @@ -0,0 +1,132 @@ + + + + + + + + + sd_id128_to_string + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_id128_to_string + 3 + + + + sd_id128_to_string + sd_id128_from_string + Format or parse 128-bit IDs as strings + + + + + #include <systemd/sd-id128.h> + + + char *sd_id128_to_string + sd_id128_t id, char s[33] + + + + int sd_id128_from_string + const char *s, sd_id128_t *ret + + + + + + + Description + + sd_id128_to_string() formats a 128-bit + ID as a character string. It expects the ID and a string array + capable of storing 33 characters. The ID will be formatted as 32 + lowercase hexadecimal digits and be terminated by a + NUL byte. + + sd_id128_from_string() implements the + reverse operation: it takes a 33 character string with 32 + hexadecimal digits (either lowercase or uppercase, terminated by + NUL) and parses them back into a 128-bit ID + returned in ret. Alternatively, this call + can also parse a 37-character string with a 128-bit ID formatted + as RFC UUID. + + For more information about the sd_id128_t + type see + sd-id1283. + Note that these calls operate the same way on all architectures, + i.e. the results do not depend on endianness. + + When formatting a 128-bit ID into a string, it is often + easier to use a format string for + printf3. + This is easily done using the + SD_ID128_FORMAT_STR and + SD_ID128_FORMAT_VAL() macros. For more + information see + sd-id1283. + + + + Return Value + + sd_id128_to_string() always succeeds + and returns a pointer to the string array passed in. + sd_id128_from_string returns 0 on success, in + which case ret is filled in, or a negative + errno-style error code. + + + + Notes + + The sd_id128_to_string() and + sd_id128_from_string() interfaces are + available as a shared library, which can be compiled and linked to + with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-id1283, + printf3 + + + + diff --git a/src/libsystemd/sd_is_fifo.xml b/src/libsystemd/sd_is_fifo.xml new file mode 100644 index 0000000000..627cb87aaf --- /dev/null +++ b/src/libsystemd/sd_is_fifo.xml @@ -0,0 +1,200 @@ + + + + + + + + + sd_is_fifo + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_is_fifo + 3 + + + + sd_is_fifo + sd_is_socket + sd_is_socket_inet + sd_is_socket_unix + sd_is_mq + sd_is_special + Check the type of a file descriptor + + + + + #include <systemd/sd-daemon.h> + + + int sd_is_fifo + int fd + const char *path + + + + int sd_is_socket + int fd + int family + int type + int listening + + + + int sd_is_socket_inet + int fd + int family + int type + int listening + uint16_t port + + + + int sd_is_socket_unix + int fd + int type + int listening + const char *path + size_t length + + + + int sd_is_mq + int fd + const char *path + + + + int sd_is_special + int fd + const char *path + + + + + + + Description + + sd_is_fifo() may be called to check + whether the specified file descriptor refers to a FIFO or pipe. If + the path parameter is not + NULL, it is checked whether the FIFO is bound + to the specified file system path. + + sd_is_socket() may be called to check + whether the specified file descriptor refers to a socket. If the + family parameter is not + AF_UNSPEC, it is checked whether the socket + is of the specified family (AF_UNIX, AF_INET, + ...). If the type parameter is not 0, it is + checked whether the socket is of the specified type + (SOCK_STREAM, + SOCK_DGRAM, ...). If the + listening parameter is positive, it is + checked whether the socket is in accepting mode, i.e. + listen() has been called for it. If + listening is 0, it is checked whether the + socket is not in this mode. If the parameter is negative, no such + check is made. The listening parameter + should only be used for stream sockets and should be set to a + negative value otherwise. + + sd_is_socket_inet() is similar to + sd_is_socket(), but optionally checks the + IPv4 or IPv6 port number the socket is bound to, unless + port is zero. For this call + family must be passed as either + AF_UNSPEC, AF_INET, or + AF_INET6. + + sd_is_socket_unix() is similar to + sd_is_socket() but optionally checks the + AF_UNIX path the socket is bound to, unless + the path parameter is + NULL. For normal file system + AF_UNIX sockets, set the + length parameter to 0. For Linux abstract + namespace sockets, set the length to the + size of the address, including the initial 0 byte, and set the + path to the initial 0 byte of the socket + address. + + sd_is_mq() may be called to check + whether the specified file descriptor refers to a POSIX message + queue. If the path parameter is not + NULL, it is checked whether the message queue + is bound to the specified name. + + sd_is_special() may be called to check + whether the specified file descriptor refers to a special file. If + the path parameter is not + NULL, it is checked whether the file + descriptor is bound to the specified file name. Special files in + this context are character device nodes and files in + /proc or /sys. + + + + Return Value + + On failure, these calls return a negative errno-style error + code. If the file descriptor is of the specified type and bound to + the specified address, a positive return value is returned, + otherwise zero. + + + + Notes + + + + Internally, these function use a combination of + fstat() and + getsockname() to check the file descriptor + type and where it is bound to. + + + + See Also + + systemd1, + sd-daemon3, + sd_listen_fds3, + systemd.service5, + systemd.socket5 + + + + diff --git a/src/libsystemd/sd_journal_add_match.xml b/src/libsystemd/sd_journal_add_match.xml new file mode 100644 index 0000000000..98415d53fd --- /dev/null +++ b/src/libsystemd/sd_journal_add_match.xml @@ -0,0 +1,216 @@ + + + + + + + + + sd_journal_add_match + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_add_match + 3 + + + + sd_journal_add_match + sd_journal_add_disjunction + sd_journal_add_conjunction + sd_journal_flush_matches + Add or remove entry matches + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_add_match + sd_journal *j + const void *data + size_t size + + + + int sd_journal_add_disjunction + sd_journal *j + + + + int sd_journal_add_conjunction + sd_journal *j + + + + void sd_journal_flush_matches + sd_journal *j + + + + + + Description + + sd_journal_add_match() adds a match by + which to filter the entries of the journal file. Matches applied + with this call will filter what can be iterated through and read + from the journal file via calls like + sd_journal_next3 + and + sd_journal_get_data3. + Parameter data must be of the form + FIELD=value, + where the FIELD part is a short uppercase string consisting only + of 0–9, A–Z and the underscore; it may not begin with two underscores or be the empty + string. The value part may be anything, including binary. Parameter + size specifies the number of bytes in data + (i.e. the length of FIELD, plus one, plus the length of + value). Parameter size may also be + specified as 0, in which case data + must be a NUL-terminated string, and the bytes before the terminating + zero are used as the match. + + If a match is applied, only entries with this field set + will be iterated. Multiple matches may be active at the same time: + If they apply to different fields, only entries with both fields + set like this will be iterated. If they apply to the same fields, + only entries where the field takes one of the specified values + will be iterated. Well known fields are documented in + systemd.journal-fields7. + Whenever a new match is added the current entry position is reset, + and + sd_journal_next3 + (or a similar call) needs to be called before entries can be read + again. + + sd_journal_add_disjunction() may be + used to insert a disjunction (i.e. logical OR) in the match list. + If this call is invoked, all previously added matches since the + last invocation of + sd_journal_add_disjunction() or + sd_journal_add_conjunction() are combined in + an OR with all matches added afterwards, until + sd_journal_add_disjunction() or + sd_journal_add_conjunction() is invoked again + to begin the next OR or AND term. + + sd_journal_add_conjunction() may be + used to insert a conjunction (i.e. logical AND) in the match list. + If this call is invoked, all previously added matches since the + last invocation of + sd_journal_add_conjunction() are combined in + an AND with all matches added afterwards, until + sd_journal_add_conjunction() is invoked again + to begin the next AND term. The combination of + sd_journal_add_match(), + sd_journal_add_disjunction() and + sd_journal_add_conjunction() may be used to + build complex search terms, even though full logical expressions + are not available. Note that + sd_journal_add_conjunction() operates one + level 'higher' than + sd_journal_add_disjunction(). It is hence + possible to build an expression of AND terms, consisting of OR + terms, consisting of AND terms, consisting of OR terms of matches + (the latter OR expression is implicitly created for matches with + the same field name, see above). + + sd_journal_flush_matches() may be used + to flush all matches, disjunction and conjunction terms again. + After this call all filtering is removed and all entries in the + journal will be iterated again. + + Note that filtering via matches only applies to the way the + journal is read, it has no effect on storage on disk. + + + + Return Value + + sd_journal_add_match(), + sd_journal_add_disjunction() and + sd_journal_add_conjunction() + return 0 on success or a negative errno-style error + code. sd_journal_flush_matches() + returns nothing. + + + + Notes + + The sd_journal_add_match(), + sd_journal_add_disjunction(), + sd_journal_add_conjunction() and + sd_journal_flush_matches() + interfaces are available as a shared library, which can + be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + Examples + + The following example adds matches to a journal context + object to iterate only through messages generated by the Avahi + service at the four error log levels, plus all messages of the + message ID 03bb1dab98ab4ecfbf6fff2738bdd964 coming from any + service (this example lacks the necessary error checking): + + ... +int add_matches(sd_journal *j) { + sd_journal_add_match(j, "_SYSTEMD_UNIT=avahi-daemon.service", 0); + sd_journal_add_match(j, "PRIORITY=0", 0); + sd_journal_add_match(j, "PRIORITY=1", 0); + sd_journal_add_match(j, "PRIORITY=2", 0); + sd_journal_add_match(j, "PRIORITY=3", 0); + sd_journal_add_disjunction(j); + sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964", 0); +} + + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_open3, + sd_journal_next3, + sd_journal_get_data3, + systemd.journal-fields7 + + + + diff --git a/src/libsystemd/sd_journal_enumerate_fields.xml b/src/libsystemd/sd_journal_enumerate_fields.xml new file mode 100644 index 0000000000..fa5884106b --- /dev/null +++ b/src/libsystemd/sd_journal_enumerate_fields.xml @@ -0,0 +1,161 @@ + + + + + + + + + sd_journal_enumerate_fields + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_enumerate_fields + 3 + + + + sd_journal_enumerate_fields + sd_journal_restart_fields + SD_JOURNAL_FOREACH_FIELD + Read used field names from the journal + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_enumerate_fields + sd_journal *j + const char **field + + + + void sd_journal_restart_fields + sd_journal *j + + + + SD_JOURNAL_FOREACH_FIELD + sd_journal *j + const char *field + + + + + + + Description + + sd_journal_enumerate_fields() may be used to iterate through all field names used in the + opened journal files. On each invocation the next field name is returned. The order of the returned field names is + not defined. It takes two arguments: the journal context object, plus a pointer to a constant string pointer where + the field name is stored in. The returned data is in a read-only memory map and is only valid until the next + invocation of sd_journal_enumerate_fields(). Note that this call is subject to the data field + size threshold as controlled by sd_journal_set_data_threshold(). + + sd_journal_restart_fields() resets the field name enumeration index to the beginning of + the list. The next invocation of sd_journal_enumerate_fields() will return the first field + name again. + + The SD_JOURNAL_FOREACH_FIELD() macro may be used as a handy wrapper around + sd_journal_restart_fields() and sd_journal_enumerate_fields(). + + These functions currently are not influenced by matches set with sd_journal_add_match() + but this might change in a later version of this software. + + To retrieve the possible values a specific field can take use + sd_journal_query_unique3. + + + + Return Value + + sd_journal_enumerate_fields() returns a + positive integer if the next field name has been read, 0 when no + more field names are known, or a negative errno-style error code. + sd_journal_restart_fields() returns + nothing. + + + + Notes + + The sd_journal_enumerate_fields() and sd_journal_restart_fields() + interfaces are available as a shared library, which can be compiled and linked to with the + libsystemd pkg-config1 file. + + + + Examples + + Use the SD_JOURNAL_FOREACH_FIELD macro to iterate through all field names in use in the + current journal. + + #include <stdio.h> +#include <string.h> +#include <systemd/sd-journal.h> + +int main(int argc, char *argv[]) { + sd_journal *j; + const char *field; + int r; + + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + SD_JOURNAL_FOREACH_FIELD(j, field) + printf("%s\n", field); + sd_journal_close(j); + return 0; +} + + + + + See Also + + + systemd1, + systemd.journal-fields7, + sd-journal3, + sd_journal_open3, + sd_journal_query_unique3, + sd_journal_get_data3, + sd_journal_add_match3 + + + + diff --git a/src/libsystemd/sd_journal_get_catalog.xml b/src/libsystemd/sd_journal_get_catalog.xml new file mode 100644 index 0000000000..c19eb11b20 --- /dev/null +++ b/src/libsystemd/sd_journal_get_catalog.xml @@ -0,0 +1,137 @@ + + + + + + + + + sd_journal_get_catalog + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_get_catalog + 3 + + + + sd_journal_get_catalog + sd_journal_get_catalog_for_message_id + Retrieve message catalog entry + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_get_catalog + sd_journal *j + char **ret + + + + int sd_journal_get_catalog_for_message_id + sd_id128_t id + char **ret + + + + + + + + Description + + sd_journal_get_catalog() retrieves a + message catalog entry for the current journal entry. This will + look up an entry in the message catalog by using the + MESSAGE_ID= field of the current journal entry. + Before returning the entry all journal field names in the catalog + entry text enclosed in "@" will be replaced by the respective + field values of the current entry. If a field name referenced in + the message catalog entry does not exist, in the current journal + entry, the "@" will be removed, but the field name otherwise left + untouched. + + sd_journal_get_catalog_for_message_id() + works similar to sd_journal_get_catalog() but + the entry is looked up by the specified message ID (no open + journal context is necessary for this), and no field substitution + is performed. + + For more information about the journal message catalog + please refer to the Journal + Message Catalogs documentation page. + + + + Return Value + + sd_journal_get_catalog() and + sd_journal_get_catalog_for_message_id() + return 0 on success or a negative errno-style error code. If no + matching message catalog entry is found, -ENOENT is + returned. + + On successful return, ret points to a + new string, which must be freed with + free3. + + + + + Notes + + The sd_journal_get_catalog() and + sd_journal_get_catalog_for_message_id() + interfaces are available as a shared library, which can be + compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + systemd.journal-fields7, + sd-journal3, + sd_journal_open3, + sd_journal_next3, + sd_journal_get_data3, + malloc3 + + + + diff --git a/src/libsystemd/sd_journal_get_cursor.xml b/src/libsystemd/sd_journal_get_cursor.xml new file mode 100644 index 0000000000..a400d8b1b5 --- /dev/null +++ b/src/libsystemd/sd_journal_get_cursor.xml @@ -0,0 +1,144 @@ + + + + + + + + + sd_journal_get_cursor + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_get_cursor + 3 + + + + sd_journal_get_cursor + sd_journal_test_cursor + Get cursor string for or test cursor string against the current journal entry + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_get_cursor + sd_journal *j + char **cursor + + + + int sd_journal_test_cursor + sd_journal *j + const char *cursor + + + + + + + Description + + sd_journal_get_cursor() returns a + cursor string for the current journal entry. A cursor is a + serialization of the current journal position formatted as text. + The string only contains printable characters and can be passed + around in text form. The cursor identifies a journal entry + globally and in a stable way and may be used to later seek to it + via + sd_journal_seek_cursor3. + The cursor string should be considered opaque and not be parsed by + clients. Seeking to a cursor position without the specific entry + being available locally will seek to the next closest (in terms of + time) available entry. The call takes two arguments: a journal + context object and a pointer to a string pointer where the cursor + string will be placed. The string is allocated via libc + malloc3 + and should be freed after use with + free3. + + Note that sd_journal_get_cursor() will + not work before + sd_journal_next3 + (or related call) has been called at least once, in order to + position the read pointer at a valid entry. + + sd_journal_test_cursor() + may be used to check whether the current position in + the journal matches the specified cursor. This is + useful since cursor strings do not uniquely identify + an entry: the same entry might be referred to by + multiple different cursor strings, and hence string + comparing cursors is not possible. Use this call to + verify after an invocation of + sd_journal_seek_cursor3 + whether the entry being sought to was actually found + in the journal or the next closest entry was used + instead. + + + + Return Value + + sd_journal_get_cursor() returns 0 on + success or a negative errno-style error code. + sd_journal_test_cursor() returns positive if + the current entry matches the specified cursor, 0 if it does not + match the specified cursor or a negative errno-style error code on + failure. + + + + Notes + + The sd_journal_get_cursor() and + sd_journal_test_cursor() interfaces are + available as a shared library, which can be compiled and linked to + with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_open3, + sd_journal_seek_cursor3 + + + + diff --git a/src/libsystemd/sd_journal_get_cutoff_realtime_usec.xml b/src/libsystemd/sd_journal_get_cutoff_realtime_usec.xml new file mode 100644 index 0000000000..23e7cc65e8 --- /dev/null +++ b/src/libsystemd/sd_journal_get_cutoff_realtime_usec.xml @@ -0,0 +1,145 @@ + + + + + + + + + sd_journal_get_cutoff_realtime_usec + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_get_cutoff_realtime_usec + 3 + + + + sd_journal_get_cutoff_realtime_usec + sd_journal_get_cutoff_monotonic_usec + Read cut-off timestamps from the current journal entry + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_get_cutoff_realtime_usec + sd_journal *j + uint64_t *from + uint64_t *to + + + + int sd_journal_get_cutoff_monotonic_usec + sd_journal *j + sd_id128_t boot_id + uint64_t *from + uint64_t *to + + + + + + + Description + + sd_journal_get_cutoff_realtime_usec() + retrieves the realtime (wallclock) timestamps of the first and + last entries accessible in the journal. It takes three arguments: + the journal context object j and two + pointers from and to + pointing at 64-bit unsigned integers to store the timestamps in. + The timestamps are in microseconds since the epoch, i.e. + CLOCK_REALTIME. Either one of the two + timestamp arguments may be passed as NULL in + case the timestamp is not needed, but not both. + + sd_journal_get_cutoff_monotonic_usec() + retrieves the monotonic timestamps of the first and last entries + accessible in the journal. It takes three arguments: the journal + context object j, a 128-bit identifier for + the boot boot_id, and two pointers to + 64-bit unsigned integers to store the timestamps, + from and to. The + timestamps are in microseconds since boot-up of the specific boot, + i.e. CLOCK_MONOTONIC. Since the monotonic + clock begins new with every reboot it only defines a well-defined + point in time when used together with an identifier identifying + the boot, see + sd_id128_get_boot3 + for more information. The function will return the timestamps for + the boot identified by the passed boot ID. Either one of the two + timestamp arguments may be passed as NULL in + case the timestamp is not needed, but not both. + + + + Return Value + + sd_journal_get_cutoff_realtime_usec() + and sd_journal_get_cutoff_monotonic_usec() + return 1 on success, 0 if not suitable entries are in the journal + or a negative errno-style error code. + + Locations pointed to by parameters + from and to will be + set only if the return value is positive, and obviously, the + parameters are non-null. + + + + Notes + + The + sd_journal_get_cutoff_realtime_usec() and + sd_journal_get_cutoff_monotonic_usec() + interfaces are available as a shared library, which can be + compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_open3, + sd_journal_get_realtime_usec3, + sd_id128_get_boot3, + clock_gettime2 + + + + diff --git a/src/libsystemd/sd_journal_get_data.xml b/src/libsystemd/sd_journal_get_data.xml new file mode 100644 index 0000000000..908ee7db16 --- /dev/null +++ b/src/libsystemd/sd_journal_get_data.xml @@ -0,0 +1,235 @@ + + + + + + + + + sd_journal_get_data + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_get_data + 3 + + + + sd_journal_get_data + sd_journal_enumerate_data + sd_journal_restart_data + SD_JOURNAL_FOREACH_DATA + sd_journal_set_data_threshold + sd_journal_get_data_threshold + Read data fields from the current journal entry + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_get_data + sd_journal *j + const char *field + const void **data + size_t *length + + + + int sd_journal_enumerate_data + sd_journal *j + const void **data + size_t *length + + + + void sd_journal_restart_data + sd_journal *j + + + + SD_JOURNAL_FOREACH_DATA + sd_journal *j + const void *data + size_t length + + + + int sd_journal_set_data_threshold + sd_journal *j + size_t sz + + + + int sd_journal_get_data_threshold + sd_journal *j + size_t *sz + + + + + + Description + + sd_journal_get_data() gets the data + object associated with a specific field from the current journal + entry. It takes four arguments: the journal context object, a + string with the field name to request, plus a pair of pointers to + pointer/size variables where the data object and its size shall be + stored in. The field name should be an entry field name. + Well-known field names are listed in + systemd.journal-fields7. + The returned data is in a read-only memory map and is only valid + until the next invocation of + sd_journal_get_data() or + sd_journal_enumerate_data(), or the read + pointer is altered. Note that the data returned will be prefixed + with the field name and '='. Also note that, by default, data fields + larger than 64K might get truncated to 64K. This threshold may be + changed and turned off with + sd_journal_set_data_threshold() (see + below). + + sd_journal_enumerate_data() may be used + to iterate through all fields of the current entry. On each + invocation the data for the next field is returned. The order of + these fields is not defined. The data returned is in the same + format as with sd_journal_get_data() and also + follows the same life-time semantics. + + sd_journal_restart_data() resets the + data enumeration index to the beginning of the entry. The next + invocation of sd_journal_enumerate_data() + will return the first field of the entry again. + + Note that the SD_JOURNAL_FOREACH_DATA() + macro may be used as a handy wrapper around + sd_journal_restart_data() and + sd_journal_enumerate_data(). + + Note that these functions will not work before + sd_journal_next3 + (or related call) has been called at least once, in order to + position the read pointer at a valid entry. + + sd_journal_set_data_threshold() may be + used to change the data field size threshold for data returned by + sd_journal_get_data(), + sd_journal_enumerate_data() and + sd_journal_enumerate_unique(). This threshold + is a hint only: it indicates that the client program is interested + only in the initial parts of the data fields, up to the threshold + in size — but the library might still return larger data objects. + That means applications should not rely exclusively on this + setting to limit the size of the data fields returned, but need to + apply a explicit size limit on the returned data as well. This + threshold defaults to 64K by default. To retrieve the complete + data fields this threshold should be turned off by setting it to + 0, so that the library always returns the complete data objects. + It is recommended to set this threshold as low as possible since + this relieves the library from having to decompress large + compressed data objects in full. + + sd_journal_get_data_threshold() returns + the currently configured data field size threshold. + + + + Return Value + + sd_journal_get_data() returns 0 on + success or a negative errno-style error code. If the current entry + does not include the specified field, -ENOENT is returned. If + sd_journal_next3 + has not been called at least once, -EADDRNOTAVAIL is returned. + sd_journal_enumerate_data() returns a + positive integer if the next field has been read, 0 when no more + fields are known, or a negative errno-style error code. + sd_journal_restart_data() returns nothing. + sd_journal_set_data_threshold() and + sd_journal_get_threshold() return 0 on + success or a negative errno-style error code. + + + + Notes + + The sd_journal_get_data(), + sd_journal_enumerate_data(), + sd_journal_restart_data(), + sd_journal_set_data_threshold() and + sd_journal_get_data_threshold() interfaces + are available as a shared library, which can be compiled and + linked to with the + libsystemd pkg-config1 + file. + + + + Examples + + See + sd_journal_next3 + for a complete example how to use + sd_journal_get_data(). + + Use the + SD_JOURNAL_FOREACH_DATA macro to + iterate through all fields of the current journal + entry: + + ... +int print_fields(sd_journal *j) { + const void *data; + size_t length; + SD_JOURNAL_FOREACH_DATA(j, data, length) + printf("%.*s\n", (int) length, data); +} +... + + + + + See Also + + + systemd1, + systemd.journal-fields7, + sd-journal3, + sd_journal_open3, + sd_journal_next3, + sd_journal_get_realtime_usec3, + sd_journal_query_unique3 + + + + diff --git a/src/libsystemd/sd_journal_get_fd.xml b/src/libsystemd/sd_journal_get_fd.xml new file mode 100644 index 0000000000..61293f7f99 --- /dev/null +++ b/src/libsystemd/sd_journal_get_fd.xml @@ -0,0 +1,332 @@ + + + + + + + + + sd_journal_get_fd + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_get_fd + 3 + + + + sd_journal_get_fd + sd_journal_get_events + sd_journal_get_timeout + sd_journal_process + sd_journal_wait + sd_journal_reliable_fd + SD_JOURNAL_NOP + SD_JOURNAL_APPEND + SD_JOURNAL_INVALIDATE + Journal change notification + interface + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_get_fd + sd_journal *j + + + + int sd_journal_get_events + sd_journal *j + + + + int sd_journal_get_timeout + sd_journal *j + uint64_t *timeout_usec + + + + int sd_journal_process + sd_journal *j + + + + int sd_journal_wait + sd_journal *j + uint64_t timeout_usec + + + + int sd_journal_reliable_fd + sd_journal *j + + + + + + + Description + + sd_journal_get_fd() returns a file + descriptor that may be asynchronously polled in an external event + loop and is signaled as soon as the journal changes, because new + entries or files were added, rotation took place, or files have + been deleted, and similar. The file descriptor is suitable for + usage in + poll2. + Use sd_journal_get_events() for an events + mask to watch for. The call takes one argument: the journal + context object. Note that not all file systems are capable of + generating the necessary events for wakeups from this file + descriptor for changes to be noticed immediately. In particular + network files systems do not generate suitable file change events + in all cases. Cases like this can be detected with + sd_journal_reliable_fd(), below. + sd_journal_get_timeout() will ensure in these + cases that wake-ups happen frequently enough for changes to be + noticed, although with a certain latency. + + sd_journal_get_events() will return the + poll() mask to wait for. This function will + return a combination of POLLIN and + POLLOUT and similar to fill into the + .events field of struct + pollfd. + + sd_journal_get_timeout() will return a + timeout value for usage in poll(). This + returns a value in microseconds since the epoch of + CLOCK_MONOTONIC for timing out + poll() in timeout_usec. + See + clock_gettime2 + for details about CLOCK_MONOTONIC. If there + is no timeout to wait for, this will fill in (uint64_t) + -1 instead. Note that poll() takes + a relative timeout in milliseconds rather than an absolute timeout + in microseconds. To convert the absolute 'us' timeout into + relative 'ms', use code like the following: + + uint64_t t; +int msec; +sd_journal_get_timeout(m, &t); +if (t == (uint64_t) -1) + msec = -1; +else { + struct timespec ts; + uint64_t n; + clock_getttime(CLOCK_MONOTONIC, &ts); + n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; + msec = t > n ? (int) ((t - n + 999) / 1000) : 0; +} + + The code above does not do any error checking for brevity's + sake. The calculated msec integer can be passed + directly as poll()'s timeout + parameter. + + After each poll() wake-up + sd_journal_process() needs to be called to + process events. This call will also indicate what kind of change + has been detected (see below; note that spurious wake-ups are + possible). + + A synchronous alternative for using + sd_journal_get_fd(), + sd_journal_get_events(), + sd_journal_get_timeout() and + sd_journal_process() is + sd_journal_wait(). It will synchronously wait + until the journal gets changed. The maximum time this call sleeps + may be controlled with the timeout_usec + parameter. Pass (uint64_t) -1 to wait + indefinitely. Internally this call simply combines + sd_journal_get_fd(), + sd_journal_get_events(), + sd_journal_get_timeout(), + poll() and + sd_journal_process() into one. + + sd_journal_reliable_fd() may be used to + check whether the wakeup events from the file descriptor returned + by sd_journal_get_fd() are known to be + immediately triggered. On certain file systems where file change + events from the OS are not available (such as NFS) changes need to + be polled for repeatedly, and hence are detected only with a + certain latency. This call will return a positive value if the + journal changes are detected immediately and zero when they need + to be polled for and hence might be noticed only with a certain + latency. Note that there is usually no need to invoke this function + directly as sd_journal_get_timeout() on these + file systems will ask for timeouts explicitly anyway. + + + + Return Value + + sd_journal_get_fd() returns a valid + file descriptor on success or a negative errno-style error + code. + + sd_journal_get_events() returns a + combination of POLLIN, + POLLOUT and suchlike on success or a negative + errno-style error code. + + sd_journal_reliable_fd() returns a + positive integer if the file descriptor returned by + sd_journal_get_fd() will generate wake-ups + immediately for all journal changes. Returns 0 if there might be a + latency involved. + + sd_journal_process() and + sd_journal_wait() return one of + SD_JOURNAL_NOP, + SD_JOURNAL_APPEND or + SD_JOURNAL_INVALIDATE on success or a + negative errno-style error code. If + SD_JOURNAL_NOP is returned, the journal did + not change since the last invocation. If + SD_JOURNAL_APPEND is returned, new entries + have been appended to the end of the journal. If + SD_JOURNAL_INVALIDATE, journal files were + added or removed (possibly due to rotation). In the latter event, + live-view UIs should probably refresh their entire display, while + in the case of SD_JOURNAL_APPEND, it is + sufficient to simply continue reading at the previous end of the + journal. + + + + Notes + + The sd_journal_get_fd(), + sd_journal_get_events(), + sd_journal_reliable_fd(), + sd_journal_process() and + sd_journal_wait() interfaces are available as + a shared library, which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + Examples + + Iterating through the journal, in a live view tracking all + changes: + + #include <stdio.h> +#include <string.h> +#include <systemd/sd-journal.h> + +int main(int argc, char *argv[]) { + int r; + sd_journal *j; + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + for (;;) { + const void *d; + size_t l; + r = sd_journal_next(j); + if (r < 0) { + fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r)); + break; + } + if (r == 0) { + /* Reached the end, let's wait for changes, and try again */ + r = sd_journal_wait(j, (uint64_t) -1); + if (r < 0) { + fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r)); + break; + } + continue; + } + r = sd_journal_get_data(j, "MESSAGE", &d, &l); + if (r < 0) { + fprintf(stderr, "Failed to read message field: %s\n", strerror(-r)); + continue; + } + printf("%.*s\n", (int) l, (const char*) d); + } + sd_journal_close(j); + return 0; +} + + Waiting with poll() (this + example lacks all error checking for the sake of + simplicity): + + #include <poll.h> +#include <systemd/sd-journal.h> + +int wait_for_changes(sd_journal *j) { + struct pollfd pollfd; + int msec; + + sd_journal_get_timeout(m, &t); + if (t == (uint64_t) -1) + msec = -1; + else { + struct timespec ts; + uint64_t n; + clock_getttime(CLOCK_MONOTONIC, &ts); + n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; + msec = t > n ? (int) ((t - n + 999) / 1000) : 0; + } + + pollfd.fd = sd_journal_get_fd(j); + pollfd.events = sd_journal_get_events(j); + poll(&pollfd, 1, msec); + return sd_journal_process(j); +} + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_open3, + sd_journal_next3, + poll2, + clock_gettime2 + + + + diff --git a/src/libsystemd/sd_journal_get_realtime_usec.xml b/src/libsystemd/sd_journal_get_realtime_usec.xml new file mode 100644 index 0000000000..607d74666b --- /dev/null +++ b/src/libsystemd/sd_journal_get_realtime_usec.xml @@ -0,0 +1,141 @@ + + + + + + + + + sd_journal_get_realtime_usec + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_get_realtime_usec + 3 + + + + sd_journal_get_realtime_usec + sd_journal_get_monotonic_usec + Read timestamps from the current journal entry + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_get_realtime_usec + sd_journal *j + uint64_t *usec + + + + int sd_journal_get_monotonic_usec + sd_journal *j + uint64_t *usec + sd_id128_t *boot_id + + + + + + + Description + + sd_journal_get_realtime_usec() gets the + realtime (wallclock) timestamp of the current journal entry. It + takes two arguments: the journal context object and a pointer to a + 64-bit unsigned integer to store the timestamp in. The timestamp + is in microseconds since the epoch, i.e. + CLOCK_REALTIME. + + sd_journal_get_monotonic_usec() gets + the monotonic timestamp of the current journal entry. It takes + three arguments: the journal context object, a pointer to a 64-bit + unsigned integer to store the timestamp in, as well as a 128-bit + ID buffer to store the boot ID of the monotonic timestamp. The + timestamp is in microseconds since boot-up of the specific boot, + i.e. CLOCK_MONOTONIC. Since the monotonic + clock begins new with every reboot, it only defines a well-defined + point in time when used together with an identifier identifying + the boot. See + sd_id128_get_boot3 + for more information. If the boot ID parameter is passed + NULL, the function will fail if the monotonic + timestamp of the current entry is not of the current system + boot. + + Note that these functions will not work before + sd_journal_next3 + (or related call) has been called at least + once, in order to position the read pointer at a valid entry. + + + + Return Value + + sd_journal_get_realtime_usec() and + sd_journal_get_monotonic_usec() returns 0 on + success or a negative errno-style error code. If the boot ID + parameter was passed NULL and the monotonic + timestamp of the current journal entry is not of the current + system boot, -ESTALE is returned by + sd_journal_get_monotonic_usec(). + + + + Notes + + The sd_journal_get_realtime_usec() and + sd_journal_get_monotonic_usec() interfaces + are available as a shared library, which can be compiled and + linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_open3, + sd_journal_next3, + sd_journal_get_data3, + sd_id128_get_boot3, + clock_gettime2, + sd_journal_get_cutoff_realtime_usec3 + + + + diff --git a/src/libsystemd/sd_journal_get_usage.xml b/src/libsystemd/sd_journal_get_usage.xml new file mode 100644 index 0000000000..72c804d834 --- /dev/null +++ b/src/libsystemd/sd_journal_get_usage.xml @@ -0,0 +1,100 @@ + + + + + + + + + sd_journal_get_usage + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_get_usage + 3 + + + + sd_journal_get_usage + Journal disk usage + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_get_usage + sd_journal *j + uint64_t *bytes + + + + + + + Description + + sd_journal_get_usage() determines the + total disk space currently used by journal files (in bytes). If + SD_JOURNAL_LOCAL_ONLY was passed when opening + the journal, this value will only reflect the size of journal + files of the local host, otherwise of all hosts. + + + + Return Value + + sd_journal_get_usage() returns 0 on + success or a negative errno-style error code. + + + + Notes + + The sd_journal_get_usage() interface is + available as a shared library, which can be compiled and linked to + with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_open3, + + + + diff --git a/src/libsystemd/sd_journal_has_runtime_files.xml b/src/libsystemd/sd_journal_has_runtime_files.xml new file mode 100644 index 0000000000..237e649206 --- /dev/null +++ b/src/libsystemd/sd_journal_has_runtime_files.xml @@ -0,0 +1,95 @@ + + + + + + + + + sd_journal_has_runtime_files + systemd + + + + Developer + Jan + Synáček + jan.synacek@gmail.com + + + + + + sd_journal_has_runtime_files + 3 + + + + sd_journal_has_runtime_files + sd_journal_has_persistent_files + Query availability of runtime or persistent journal files. + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_has_runtime_files + sd_journal *j + + + + int sd_journal_has_persistent_files + sd_journal *j + + + + + + + Description + + sd_journal_has_runtime_files() returns a positive value + if runtime journal files (present in /run/systemd/journal/) have been found. + Otherwise returns 0. + + sd_journal_has_persistent_files() returns a positive value + if persistent journal files (present in /var/log/journal/) have been found. + Otherwise returns 0. + + + + Return value + Both sd_journal_has_runtime_files() + and sd_journal_has_persistent_files() return -EINVAL + if their argument is NULL. + + + + + See Also + + sd-journal3 + + + + diff --git a/src/libsystemd/sd_journal_next.xml b/src/libsystemd/sd_journal_next.xml new file mode 100644 index 0000000000..115fe26661 --- /dev/null +++ b/src/libsystemd/sd_journal_next.xml @@ -0,0 +1,207 @@ + + + + + + + + + sd_journal_next + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_next + 3 + + + + sd_journal_next + sd_journal_previous + sd_journal_next_skip + sd_journal_previous_skip + SD_JOURNAL_FOREACH + SD_JOURNAL_FOREACH_BACKWARDS + Advance or set back the read pointer in the journal + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_next + sd_journal *j + + + + int sd_journal_previous + sd_journal *j + + + + int sd_journal_next_skip + sd_journal *j + uint64_t skip + + + + int sd_journal_previous_skip + sd_journal *j + uint64_t skip + + + + SD_JOURNAL_FOREACH + sd_journal *j + + + + SD_JOURNAL_FOREACH_BACKWARDS + sd_journal *j + + + + + + Description + + sd_journal_next() advances the read + pointer into the journal by one entry. The only argument taken is + a journal context object as allocated via + sd_journal_open3. + After successful invocation the entry may be read with functions + such as + sd_journal_get_data3. + + Similarly, sd_journal_previous() sets + the read pointer back one entry. + + sd_journal_next_skip() and + sd_journal_previous_skip() advance/set back + the read pointer by multiple entries at once, as specified in the + skip parameter. + + The journal is strictly ordered by reception time, and hence + advancing to the next entry guarantees that the entry then + pointing to is later in time than then previous one, or has the + same timestamp. + + Note that + sd_journal_get_data3 + and related calls will fail unless + sd_journal_next() has been invoked at least + once in order to position the read pointer on a journal + entry. + + Note that the SD_JOURNAL_FOREACH() + macro may be used as a wrapper around + sd_journal_seek_head3 + and sd_journal_next() in order to make + iterating through the journal easier. See below for an example. + Similarly, SD_JOURNAL_FOREACH_BACKWARDS() may + be used for iterating the journal in reverse order. + + + + Return Value + + The four calls return the number of entries advanced/set + back on success or a negative errno-style error code. When the end + or beginning of the journal is reached, a number smaller than + requested is returned. More specifically, if + sd_journal_next() or + sd_journal_previous() reach the end/beginning + of the journal they will return 0, instead of 1 when they are + successful. This should be considered an EOF marker. + + + + Notes + + The sd_journal_next(), + sd_journal_previous(), + sd_journal_next_skip() and + sd_journal_previous_skip() interfaces are + available as a shared library, which can be compiled and linked to + with the + libsystemd pkg-config1 + file. + + + + Examples + + Iterating through the journal: + + #include <stdio.h> +#include <string.h> +#include <systemd/sd-journal.h> + +int main(int argc, char *argv[]) { + int r; + sd_journal *j; + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + SD_JOURNAL_FOREACH(j) { + const char *d; + size_t l; + + r = sd_journal_get_data(j, "MESSAGE", (const void **)&d, &l); + if (r < 0) { + fprintf(stderr, "Failed to read message field: %s\n", strerror(-r)); + continue; + } + + printf("%.*s\n", (int) l, d); + } + sd_journal_close(j); + return 0; +} + + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_open3, + sd_journal_get_data3, + sd_journal_get_realtime_usec3, + sd_journal_get_cursor3 + + + + diff --git a/src/libsystemd/sd_journal_open.xml b/src/libsystemd/sd_journal_open.xml new file mode 100644 index 0000000000..153af2387f --- /dev/null +++ b/src/libsystemd/sd_journal_open.xml @@ -0,0 +1,228 @@ + + + + + + + + + sd_journal_open + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_open + 3 + + + + sd_journal_open + sd_journal_open_directory + sd_journal_open_directory_fd + sd_journal_open_files + sd_journal_open_files_fd + sd_journal_close + sd_journal + SD_JOURNAL_LOCAL_ONLY + SD_JOURNAL_RUNTIME_ONLY + SD_JOURNAL_SYSTEM + SD_JOURNAL_CURRENT_USER + SD_JOURNAL_OS_ROOT + Open the system journal for reading + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_open + sd_journal **ret + int flags + + + + int sd_journal_open_directory + sd_journal **ret + const char *path + int flags + + + + int sd_journal_open_directory_fd + sd_journal **ret + int fd + int flags + + + + int sd_journal_open_files + sd_journal **ret + const char **paths + int flags + + + + int sd_journal_open_files_fd + sd_journal **ret + int fds[] + unsigned n_fds + int flags + + + + void sd_journal_close + sd_journal *j + + + + + + Description + + sd_journal_open() opens the log journal + for reading. It will find all journal files automatically and + interleave them automatically when reading. As first argument it + takes a pointer to a sd_journal pointer, which, + on success, will contain a journal context object. The second + argument is a flags field, which may consist of the following + flags ORed together: SD_JOURNAL_LOCAL_ONLY + makes sure only journal files generated on the local machine will + be opened. SD_JOURNAL_RUNTIME_ONLY makes sure + only volatile journal files will be opened, excluding those which + are stored on persistent storage. + SD_JOURNAL_SYSTEM will cause journal files of + system services and the kernel (in opposition to user session + processes) to be opened. + SD_JOURNAL_CURRENT_USER will cause journal + files of the current user to be opened. If neither + SD_JOURNAL_SYSTEM nor + SD_JOURNAL_CURRENT_USER are specified, all + journal file types will be opened. + + sd_journal_open_directory() is similar to sd_journal_open() but + takes an absolute directory path as argument. All journal files in this directory will be opened and interleaved + automatically. This call also takes a flags argument. The only flags parameter accepted by this call is + SD_JOURNAL_OS_ROOT. If specified, the journal files are searched below the usual + /var/log/journal and /run/log/journal relative to the specified path, + instead of directly beneath it. + + sd_journal_open_directory_fd() is similar to + sd_journal_open_directory(), but takes a file descriptor referencing a directory in the file + system instead of an absolute file system path. + + sd_journal_open_files() is similar to sd_journal_open() but takes a + NULL-terminated list of file paths to open. All files will be opened and interleaved + automatically. This call also takes a flags argument, but it must be passed as 0 as no flags are currently + understood for this call. Please note that in the case of a live journal, this function is only useful for + debugging, because individual journal files can be rotated at any moment, and the opening of specific files is + inherently racy. + + sd_journal_open_files_fd() is similar to sd_journal_open_files() + but takes an array of open file descriptors that must reference journal files, instead of an array of file system + paths. Pass the array of file descriptors as second argument, and the number of array entries in the third. The + flags parameter must be passed as 0. + + sd_journal objects cannot be used in the + child after a fork. Functions which take a journal object as an + argument (sd_journal_next() and others) will + return -ECHILD after a fork. + + + sd_journal_close() will close the + journal context allocated with + sd_journal_open() or + sd_journal_open_directory() and free its + resources. + + When opening the journal only journal files accessible to + the calling user will be opened. If journal files are not + accessible to the caller, this will be silently ignored. + + See + sd_journal_next3 + for an example of how to iterate through the journal after opening + it with sd_journal_open(). + + A journal context object returned by + sd_journal_open() references a specific + journal entry as current entry, similar to a + file seek index in a classic file system file, but without + absolute positions. It may be altered with + sd_journal_next3 + and + sd_journal_seek_head3 + and related calls. The current entry position may be exported in + cursor strings, as accessible via + sd_journal_get_cursor3. + Cursor strings may be used to globally identify a specific journal + entry in a stable way and then later to seek to it (or if the + specific entry is not available locally, to its closest entry in + time) + sd_journal_seek_cursor3. + + Notification of journal changes is available via + sd_journal_get_fd() and related calls. + + + + Return Value + + The sd_journal_open(), + sd_journal_open_directory(), and + sd_journal_open_files() calls return 0 on + success or a negative errno-style error code. + sd_journal_close() returns nothing. + + + + Notes + + The sd_journal_open(), + sd_journal_open_directory() and + sd_journal_close() interfaces are available + as a shared library, which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_next3, + sd_journal_get_data3, + systemd-machined8 + + + + diff --git a/src/libsystemd/sd_journal_print.xml b/src/libsystemd/sd_journal_print.xml new file mode 100644 index 0000000000..17fdc9c1f2 --- /dev/null +++ b/src/libsystemd/sd_journal_print.xml @@ -0,0 +1,260 @@ + + + + + + + + + sd_journal_print + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_print + 3 + + + + sd_journal_print + sd_journal_printv + sd_journal_send + sd_journal_sendv + sd_journal_perror + SD_JOURNAL_SUPPRESS_LOCATION + Submit log entries to the journal + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_print + int priority + const char *format + ... + + + + int sd_journal_printv + int priority + const char *format + va_list ap + + + + int sd_journal_send + const char *format + ... + + + + int sd_journal_sendv + const struct iovec *iov + int n + + + + int sd_journal_perror + const char *message + + + + + + + Description + + sd_journal_print() may be used to + submit simple, plain text log entries to the system journal. The + first argument is a priority value. This is followed by a format + string and its parameters, similar to + printf3 + or + syslog3. + The priority value is one of + LOG_EMERG, + LOG_ALERT, + LOG_CRIT, + LOG_ERR, + LOG_WARNING, + LOG_NOTICE, + LOG_INFO, + LOG_DEBUG, as defined in + syslog.h, see + syslog3 + for details. It is recommended to use this call to submit log + messages in the application locale or system locale and in UTF-8 + format, but no such restrictions are enforced. + + sd_journal_printv() is similar to + sd_journal_print() but takes a variable + argument list encapsulated in an object of type + va_list (see + stdarg3 + for more information) instead of the format string. It is + otherwise equivalent in behavior. + + sd_journal_send() may be used to submit + structured log entries to the system journal. It takes a series of + format strings, each immediately followed by their associated + parameters, terminated by NULL. The strings + passed should be of the format VARIABLE=value. + The variable name must be in uppercase and consist only of + characters, numbers and underscores, and may not begin with an + underscore. (All assignments that do not follow this syntax will + be ignored.) The value can be of any size and format. It is highly + recommended to submit text strings formatted in the UTF-8 + character encoding only, and submit binary fields only when + formatting in UTF-8 strings is not sensible. A number of + well-known fields are defined, see + systemd.journal-fields7 + for details, but additional application defined fields may be + used. A variable may be assigned more than one value per + entry. + + sd_journal_sendv() is similar to + sd_journal_send() but takes an array of + struct iovec (as defined in + uio.h, see + readv3 + for details) instead of the format string. Each structure should + reference one field of the entry to submit. The second argument + specifies the number of structures in the array. + sd_journal_sendv() is particularly useful to + submit binary objects to the journal where that is + necessary. + + sd_journal_perror() is a similar to + perror3 + and writes a message to the journal that consists of the passed + string, suffixed with ": " and a human-readable representation of + the current error code stored in + errno3. + If the message string is passed as NULL or + empty string, only the error string representation will be + written, prefixed with nothing. An additional journal field ERRNO= + is included in the entry containing the numeric error code + formatted as decimal string. The log priority used is + LOG_ERR (3). + + Note that sd_journal_send() is a + wrapper around sd_journal_sendv() to make it + easier to use when only text strings shall be submitted. Also, the + following two calls are mostly equivalent: + + sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid()); + +sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(), + "PRIORITY=%i", LOG_INFO, + NULL); + + Note that these calls implicitly add fields for the source + file, function name and code line where invoked. This is + implemented with macros. If this is not desired, it can be turned + off by defining SD_JOURNAL_SUPPRESS_LOCATION before including + sd-journal.h. + + syslog3 + and sd_journal_print() may + largely be used interchangeably + functionality-wise. However, note that log messages + logged via the former take a different path to the + journal server than the later, and hence global + chronological ordering between the two streams cannot + be guaranteed. Using + sd_journal_print() has the + benefit of logging source code line, filenames, and + functions as metadata along all entries, and + guaranteeing chronological ordering with structured + log entries that are generated via + sd_journal_send(). Using + syslog() has the benefit of being + more portable. + + + + Return Value + + The four calls return 0 on success or a negative errno-style + error code. The + errno3 + variable itself is not altered. + + If + systemd-journald8 + is not running (the socket is not present), those functions do + nothing, and also return 0. + + + + Async signal safety + sd_journal_sendv() is "async signal + safe" in the meaning of + signal7. + + + sd_journal_print, + sd_journal_printv, + sd_journal_send, and + sd_journal_perror are + not async signal safe. + + + + Notes + + The sd_journal_print(), + sd_journal_printv(), + sd_journal_send() and + sd_journal_sendv() interfaces are available + as a shared library, which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_stream_fd3, + syslog3, + perror3, + errno3, + systemd.journal-fields7, + signal7, + socket7 + + + + diff --git a/src/libsystemd/sd_journal_query_unique.xml b/src/libsystemd/sd_journal_query_unique.xml new file mode 100644 index 0000000000..dbff55c105 --- /dev/null +++ b/src/libsystemd/sd_journal_query_unique.xml @@ -0,0 +1,212 @@ + + + + + + + + + sd_journal_query_unique + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_query_unique + 3 + + + + sd_journal_query_unique + sd_journal_enumerate_unique + sd_journal_restart_unique + SD_JOURNAL_FOREACH_UNIQUE + Read unique data fields from the journal + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_query_unique + sd_journal *j + const char *field + + + + int sd_journal_enumerate_unique + sd_journal *j + const void **data + size_t *length + + + + void sd_journal_restart_unique + sd_journal *j + + + + SD_JOURNAL_FOREACH_UNIQUE + sd_journal *j + const void *data + size_t length + + + + + + + Description + + sd_journal_query_unique() queries the + journal for all unique values the specified field can take. It + takes two arguments: the journal to query and the field name to + look for. Well-known field names are listed on + systemd.journal-fields7. + Field names must be specified without a trailing '='. After this + function has been executed successfully the field values may be + queried using sd_journal_enumerate_unique(). + Invoking this call a second time will change the field name being + queried and reset the enumeration index to the first field value + that matches. + + sd_journal_enumerate_unique() may be + used to iterate through all data fields which match the previously + selected field name as set with + sd_journal_query_unique(). On each invocation + the next field data matching the field name is returned. The order + of the returned data fields is not defined. It takes three + arguments: the journal context object, plus a pair of pointers to + pointer/size variables where the data object and its size shall be + stored in. The returned data is in a read-only memory map and is + only valid until the next invocation of + sd_journal_enumerate_unique(). Note that the + data returned will be prefixed with the field name and '='. Note + that this call is subject to the data field size threshold as + controlled by + sd_journal_set_data_threshold(). + + sd_journal_restart_unique() resets the + data enumeration index to the beginning of the list. The next + invocation of sd_journal_enumerate_unique() + will return the first field data matching the field name + again. + + Note that the + SD_JOURNAL_FOREACH_UNIQUE() macro may be used + as a handy wrapper around + sd_journal_restart_unique() and + sd_journal_enumerate_unique(). + + Note that these functions currently are not influenced by + matches set with sd_journal_add_match() but + this might change in a later version of this software. + + To enumerate all field names currently in use (and thus all suitable field parameters for + sd_journal_query_unique()), use the + sd_journal_enumerate_fields3 + call. + + + + Return Value + + sd_journal_query_unique() returns 0 on + success or a negative errno-style error code. + sd_journal_enumerate_unique() returns a + positive integer if the next field data has been read, 0 when no + more fields are known, or a negative errno-style error code. + sd_journal_restart_unique() returns + nothing. + + + + Notes + + The sd_journal_query_unique(), + sd_journal_enumerate_unique() and + sd_journal_restart_unique() interfaces are + available as a shared library, which can be compiled and linked to + with the + libsystemd pkg-config1 + file. + + + + Examples + + Use the SD_JOURNAL_FOREACH_UNIQUE macro + to iterate through all values a field of the journal can take. The + following example lists all unit names referenced in the + journal: + + #include <stdio.h> +#include <string.h> +#include <systemd/sd-journal.h> + +int main(int argc, char *argv[]) { + sd_journal *j; + const void *d; + size_t l; + int r; + + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + r = sd_journal_query_unique(j, "_SYSTEMD_UNIT"); + if (r < 0) { + fprintf(stderr, "Failed to query journal: %s\n", strerror(-r)); + return 1; + } + SD_JOURNAL_FOREACH_UNIQUE(j, d, l) + printf("%.*s\n", (int) l, (const char*) d); + sd_journal_close(j); + return 0; +} + + + + + See Also + + + systemd1, + systemd.journal-fields7, + sd-journal3, + sd_journal_open3, + sd_journal_enumerate_fields3, + sd_journal_get_data3, + sd_journal_add_match3 + + + + diff --git a/src/libsystemd/sd_journal_seek_head.xml b/src/libsystemd/sd_journal_seek_head.xml new file mode 100644 index 0000000000..d74c2d5bbc --- /dev/null +++ b/src/libsystemd/sd_journal_seek_head.xml @@ -0,0 +1,172 @@ + + + + + + + + + sd_journal_seek_head + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_seek_head + 3 + + + + sd_journal_seek_head + sd_journal_seek_tail + sd_journal_seek_monotonic_usec + sd_journal_seek_realtime_usec + sd_journal_seek_cursor + Seek to a position in the + journal + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_seek_head + sd_journal *j + + + + int sd_journal_seek_tail + sd_journal *j + + + + int sd_journal_seek_monotonic_usec + sd_journal *j + sd_id128_t boot_id + uint64_t usec + + + + int sd_journal_seek_realtime_usec + sd_journal *j + uint64_t usec + + + + int sd_journal_seek_cursor + sd_journal *j + const char *cursor + + + + + + Description + + sd_journal_seek_head() seeks to the + beginning of the journal, i.e. the oldest available entry. + + Similarly, sd_journal_seek_tail() may + be used to seek to the end of the journal, i.e. the most recent + available entry. + + sd_journal_seek_monotonic_usec() seeks + to the entry with the specified monotonic timestamp, i.e. + CLOCK_MONOTONIC. Since monotonic time + restarts on every reboot a boot ID needs to be specified as + well. + + sd_journal_seek_realtime_usec() seeks + to the entry with the specified realtime (wallclock) timestamp, + i.e. CLOCK_REALTIME. Note that the realtime + clock is not necessarily monotonic. If a realtime timestamp is + ambiguous, it is not defined which position is sought to. + + sd_journal_seek_cursor() seeks to the + entry located at the specified cursor string. For details on + cursors, see + sd_journal_get_cursor3. + If no entry matching the specified cursor is found the call will + seek to the next closest entry (in terms of time) instead. To + verify whether the newly selected entry actually matches the + cursor, use + sd_journal_test_cursor3. + + Note that these calls do not actually make any entry the new + current entry, this needs to be done in a separate step with a + subsequent + sd_journal_next3 + invocation (or a similar call). Only then, entry data may be + retrieved via + sd_journal_get_data3. + If no entry exists that matches exactly the specified seek + address, the next closest is sought to. If + sd_journal_next3 + is used, the closest following entry will be sought to, if + sd_journal_previous3 + is used the closest preceding entry is sought to. + + + + Return Value + + The functions return 0 on success or a negative errno-style + error code. + + + + Notes + + The sd_journal_seek_head(), + sd_journal_seek_tail(), + sd_journal_seek_monotonic_usec(), + sd_journal_seek_realtime_usec(), + and sd_journal_seek_cursor() + interfaces are available as a shared library, which can + be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-journal3, + sd_journal_open3, + sd_journal_next3, + sd_journal_get_data3, + sd_journal_get_cursor3, + sd_journal_get_realtime_usec3 + + + + diff --git a/src/libsystemd/sd_journal_stream_fd.xml b/src/libsystemd/sd_journal_stream_fd.xml new file mode 100644 index 0000000000..2ea7731b48 --- /dev/null +++ b/src/libsystemd/sd_journal_stream_fd.xml @@ -0,0 +1,163 @@ + + + + + + + + + sd_journal_stream_fd + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_journal_stream_fd + 3 + + + + sd_journal_stream_fd + Create log stream file descriptor to the journal + + + + + #include <systemd/sd-journal.h> + + + int sd_journal_stream_fd + const char *identifier + int priority + int level_prefix + + + + + + + Description + + sd_journal_stream_fd() may be used to + create a log stream file descriptor. Log messages written to this + file descriptor as simple newline-separated text strings are + written to the journal. This file descriptor can be used + internally by applications or be made standard output or standard + error of other processes executed. + + sd_journal_stream_fd() takes a short + program identifier string as first argument, which will be written + to the journal as _SYSLOG_IDENTIFIER= field for each log entry + (see + systemd.journal-fields7 + for more information). The second argument shall be the default + priority level for all messages. The priority level is one of + LOG_EMERG, LOG_ALERT, + LOG_CRIT, LOG_ERR, + LOG_WARNING, LOG_NOTICE, + LOG_INFO, LOG_DEBUG, as + defined in syslog.h, see + syslog3 + for details. The third argument is a boolean: if true kernel-style + log level prefixes (such as SD_WARNING) are + interpreted, see + sd-daemon3 + for more information. + + It is recommended that applications log UTF-8 messages only + with this API, but this is not enforced. + + + + Return Value + + The call returns a valid write-only file descriptor on + success or a negative errno-style error code. + + + + Notes + + The sd_journal_stream_fd() interface is + available as a shared library, which can be compiled and linked to + with the + libsystemd pkg-config1 + file. + + + + Examples + + Creating a log stream suitable for + fprintf3: + + #include <syslog.h> +#include <stdio.h> +#include <string.h> +#include <unistd.h> +#include <systemd/sd-journal.h> +#include <systemd/sd-daemon.h> + +int main(int argc, char *argv[]) { + int fd; + FILE *log; + fd = sd_journal_stream_fd("test", LOG_INFO, 1); + if (fd < 0) { + fprintf(stderr, "Failed to create stream fd: %s\n", strerror(-fd)); + return 1; + } + log = fdopen(fd, "w"); + if (!log) { + fprintf(stderr, "Failed to create file object: %m\n"); + close(fd); + return 1; + } + fprintf(log, "Hello World!\n"); + fprintf(log, SD_WARNING "This is a warning!\n"); + fclose(log); + return 0; +} + + + + + See Also + + + systemd1, + sd-journal3, + sd-daemon3, + sd_journal_print3, + syslog3, + fprintf3, + systemd.journal-fields7 + + + + diff --git a/src/libsystemd/sd_listen_fds.xml b/src/libsystemd/sd_listen_fds.xml new file mode 100644 index 0000000000..93bf8d853f --- /dev/null +++ b/src/libsystemd/sd_listen_fds.xml @@ -0,0 +1,257 @@ + + + + + + + + + sd_listen_fds + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_listen_fds + 3 + + + + sd_listen_fds + sd_listen_fds_with_names + SD_LISTEN_FDS_START + Check for file descriptors passed by the system manager + + + + + #include <systemd/sd-daemon.h> + + #define SD_LISTEN_FDS_START 3 + + + int sd_listen_fds + int unset_environment + + + + int sd_listen_fds_with_names + int unset_environment + char*** names + + + + + + Description + + sd_listen_fds() may be invoked by a + daemon to check for file descriptors passed by the service manager as + part of the socket-based activation logic. It returns the number + of received file descriptors. If no file descriptors have been + received, zero is returned. The first file descriptor may be found + at file descriptor number 3 + (i.e. SD_LISTEN_FDS_START), the remaining + descriptors follow at 4, 5, 6, ..., if any. + + If a daemon receives more than one file descriptor, they + will be passed in the same order as configured in the systemd + socket unit file (see + systemd.socket5 + for details). Nonetheless, it is recommended to verify the correct + socket types before using them. To simplify this checking, the + functions + sd_is_fifo3, + sd_is_socket3, + sd_is_socket_inet3, + sd_is_socket_unix3 + are provided. In order to maximize flexibility, it is recommended + to make these checks as loose as possible without allowing + incorrect setups. i.e. often, the actual port number a socket is + bound to matters little for the service to work, hence it should + not be verified. On the other hand, whether a socket is a datagram + or stream socket matters a lot for the most common program logics + and should be checked. + + This function call will set the FD_CLOEXEC flag for all + passed file descriptors to avoid further inheritance to children + of the calling process. + + If multiple socket units activate the same service, the order + of the file descriptors passed to its main process is undefined. + If additional file descriptors have been passed to the service + manager using + sd_pid_notify_with_fds3's + FDSTORE=1 messages, these file descriptors are + passed last, in arbitrary order, and with duplicates + removed. + + If the unset_environment parameter is + non-zero, sd_listen_fds() will unset the + $LISTEN_FDS, $LISTEN_PID and + $LISTEN_FDNAMES environment variables before + returning (regardless of whether the function call itself + succeeded or not). Further calls to + sd_listen_fds() will then return zero, but the + variables are no longer inherited by child processes. + + sd_listen_fds_with_names() is like + sd_listen_fds(), but optionally also returns + an array of strings with identification names for the passed file + descriptors, if that is available and the + names parameter is non-NULL. This + information is read from the $LISTEN_FDNAMES + variable, which may contain a colon-separated list of names. For + socket-activated services, these names may be configured with the + FileDescriptorName= setting in socket unit + files, see + systemd.socket5 + for details. For file descriptors pushed into the file descriptor + store (see above), the name is set via the + FDNAME= field transmitted via + sd_pid_notify_with_fds(). The primary usecase + for these names are services which accept a variety of file + descriptors which are not recognizable with functions like + sd_is_socket() alone, and thus require + identification via a name. It is recommended to rely on named file + descriptors only if identification via + sd_is_socket() and related calls is not + sufficient. Note that the names used are not unique in any + way. The returned array of strings has as many entries as file + descriptors have been received, plus a final NULL pointer + terminating the array. The caller needs to free the array itself + and each of its elements with libc's free() + call after use. If the names parameter is + NULL, the call is entirely equivalent to + sd_listen_fds(). + + Under specific conditions, the following automatic file + descriptor names are returned: + + + + <command>Special names</command> + + + + + + Name + Description + + + + + unknown + The process received no name for the specific file descriptor from the service manager. + + + + stored + The file descriptor originates in the service manager's per-service file descriptor store, and the FDNAME= field was absent when the file descriptor was submitted to the service manager. + + + + connection + The service was activated in per-connection style using Accept=yes in the socket unit file, and the file descriptor is the connection socket. + + + +
+ + + + + Return Value + + On failure, these calls returns a negative errno-style error + code. If + $LISTEN_FDS/$LISTEN_PID was + not set or was not correctly set for this daemon and hence no file + descriptors were received, 0 is returned. Otherwise, the number of + file descriptors passed is returned. The application may find them + starting with file descriptor SD_LISTEN_FDS_START, i.e. file + descriptor 3. + + + + Notes + + + + Internally, sd_listen_fds() checks + whether the $LISTEN_PID environment variable + equals the daemon PID. If not, it returns immediately. Otherwise, + it parses the number passed in the $LISTEN_FDS + environment variable, then sets the FD_CLOEXEC flag for the parsed + number of file descriptors starting from SD_LISTEN_FDS_START. + Finally, it returns the parsed + number. sd_listen_fds_with_names() does the + same but also parses $LISTEN_FDNAMES if + set. + + + + Environment + + + + $LISTEN_PID + $LISTEN_FDS + $LISTEN_FDNAMES + + Set by the service manager for supervised + processes that use socket-based activation. This environment + variable specifies the data + sd_listen_fds() and + sd_listen_fds_with_names() parses. See + above for details. + + + + + + See Also + + + systemd1, + sd-daemon3, + sd_is_fifo3, + sd_is_socket3, + sd_is_socket_inet3, + sd_is_socket_unix3, + sd_pid_notify_with_fds3, + daemon7, + systemd.service5, + systemd.socket5 + + + + diff --git a/src/libsystemd/sd_login_monitor_new.xml b/src/libsystemd/sd_login_monitor_new.xml new file mode 100644 index 0000000000..5625ab9207 --- /dev/null +++ b/src/libsystemd/sd_login_monitor_new.xml @@ -0,0 +1,287 @@ + + + + + + + + + sd_login_monitor_new + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_login_monitor_new + 3 + + + + sd_login_monitor_new + sd_login_monitor_unref + sd_login_monitor_unrefp + sd_login_monitor_flush + sd_login_monitor_get_fd + sd_login_monitor_get_events + sd_login_monitor_get_timeout + sd_login_monitor + Monitor login sessions, seats, users and virtual machines/containers + + + + + #include <systemd/sd-login.h> + + + int sd_login_monitor_new + const char *category + sd_login_monitor **ret + + + + sd_login_monitor *sd_login_monitor_unref + sd_login_monitor *m + + + + void sd_login_monitor_unrefp + sd_login_monitor **m + + + + int sd_login_monitor_flush + sd_login_monitor *m + + + + int sd_login_monitor_get_fd + sd_login_monitor *m + + + + int sd_login_monitor_get_events + sd_login_monitor *m + + + + int sd_login_monitor_get_timeout + sd_login_monitor *m + uint64_t *timeout_usec + + + + + + + Description + + sd_login_monitor_new() may be used to + monitor login sessions, users, seats, and virtual + machines/containers. Via a monitor object a file descriptor can be + integrated into an application defined event loop which is woken + up each time a user logs in, logs out or a seat is added or + removed, or a session, user, seat or virtual machine/container + changes state otherwise. The first parameter takes a string which + can be seat (to get only notifications about + seats being added, removed or changed), session + (to get only notifications about sessions being created or removed + or changed), uid (to get only notifications + when a user changes state in respect to logins) or + machine (to get only notifications when a + virtual machine or container is started or stopped). If + notifications shall be generated in all these conditions, + NULL may be passed. Note that in the future + additional categories may be defined. The second parameter returns + a monitor object and needs to be freed with the + sd_login_monitor_unref() call after + use. + + sd_login_monitor_unref() may be used to + destroy a monitor object. Note that this will invalidate any file + descriptor returned by + sd_login_monitor_get_fd(). + + sd_login_monitor_unrefp() is similar to + sd_login_monitor_unref() but takes a pointer + to a pointer to an sd_login_monitor object. This call + is useful in conjunction with GCC's and LLVM's Clean-up + Variable Attribute. Note that this function is defined as + inline function. Use a declaration like the following, in order to + allocate a login monitor object that is freed automatically as the + code block is left: + + { + __attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL; + int r; + … + r = sd_login_monitor_default(&m); + if (r < 0) + fprintf(stderr, "Failed to allocate login monitor object: %s\n", strerror(-r)); + … +} + + sd_login_monitor_flush() may be used to + reset the wakeup state of the monitor object. Whenever an event + causes the monitor to wake up the event loop via the file + descriptor this function needs to be called to reset the wake-up + state. If this call is not invoked, the file descriptor will + immediately wake up the event loop again. + + sd_login_monitor_unref() and + sd_login_monitor_unrefp() execute no + operation if the passed in monitor object is + NULL. + + sd_login_monitor_get_fd() may be used + to retrieve the file descriptor of the monitor object that may be + integrated in an application defined event loop, based around + poll2 + or a similar interface. The application should include the + returned file descriptor as wake-up source for the events mask + returned by sd_login_monitor_get_events(). It + should pass a timeout value as returned by + sd_login_monitor_get_timeout(). Whenever a + wake-up is triggered the file descriptor needs to be reset via + sd_login_monitor_flush(). An application + needs to reread the login state with a function like + sd_get_seats3 + or similar to determine what changed. + + sd_login_monitor_get_events() will + return the poll() mask to wait for. This + function will return a combination of POLLIN, + POLLOUT and similar to fill into the + .events field of struct + pollfd. + + sd_login_monitor_get_timeout() will + return a timeout value for usage in poll(). + This returns a value in microseconds since the epoch of + CLOCK_MONOTONIC for timing out + poll() in timeout_usec. + See + clock_gettime2 + for details about CLOCK_MONOTONIC. If there + is no timeout to wait for this will fill in (uint64_t) + -1 instead. Note that poll() takes + a relative timeout in milliseconds rather than an absolute timeout + in microseconds. To convert the absolute 'µs' timeout into + relative 'ms', use code like the following: + + uint64_t t; +int msec; +sd_login_monitor_get_timeout(m, &t); +if (t == (uint64_t) -1) + msec = -1; +else { + struct timespec ts; + uint64_t n; + clock_getttime(CLOCK_MONOTONIC, &ts); + n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; + msec = t > n ? (int) ((t - n + 999) / 1000) : 0; +} + + The code above does not do any error checking for brevity's + sake. The calculated msec integer can be passed + directly as poll()'s timeout + parameter. + + + + Return Value + + On success, + sd_login_monitor_new(), + sd_login_monitor_flush() and + sd_login_monitor_get_timeout() + return 0 or a positive integer. On success, + sd_login_monitor_get_fd() returns + a Unix file descriptor. On success, + sd_login_monitor_get_events() + returns a combination of POLLIN, + POLLOUT and suchlike. On failure, + these calls return a negative errno-style error + code. + + sd_login_monitor_unref() + always returns NULL. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + An input parameter was invalid (out of range, + or NULL, where that is not accepted). The specified category to + watch is not known. + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + The sd_login_monitor_new(), + sd_login_monitor_unref(), + sd_login_monitor_flush(), + sd_login_monitor_get_fd(), + sd_login_monitor_get_events() and + sd_login_monitor_get_timeout() + interfaces are available as a shared library, which can be + compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-login3, + sd_get_seats3, + poll2, + clock_gettime2 + + + + diff --git a/src/libsystemd/sd_machine_get_class.xml b/src/libsystemd/sd_machine_get_class.xml new file mode 100644 index 0000000000..ef604139da --- /dev/null +++ b/src/libsystemd/sd_machine_get_class.xml @@ -0,0 +1,152 @@ + + + + + + + + + sd_machine_get_class + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_machine_get_class + 3 + + + + sd_machine_get_class + sd_machine_get_ifindices + Determine the class and network interface indices of a + locally running virtual machine or container. + + + + + #include <systemd/sd-login.h> + + + int sd_machine_get_class + const char* machine + char **class + + + + int sd_machine_get_ifindices + const char* machine + int **ifindices + + + + + + Description + + sd_machine_get_class() may be used to + determine the class of a locally running virtual machine or + container that is registered with + systemd-machined.service8. + The string returned is either vm or + container. The returned string needs to be + freed with the libc free3 + call after use. + + sd_machine_get_ifindices() may be used + to determine the numeric indices of the network interfaces on the + host that are pointing towards the specified locally running + virtual machine or container that is registered with + systemd-machined.service8. + The returned array needs to be freed with the libc free3 + call after use. + + + + Return Value + + On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -ENXIO + + The specified machine does not exist or is currently not running. + + + + + -EINVAL + + An input parameter was invalid (out of range, + or NULL, where that is not accepted). + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + The sd_machine_get_class() and + sd_machine_get_ifindices() interfaces are + available as a shared library, which can be compiled and linked to + with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-login3, + systemd-machined.service8, + sd_pid_get_machine_name3 + + + + diff --git a/src/libsystemd/sd_notify.xml b/src/libsystemd/sd_notify.xml new file mode 100644 index 0000000000..bd6cfdcd29 --- /dev/null +++ b/src/libsystemd/sd_notify.xml @@ -0,0 +1,399 @@ + + + + + + + + + sd_notify + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_notify + 3 + + + + sd_notify + sd_notifyf + sd_pid_notify + sd_pid_notifyf + sd_pid_notify_with_fds + Notify service manager about start-up completion and other service status changes + + + + + #include <systemd/sd-daemon.h> + + + int sd_notify + int unset_environment + const char *state + + + + int sd_notifyf + int unset_environment + const char *format + ... + + + + int sd_pid_notify + pid_t pid + int unset_environment + const char *state + + + + int sd_pid_notifyf + pid_t pid + int unset_environment + const char *format + ... + + + + int sd_pid_notify_with_fds + pid_t pid + int unset_environment + const char *state + const int *fds + unsigned n_fds + + + + + + Description + sd_notify() may be called by a service + to notify the service manager about state changes. It can be used + to send arbitrary information, encoded in an + environment-block-like string. Most importantly, it can be used for + start-up completion notification. + + If the unset_environment parameter is + non-zero, sd_notify() will unset the + $NOTIFY_SOCKET environment variable before + returning (regardless of whether the function call itself + succeeded or not). Further calls to + sd_notify() will then fail, but the variable + is no longer inherited by child processes. + + The state parameter should contain a + newline-separated list of variable assignments, similar in style + to an environment block. A trailing newline is implied if none is + specified. The string may contain any kind of variable + assignments, but the following shall be considered + well-known: + + + + READY=1 + + Tells the service manager that service startup + is finished. This is only used by systemd if the service + definition file has Type=notify set. Since there is little + value in signaling non-readiness, the only value services + should send is READY=1 (i.e. + READY=0 is not defined). + + + + RELOADING=1 + + Tells the service manager that the service is + reloading its configuration. This is useful to allow the + service manager to track the service's internal state, and + present it to the user. Note that a service that sends this + notification must also send a READY=1 + notification when it completed reloading its + configuration. + + + + STOPPING=1 + + Tells the service manager that the service is + beginning its shutdown. This is useful to allow the service + manager to track the service's internal state, and present it + to the user. + + + + STATUS=... + + Passes a single-line UTF-8 status string back + to the service manager that describes the service state. This + is free-form and can be used for various purposes: general + state feedback, fsck-like programs could pass completion + percentages and failing programs could pass a human-readable + error message. Example: STATUS=Completed 66% of file + system check... + + + + ERRNO=... + + If a service fails, the errno-style error + code, formatted as string. Example: ERRNO=2 + for ENOENT. + + + + BUSERROR=... + + If a service fails, the D-Bus error-style + error code. Example: + BUSERROR=org.freedesktop.DBus.Error.TimedOut + + + + MAINPID=... + + The main process ID (PID) of the service, in + case the service manager did not fork off the process itself. + Example: MAINPID=4711 + + + + WATCHDOG=1 + + Tells the service manager to update the + watchdog timestamp. This is the keep-alive ping that services + need to issue in regular intervals if + WatchdogSec= is enabled for it. See + systemd.service5 + for information how to enable this functionality and + sd_watchdog_enabled3 + for the details of how the service can check whether the + watchdog is enabled. + + + + + FDSTORE=1 + + Stores additional file descriptors in the + service manager. File descriptors sent this way will be + maintained per-service by the service manager and be passed + again using the usual file descriptor passing logic on the + next invocation of the service (see + sd_listen_fds3). + This is useful for implementing service restart schemes where + services serialize their state to /run, + push their file descriptors to the system manager, and are + then restarted, retrieving their state again via socket + passing and /run. Note that the service + manager will accept messages for a service only if + FileDescriptorStoreMax= is set to non-zero + for it (defaults to zero). See + systemd.service5 + for details. Multiple arrays of file descriptors may be sent + in separate messages, in which case the arrays are combined. + Note that the service manager removes duplicate file + descriptors before passing them to the service. Use + sd_pid_notify_with_fds() to send messages + with FDSTORE=1, see + below. + + + + FDNAME=... + + When used in combination with + FDSTORE=1, specifies a name for the + submitted file descriptors. This name is passed to the service + during activation, and may be queried using + sd_listen_fds_with_names3. File + descriptors submitted without this field set, will implicitly + get the name stored assigned. Note that, if + multiple file descriptors are submitted at once, the specified + name will be assigned to all of them. In order to assign + different names to submitted file descriptors, submit them in + separate invocations of + sd_pid_notify_with_fds(). The name may + consist of any ASCII character, but must not contain control + characters or :. It may not be longer than + 255 characters. If a submitted name does not follow these + restrictions, it is ignored. + + + + + It is recommended to prefix variable names that are not + listed above with X_ to avoid namespace + clashes. + + Note that systemd will accept status data sent from a + service only if the NotifyAccess= option is + correctly set in the service definition file. See + systemd.service5 + for details. + + sd_notifyf() is similar to + sd_notify() but takes a + printf()-like format string plus + arguments. + + sd_pid_notify() and + sd_pid_notifyf() are similar to + sd_notify() and + sd_notifyf() but take a process ID (PID) to + use as originating PID for the message as first argument. This is + useful to send notification messages on behalf of other processes, + provided the appropriate privileges are available. If the PID + argument is specified as 0, the process ID of the calling process + is used, in which case the calls are fully equivalent to + sd_notify() and + sd_notifyf(). + + sd_pid_notify_with_fds() is similar to + sd_pid_notify() but takes an additional array + of file descriptors. These file descriptors are sent along the + notification message to the service manager. This is particularly + useful for sending FDSTORE=1 messages, as + described above. The additional arguments are a pointer to the + file descriptor array plus the number of file descriptors in the + array. If the number of file descriptors is passed as 0, the call + is fully equivalent to sd_pid_notify(), i.e. + no file descriptors are passed. Note that sending file descriptors + to the service manager on messages that do not expect them (i.e. + without FDSTORE=1) they are immediately closed + on reception. + + + + Return Value + + On failure, these calls return a negative errno-style error + code. If $NOTIFY_SOCKET was not set and hence + no status data could be sent, 0 is returned. If the status was + sent, these functions return with a positive return value. In + order to support both, init systems that implement this scheme and + those which do not, it is generally recommended to ignore the + return value of this call. + + + + Notes + + + + These functions send a single datagram with the + state string as payload to the AF_UNIX socket + referenced in the $NOTIFY_SOCKET environment + variable. If the first character of + $NOTIFY_SOCKET is @, the + string is understood as Linux abstract namespace socket. The + datagram is accompanied by the process credentials of the sending + service, using SCM_CREDENTIALS. + + + + Environment + + + + $NOTIFY_SOCKET + + Set by the service manager for supervised + processes for status and start-up completion notification. + This environment variable specifies the socket + sd_notify() talks to. See above for + details. + + + + + + Examples + + + Start-up Notification + + When a service finished starting up, it might issue the + following call to notify the service manager: + + sd_notify(0, "READY=1"); + + + + Extended Start-up Notification + + A service could send the following after completing + initialization: + + sd_notifyf(0, "READY=1\n" + "STATUS=Processing requests...\n" + "MAINPID=%lu", + (unsigned long) getpid()); + + + + Error Cause Notification + + A service could send the following shortly before exiting, on failure: + + sd_notifyf(0, "STATUS=Failed to start up: %s\n" + "ERRNO=%i", + strerror(errno), + errno); + + + + Store a File Descriptor in the Service Manager + + To store an open file descriptor in the service manager, + in order to continue operation after a service restart without + losing state, use FDSTORE=1: + + sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1); + + + + + See Also + + systemd1, + sd-daemon3, + sd_listen_fds3, + sd_listen_fds_with_names3, + sd_watchdog_enabled3, + daemon7, + systemd.service5 + + + + diff --git a/src/libsystemd/sd_pid_get_session.xml b/src/libsystemd/sd_pid_get_session.xml new file mode 100644 index 0000000000..806cff34e4 --- /dev/null +++ b/src/libsystemd/sd_pid_get_session.xml @@ -0,0 +1,359 @@ + + + + + + + + + sd_pid_get_session + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_pid_get_session + 3 + + + + sd_pid_get_session + sd_pid_get_unit + sd_pid_get_user_unit + sd_pid_get_owner_uid + sd_pid_get_machine_name + sd_pid_get_slice + sd_pid_get_user_slice + sd_pid_get_cgroup + sd_peer_get_session + sd_peer_get_unit + sd_peer_get_user_unit + sd_peer_get_owner_uid + sd_peer_get_machine_name + sd_peer_get_slice + sd_peer_get_user_slice + sd_peer_get_cgroup + Determine session, unit, owner of a session, + container/VM or slice of a specific PID or socket + peer + + + + + #include <systemd/sd-login.h> + + + int sd_pid_get_session + pid_t pid + char **session + + + + int sd_pid_get_unit + pid_t pid + char **unit + + + + int sd_pid_get_user_unit + pid_t pid + char **unit + + + + int sd_pid_get_owner_uid + pid_t pid + uid_t *uid + + + + int sd_pid_get_machine_name + pid_t pid + char **name + + + + int sd_pid_get_slice + pid_t pid + char **slice + + + + int sd_pid_get_user_slice + pid_t pid + char **slice + + + + int sd_pid_get_cgroup + pid_t pid + char **cgroup + + + + int sd_peer_get_session + int fd + char **session + + + + int sd_peer_get_unit + int fd + char **unit + + + + int sd_peer_get_user_unit + int fd + char **unit + + + + int sd_peer_get_owner_uid + int fd + uid_t *uid + + + + int sd_peer_get_machine_name + int fd + char **name + + + + int sd_peer_get_slice + int fd + char **slice + + + + int sd_peer_get_user_slice + int fd + char **slice + + + + int sd_peer_get_cgroup + int fd + char **cgroup + + + + + + Description + + sd_pid_get_session() may be used to + determine the login session identifier of a process identified by + the specified process identifier. The session identifier is a + short string, suitable for usage in file system paths. Note that + not all processes are part of a login session (e.g. system service + processes, user processes that are shared between multiple + sessions of the same user, or kernel threads). For processes not + being part of a login session, this function will fail with + -ENODATA. The returned string needs to be freed with the libc + free3 + call after use. + + sd_pid_get_unit() may be used to + determine the systemd system unit (i.e. system service or scope + unit) identifier of a process identified by the specified PID. The + unit name is a short string, suitable for usage in file system + paths. Note that not all processes are part of a system + unit/service (e.g. user processes, or kernel threads). For + processes not being part of a systemd system unit, this function + will fail with -ENODATA. (More specifically, this call will not + work for kernel threads.) The returned string needs to be freed + with the libc free3 + call after use. + + sd_pid_get_user_unit() may be used to + determine the systemd user unit (i.e. user service or scope unit) + identifier of a process identified by the specified PID. This is + similar to sd_pid_get_unit(), but applies to + user units instead of system units. + + sd_pid_get_owner_uid() may be used to + determine the Unix UID (user identifier) of the owner of the + session of a process identified the specified PID. Note that this + function will succeed for user processes which are shared between + multiple login sessions of the same user, whereas + sd_pid_get_session() will fail. For processes + not being part of a login session and not being a shared process + of a user, this function will fail with -ENODATA. + + sd_pid_get_machine_name() may be used + to determine the name of the VM or container is a member of. The + machine name is a short string, suitable for usage in file system + paths. The returned string needs to be freed with the libc + free3 + call after use. For processes not part of a VM or containers, this + function fails with -ENODATA. + + sd_pid_get_slice() may be used to + determine the slice unit the process is a member of. See + systemd.slice5 + for details about slices. The returned string needs to be freed + with the libc + free3 + call after use. + + Similarly, sd_pid_get_user_slice() + returns the user slice (as managed by the user's systemd instance) + of a process. + + sd_pid_get_cgroup() returns the control + group path of the specified process, relative to the root of the + hierarchy. Returns the path without trailing slash, except for + processes located in the root control group, where "/" is + returned. To find the actual control group path in the file system, + the returned path needs to be prefixed with + /sys/fs/cgroup/ (if the unified control group + setup is used), or + /sys/fs/cgroup/HIERARCHY/ + (if the legacy multi-hierarchy control group setup is used). + + If the pid parameter of any of these + functions is passed as 0, the operation is executed for the + calling process. + + The sd_peer_get_session(), + sd_peer_get_unit(), + sd_peer_get_user_unit(), + sd_peer_get_owner_uid(), + sd_peer_get_machine_name(), + sd_peer_get_slice(), + sd_peer_get_user_slice() and + sd_peer_get_cgroup() calls operate similar to + their PID counterparts, but operate on a connected AF_UNIX socket + and retrieve information about the connected peer process. Note + that these fields are retrieved via /proc, + and hence are not suitable for authorization purposes, as they are + subject to races. + + + + Return Value + + On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -ESRCH + + The specified PID does not refer to a running + process. + + + + + -BADF + + The specified socket file descriptor was + invalid. + + + + -ENODATA + + The given field is not specified for the described + process or peer. + + + + + -EINVAL + + An input parameter was invalid (out of range, + or NULL, where that is not accepted). + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + The sd_pid_get_session(), + sd_pid_get_unit(), + sd_pid_get_user_unit(), + sd_pid_get_owner_uid(), + sd_pid_get_machine_name(), + sd_pid_get_slice(), + sd_pid_get_user_slice(), + sd_peer_get_session(), + sd_peer_get_unit(), + sd_peer_get_user_unit(), + sd_peer_get_owner_uid(), + sd_peer_get_machine_name(), + sd_peer_get_slice() and + sd_peer_get_user_slice() interfaces are + available as a shared library, which can be compiled and linked to + with the libsystemd pkg-config1 + file. + + Note that the login session identifier as + returned by sd_pid_get_session() + is completely unrelated to the process session + identifier as returned by + getsid2. + + + + See Also + + + systemd1, + sd-login3, + sd_session_is_active3, + getsid2, + systemd.slice5, + systemd-machined.service8 + + + + diff --git a/src/libsystemd/sd_seat_get_active.xml b/src/libsystemd/sd_seat_get_active.xml new file mode 100644 index 0000000000..c5e6ddab02 --- /dev/null +++ b/src/libsystemd/sd_seat_get_active.xml @@ -0,0 +1,212 @@ + + + + + + + + + sd_seat_get_active + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_seat_get_active + 3 + + + + sd_seat_get_active + sd_seat_get_sessions + sd_seat_can_multi_session + sd_seat_can_tty + sd_seat_can_graphical + Determine state of a specific seat + + + + + #include <systemd/sd-login.h> + + + int sd_seat_get_active + const char *seat + char **session + uid_t *uid + + + + int sd_seat_get_sessions + const char *seat + char ***sessions + uid_t **uid + unsigned int *n_uids + + + + int sd_seat_can_multi_session + const char *seat + + + + int sd_seat_can_tty + const char *seat + + + + int sd_seat_can_graphical + const char *seat + + + + + + Description + + sd_seat_get_active() may be used to + determine which session is currently active on a seat, if there is + any. Returns the session identifier and the user identifier of the + Unix user the session is belonging to. Either the session or the + user identifier parameter can be passed NULL, + in case only one of the parameters shall be queried. The returned + string needs to be freed with the libc + free3 + call after use. + + sd_seat_get_sessions() may be used to + determine all sessions on the specified seat. Returns two arrays, + one (NULL terminated) with the session + identifiers of the sessions and one with the user identifiers of + the Unix users the sessions belong to. An additional parameter may + be used to return the number of entries in the latter array. The + two arrays and the latter parameter may be passed as + NULL in case these values need not to be + determined. The arrays and the strings referenced by them need to + be freed with the libc + free3 + call after use. Note that instead of an empty array + NULL may be returned and should be considered + equivalent to an empty array. + + sd_seat_can_multi_session() may be used + to determine whether a specific seat is capable of multi-session, + i.e. allows multiple login sessions in parallel (with only one + being active at a time). + + sd_seat_can_tty() may be used to + determine whether a specific seat provides TTY functionality, i.e. + is useful as a text console. + + sd_seat_can_graphical() may be used to + determine whether a specific seat provides graphics functionality, + i.e. is useful as a graphics display. + + If the seat parameter of any of these + functions is passed as NULL, the operation is + executed for the seat of the session of the calling process, if + there is any. + + + + Return Value + + On success, sd_seat_get_active() + returns 0 or a positive integer. On success, + sd_seat_get_sessions() returns the number of + entries in the session identifier array. If the test succeeds, + sd_seat_can_multi_session, + sd_seat_can_tty and + sd_seat_can_graphical return a positive + integer, if it fails 0. On failure, these calls return a negative + errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -ENODATA + + The given field is not specified for the described + seat. + + + + + -ENXIO + + The specified seat is unknown. + + + + + -EINVAL + + An input parameter was invalid (out of range, + or NULL, where that is not accepted). + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + The sd_seat_get_active(), + sd_seat_get_sessions(), + sd_seat_can_multi_session(), + sd_seat_can_tty() and + sd_seat_can_graphical() interfaces are + available as a shared library, which can be compiled and linked to + with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-login3, + sd_session_get_seat3 + + + + diff --git a/src/libsystemd/sd_session_is_active.xml b/src/libsystemd/sd_session_is_active.xml new file mode 100644 index 0000000000..a6076b177a --- /dev/null +++ b/src/libsystemd/sd_session_is_active.xml @@ -0,0 +1,359 @@ + + + + + + + + + sd_session_is_active + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_session_is_active + 3 + + + + sd_session_is_active + sd_session_is_remote + sd_session_get_state + sd_session_get_uid + sd_session_get_seat + sd_session_get_service + sd_session_get_type + sd_session_get_class + sd_session_get_desktop + sd_session_get_display + sd_session_get_tty + sd_session_get_vt + sd_session_get_remote_host + sd_session_get_remote_user + Determine state of a specific session + + + + + #include <systemd/sd-login.h> + + + int sd_session_is_active + const char *session + + + + int sd_session_is_remote + const char *session + + + + int sd_session_get_state + const char *session + char **state + + + + int sd_session_get_uid + const char *session + uid_t *uid + + + + int sd_session_get_seat + const char *session + char **seat + + + + int sd_session_get_service + const char *session + char **service + + + + int sd_session_get_type + const char *session + char **type + + + + int sd_session_get_class + const char *session + char **class + + + + int sd_session_get_desktop + const char *session + char **desktop + + + + int sd_session_get_display + const char *session + char **display + + + + int sd_session_get_remote_host + const char *session + char **remote_host + + + + int sd_session_get_remote_user + const char *session + char **remote_user + + + + int sd_session_get_tty + const char *session + char **tty + + + + int sd_session_get_vt + const char *session + unsigned int *vt + + + + + + Description + + sd_session_is_active() may be used to + determine whether the session identified by the specified session + identifier is currently active (i.e. currently in the foreground + and available for user input) or not. + + sd_session_is_remote() may be used to + determine whether the session identified by the specified session + identifier is a remote session (i.e. its remote host is known) or + not. + + sd_session_get_state() may be used to + determine the state of the session identified by the specified + session identifier. The following states are currently known: + online (session logged in, but session not + active, i.e. not in the foreground), active + (session logged in and active, i.e. in the foreground), + closing (session nominally logged out, but some + processes belonging to it are still around). In the future + additional states might be defined, client code should be written + to be robust in regards to additional state strings being + returned. This function is a more generic version of + sd_session_is_active(). The returned string + needs to be freed with the libc + free3 + call after use. + + sd_session_get_uid() may be used to + determine the user identifier of the Unix user the session + identified by the specified session identifier belongs to. + + sd_session_get_seat() may be used to + determine the seat identifier of the seat the session identified + by the specified session identifier belongs to. Note that not all + sessions are attached to a seat, this call will fail for them. The + returned string needs to be freed with the libc + free3 + call after use. + + sd_session_get_service() may be used to + determine the name of the service (as passed during PAM session + setup) that registered the session identified by the specified + session identifier. The returned string needs to be freed with the + libc + free3 + call after use. + + sd_session_get_type() may be used to + determine the type of the session identified by the specified + session identifier. The returned string is one of + x11, wayland, + tty, mir or + unspecified and needs to be freed with the libc + free3 + call after use. + + sd_session_get_class() may be used to + determine the class of the session identified by the specified + session identifier. The returned string is one of + user, greeter, + lock-screen, or background + and needs to be freed with the libc + free3 + call after use. + + sd_session_get_desktop() may be used to + determine the brand of the desktop running on the session + identified by the specified session identifier. This field can be + set freely by desktop environments and does not follow any special + formatting. However, desktops are strongly recommended to use the + same identifiers and capitalization as for + $XDG_CURRENT_DESKTOP, as defined by the Desktop + Entry Specification. The returned string needs to be freed + with the libc + free3 + call after use. + + sd_session_get_display() may be used to + determine the X11 display of the session identified by the + specified session identifier. The returned string needs to be + freed with the libc + free3 + call after use. + + sd_session_get_remote_host() may be + used to determine the remote hostname of the session identified by + the specified session identifier. The returned string needs to be + freed with the libc + free3 + call after use. + + sd_session_get_remote_user() may be + used to determine the remote username of the session identified by + the specified session identifier. The returned string needs to be + freed with the libc + free3 + call after use. Note that this value is rarely known to the + system, and even then should not be relied on. + + sd_session_get_tty() may be used to + determine the TTY device of the session identified by the + specified session identifier. The returned string needs to be + freed with the libc + free3 + call after use. + + sd_session_get_vt() may be used to + determine the VT number of the session identified by the specified + session identifier. This function will return an error if the seat + does not support VTs. + + If the session parameter of any of these + functions is passed as NULL, the operation is + executed for the session the calling process is a member of, if + there is any. + + + + Return Value + + If the test succeeds, + sd_session_is_active() and + sd_session_is_remote() return a + positive integer; if it fails, 0. On success, + sd_session_get_state(), + sd_session_get_uid(), + sd_session_get_seat(), + sd_session_get_service(), + sd_session_get_type(), + sd_session_get_class(), + sd_session_get_display(), + sd_session_get_remote_user(), + sd_session_get_remote_host() and + sd_session_get_tty() return 0 or + a positive integer. On failure, these calls return a + negative errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -ENXIO + + The specified session does not exist. + + + + + -ENODATA + + The given field is not specified for the described + session. + + + + + -EINVAL + + An input parameter was invalid (out of range, + or NULL, where that is not accepted). + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + The sd_session_is_active(), + sd_session_get_state(), + sd_session_get_uid(), + sd_session_get_seat(), + sd_session_get_service(), + sd_session_get_type(), + sd_session_get_class(), + sd_session_get_display(), + sd_session_get_remote_host(), + sd_session_get_remote_user() and + sd_session_get_tty() + interfaces are available as a shared library, which can + be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-login3, + sd_pid_get_session3 + + + + diff --git a/src/libsystemd/sd_uid_get_state.xml b/src/libsystemd/sd_uid_get_state.xml new file mode 100644 index 0000000000..130af761da --- /dev/null +++ b/src/libsystemd/sd_uid_get_state.xml @@ -0,0 +1,230 @@ + + + + + + + + + sd_uid_get_state + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_uid_get_state + 3 + + + + sd_uid_get_state + sd_uid_is_on_seat + sd_uid_get_sessions + sd_uid_get_seats + sd_uid_get_display + Determine login state of a specific Unix user ID + + + + + #include <systemd/sd-login.h> + + + int sd_uid_get_state + uid_t uid + char **state + + + + int sd_uid_is_on_seat + uid_t uid + int require_active + const char *seat + + + + int sd_uid_get_sessions + uid_t uid + int require_active + char ***sessions + + + + int sd_uid_get_seats + uid_t uid + int require_active + char ***seats + + + + int sd_uid_get_display + uid_t uid + char **session + + + + + + Description + + sd_uid_get_state() may be used to + determine the login state of a specific Unix user identifier. The + following states are currently known: offline + (user not logged in at all), lingering (user + not logged in, but some user services running), + online (user logged in, but not active, i.e. + has no session in the foreground), active (user + logged in, and has at least one active session, i.e. one session + in the foreground), closing (user not logged + in, and not lingering, but some processes are still around). In + the future additional states might be defined, client code should + be written to be robust in regards to additional state strings + being returned. The returned string needs to be freed with the + libc + free3 + call after use. + + sd_uid_is_on_seat() may be used to + determine whether a specific user is logged in or active on a + specific seat. Accepts a Unix user identifier and a seat + identifier string as parameters. The + require_active parameter is a boolean + value. If non-zero (true), this function will test if the user is + active (i.e. has a session that is in the foreground and accepting + user input) on the specified seat, otherwise (false) only if the + user is logged in (and possibly inactive) on the specified + seat. + + sd_uid_get_sessions() may be used to + determine the current sessions of the specified user. Accepts a + Unix user identifier as parameter. The + require_active parameter controls whether + the returned list shall consist of only those sessions where the + user is currently active (> 0), where the user is currently + online but possibly inactive (= 0), or logged in at all but + possibly closing the session (< 0). The call returns a + NULL terminated string array of session + identifiers in sessions which needs to be + freed by the caller with the libc + free3 + call after use, including all the strings referenced. If the + string array parameter is passed as NULL, the + array will not be filled in, but the return code still indicates + the number of current sessions. Note that instead of an empty + array NULL may be returned and should be + considered equivalent to an empty array. + + Similarly, sd_uid_get_seats() may be + used to determine the list of seats on which the user currently + has sessions. Similar semantics apply, however note that the user + may have multiple sessions on the same seat as well as sessions + with no attached seat and hence the number of entries in the + returned array may differ from the one returned by + sd_uid_get_sessions(). + + sd_uid_get_display() returns the name + of the "primary" session of a user. If the user has graphical + sessions, it will be the oldest graphical session. Otherwise, it + will be the oldest open session. + + + + Return Value + + On success, sd_uid_get_state() returns + 0 or a positive integer. If the test succeeds, + sd_uid_is_on_seat() returns a positive + integer; if it fails, 0. + sd_uid_get_sessions() and + sd_uid_get_seats() return the number of + entries in the returned arrays. + sd_uid_get_display() returns a non-negative + code on success. On failure, these calls return a negative + errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -ENODATA + + The given field is not specified for the described + user. + + + + + -ENXIO + + The specified seat is unknown. + + + + + -EINVAL + + An input parameter was invalid (out of range, + or NULL, where that is not accepted). This is also returned if + the passed user ID is 0xFFFF or 0xFFFFFFFF, which are + undefined on Linux. + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + Functions described here are available as a shared library, + and can be compiled and linked to using the + libsystemd pkg-config1 + entry. + + + + See Also + + + systemd1, + sd-login3, + sd_pid_get_owner_uid3 + + + + diff --git a/src/libsystemd/sd_watchdog_enabled.xml b/src/libsystemd/sd_watchdog_enabled.xml new file mode 100644 index 0000000000..3de9899453 --- /dev/null +++ b/src/libsystemd/sd_watchdog_enabled.xml @@ -0,0 +1,169 @@ + + + + + + + + + sd_watchdog_enabled + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_watchdog_enabled + 3 + + + + sd_watchdog_enabled + Check whether the service manager expects watchdog keep-alive notifications from a service + + + + + #include <systemd/sd-daemon.h> + + + int sd_watchdog_enabled + int unset_environment + uint64_t *usec + + + + + + Description + sd_watchdog_enabled() may be called by + a service to detect whether the service manager expects regular + keep-alive watchdog notification events from it, and the timeout + after which the manager will act on the service if it did not get + such a notification. + + If the $WATCHDOG_USEC environment + variable is set, and the $WATCHDOG_PID variable + is unset or set to the PID of the current process, the service + manager expects notifications from this process. The manager will + usually terminate a service when it does not get a notification + message within the specified time after startup and after each + previous message. It is recommended that a daemon sends a + keep-alive notification message to the service manager every half + of the time returned here. Notification messages may be sent with + sd_notify3 + with a message string of WATCHDOG=1. + + If the unset_environment parameter is + non-zero, sd_watchdog_enabled() will unset + the $WATCHDOG_USEC and + $WATCHDOG_PID environment variables before + returning (regardless of whether the function call itself + succeeded or not). Those variables are no longer inherited by + child processes. Further calls to + sd_watchdog_enabled() will also return with + zero. + + If the usec parameter is non-NULL, + sd_watchdog_enabled() will write the timeout + in µs for the watchdog logic to it. + + To enable service supervision with the watchdog logic, use + WatchdogSec= in service files. See + systemd.service5 + for details. + + Use + sd_event_set_watchdog3 + to enable automatic watchdog support in + sd-event3-based event loops. + + + + Return Value + + On failure, this call returns a negative errno-style error + code. If the service manager expects watchdog keep-alive + notification messages to be sent, > 0 is returned, otherwise 0 + is returned. Only if the return value is > 0, the + usec parameter is valid after the + call. + + + + Notes + + + + Internally, this functions parses the + $WATCHDOG_PID and + $WATCHDOG_USEC environment variable. The call + will ignore these variables if $WATCHDOG_PID + does not contain the PID of the current process, under the + assumption that in that case, the variables were set for a + different process further up the process tree. + + + + Environment + + + + $WATCHDOG_PID + + Set by the system manager for supervised + process for which watchdog support is enabled, and contains + the PID of that process. See above for + details. + + + + $WATCHDOG_USEC + + Set by the system manager for supervised + process for which watchdog support is enabled, and contains + the watchdog timeout in µs See above for + details. + + + + + + See Also + + systemd1, + sd-daemon3, + daemon7, + systemd.service5, + sd_notify3, + sd_event_set_watchdog3 + + + + diff --git a/src/libsystemd/src/sd-bus/sd-bus.xml b/src/libsystemd/src/sd-bus/sd-bus.xml new file mode 100644 index 0000000000..336dd33ea0 --- /dev/null +++ b/src/libsystemd/src/sd-bus/sd-bus.xml @@ -0,0 +1,123 @@ + + + + + + + + + sd-bus + systemd + + + + Documentation + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd-bus + 3 + + + + sd-bus + A lightweight D-Bus and kdbus client library + + + + + #include <systemd/sd-bus.h> + + + + pkg-config --cflags --libs libsystemd + + + + + + Description + + sd-bus.h provides an implementation + of a D-Bus client. It can interoperate both with the traditional + dbus-daemon1, + and with kdbus. See + + for more information about the big picture. + + + + Interfaces described here have not been declared stable yet, + and are not accessible from libsystemd.so. + This documentation is provided in hope it might be useful for + developers, without any guarantees of availability or stability. + + + + See + sd_bus_default3, + sd_bus_new3, + sd_bus_request_name3, + sd_bus_start3, + sd_bus_message_append3, + sd_bus_message_append_basic3, + sd_bus_message_append_array3, + sd_bus_message_append_string_memfd3, + sd_bus_message_append_strv3, + sd_bus_message_can_send3, + sd_bus_message_get_cookie3, + sd_bus_message_get_monotonic_usec3, + sd_bus_send3, + sd_bus_set_address3, + sd_bus_set_description3, + sd_bus_set_prepare3, + sd_bus_creds_get_pid3, + sd_bus_creds_new_from_pid3, + sd_bus_get_name_creds3, + sd_bus_get_owner_creds3, + sd_bus_negotiate_fds3, + sd_bus_path_encode3, + sd-bus-errors3, + sd_bus_error3, + sd_bus_error_add_map3, + sd_bus_set_allow_interactive_authorization3 + for more information about the functions available. + + + + + + See Also + + systemd1, + sd-event3, + dbus-daemon1, + dbus-send1, + gdbus + + + + diff --git a/src/libsystemd/src/sd-daemon/sd-daemon.xml b/src/libsystemd/src/sd-daemon/sd-daemon.xml new file mode 100644 index 0000000000..b06d99f346 --- /dev/null +++ b/src/libsystemd/src/sd-daemon/sd-daemon.xml @@ -0,0 +1,144 @@ + + + + + + + + + sd-daemon + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd-daemon + 3 + + + + sd-daemon + SD_EMERG + SD_ALERT + SD_CRIT + SD_ERR + SD_WARNING + SD_NOTICE + SD_INFO + SD_DEBUG + APIs for + new-style daemons + + + + + #include <systemd/sd-daemon.h> + + + + pkg-config --cflags --libs libsystemd + + + + + + Description + + sd-daemon.h provides APIs for new-style + daemons, as implemented by the + systemd1 + service manager. + + See + sd_listen_fds3, + sd_notify3, + sd_booted3, + sd_is_fifo3, + sd_watchdog_enabled3 + for more information about the functions implemented. In addition + to these functions, a couple of logging prefixes are defined as + macros: + + #define SD_EMERG "<0>" /* system is unusable */ +#define SD_ALERT "<1>" /* action must be taken immediately */ +#define SD_CRIT "<2>" /* critical conditions */ +#define SD_ERR "<3>" /* error conditions */ +#define SD_WARNING "<4>" /* warning conditions */ +#define SD_NOTICE "<5>" /* normal but significant condition */ +#define SD_INFO "<6>" /* informational */ +#define SD_DEBUG "<7>" /* debug-level messages */ + + These prefixes are intended to be used in conjunction with + stderr-based logging as implemented by systemd. If a systemd + service definition file is configured with + StandardError=journal, + StandardError=syslog or + StandardError=kmsg, these prefixes can be used + to encode a log level in lines printed. This is similar to the + kernel printk()-style logging. See + klogctl2 + for more information. + + The log levels are identical to + syslog3's + log level system. To use these prefixes simply prefix every line + with one of these strings. A line that is not prefixed will be + logged at the default log level SD_INFO. + + + Hello World + + A daemon may log with the log level NOTICE by issuing this + call: + + fprintf(stderr, SD_NOTICE "Hello World!\n"); + + + + + + + See Also + + systemd1, + sd_listen_fds3, + sd_notify3, + sd_booted3, + sd_is_fifo3, + sd_watchdog_enabled3, + daemon7, + systemd.service5, + systemd.socket5, + fprintf3, + pkg-config1 + + + + diff --git a/src/libsystemd/src/sd-event/sd-event.xml b/src/libsystemd/src/sd-event/sd-event.xml new file mode 100644 index 0000000000..fc615f0906 --- /dev/null +++ b/src/libsystemd/src/sd-event/sd-event.xml @@ -0,0 +1,187 @@ + + + + + + + + + sd-event + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd-event + 3 + + + + sd-event + A generic event loop implementation + + + + + #include <systemd/sd-event.h> + + + + pkg-config --cflags --libs libsystemd + + + + + + Description + + sd-event.h provides a generic event + loop implementation, based on Linux epoll7. + + + See + sd_event_new3, + sd_event_run3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_source_unref3, + sd_event_source_set_priority3, + sd_event_source_set_enabled3, + sd_event_source_set_userdata3, + sd_event_source_get_event3, + sd_event_source_get_pending3, + sd_event_source_set_description3, + sd_event_source_set_prepare3, + sd_event_wait3, + sd_event_get_fd3, + sd_event_set_watchdog3, + sd_event_exit3, + sd_event_now3 + for more information about the functions available. + + The event loop design is targeted on running a separate + instance of the event loop in each thread; it has no concept of + distributing events from a single event loop instance onto + multiple worker threads. Dispatching events is strictly ordered + and subject to configurable priorities. In each event loop + iteration a single event source is dispatched. Each time an event + source is dispatched the kernel is polled for new events, before + the next event source is dispatched. The event loop is designed to + honour priorities and provide fairness within each priority. It is + not designed to provide optimal throughput, as this contradicts + these goals due the limitations of the underlying epoll7 + primitives. + + The event loop implementation provides the following features: + + + I/O event sources, based on epoll7's + file descriptor watching, including edge triggered events (EPOLLET). See sd_event_add_io3. + + Timer event sources, based on timerfd_create2, + supporting the CLOCK_MONOTONIC, + CLOCK_REALTIME, + CLOCK_BOOTIME clocks, as well as the + CLOCK_REALTIME_ALARM and + CLOCK_BOOTTIME_ALARM clocks that can resume + the system from suspend. When creating timer events a required + accuracy parameter may be specified which allows coalescing of + timer events to minimize power consumption. See sd_event_add_time3. + + UNIX process signal events, based on + signalfd2, + including full support for real-time signals, and queued parameters. See sd_event_add_signal3. + + Child process state change events, based on + waitid2. See sd_event_add_child3. + + Static event sources, of three types: defer, + post and exit, for invoking calls in each event loop, after + other event sources or at event loop termination. See + sd_event_add_defer3. + + Event sources may be assigned a 64bit priority + value, that controls the order in which event sources are + dispatched if multiple are pending simultaneously. See + sd_event_source_set_priority3. + + The event loop may automatically send watchdog + notification messages to the service manager. See + sd_event_set_watchdog3. + + The event loop may be integrated into foreign + event loops, such as the GLib one. See + sd_event_get_fd3 + for an example. + + + + + + + + See Also + + systemd1, + sd_event_new3, + sd_event_run3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_source_unref3, + sd_event_source_set_priority3, + sd_event_source_set_enabled3, + sd_event_source_set_userdata3, + sd_event_source_get_event3, + sd_event_source_get_pending3, + sd_event_source_set_description3, + sd_event_source_set_prepare3, + sd_event_wait3, + sd_event_get_fd3, + sd_event_set_watchdog3, + sd_event_exit3, + sd_event_now3, + epoll7, + timerfd_create2, + signalfd2, + waitid2 + + + + diff --git a/src/libsystemd/src/sd-id128/sd-id128.xml b/src/libsystemd/src/sd-id128/sd-id128.xml new file mode 100644 index 0000000000..ea7972055d --- /dev/null +++ b/src/libsystemd/src/sd-id128/sd-id128.xml @@ -0,0 +1,166 @@ + + + + + + + + + sd-id128 + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd-id128 + 3 + + + + sd-id128 + sd_id128_t + SD_ID128_MAKE + SD_ID128_CONST_STR + SD_ID128_FORMAT_STR + SD_ID128_FORMAT_VAL + sd_id128_equal + APIs for processing 128-bit IDs + + + + + #include <systemd/sd-id128.h> + + + + pkg-config --cflags --libs libsystemd + + + + + + Description + + sd-id128.h provides APIs to process and + generate 128-bit ID values. The 128-bit ID values processed and + generated by these APIs are a generalization of OSF UUIDs as + defined by RFC + 4122 but use a simpler string format. These functions + impose no structure on the used IDs, much unlike OSF UUIDs or + Microsoft GUIDs, but are fully compatible with those types of IDs. + + + See + sd_id128_to_string3, + sd_id128_randomize3 + and + sd_id128_get_machine3 + for more information about the implemented functions. + + A 128-bit ID is implemented as the following + union type: + + typedef union sd_id128 { + uint8_t bytes[16]; + uint64_t qwords[2]; +} sd_id128_t; + + This union type allows accessing the 128-bit ID as 16 + separate bytes or two 64-bit words. It is generally safer to + access the ID components by their 8-bit array to avoid endianness + issues. This union is intended to be passed call-by-value (as + opposed to call-by-reference) and may be directly manipulated by + clients. + + A couple of macros are defined to denote and decode 128-bit + IDs: + + SD_ID128_MAKE() may be used to denote a + constant 128-bit ID in source code. A commonly used idiom is to + assign a name to a 128-bit ID using this macro: + + #define SD_MESSAGE_COREDUMP SD_ID128_MAKE(fc,2e,22,bc,6e,e6,47,b6,b9,07,29,ab,34,a2,50,b1) + + SD_ID128_CONST_STR() may be used to + convert constant 128-bit IDs into constant strings for output. The + following example code will output the string + "fc2e22bc6ee647b6b90729ab34a250b1": + int main(int argc, char *argv[]) { + puts(SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP)); +} + + SD_ID128_FORMAT_STR and + SD_ID128_FORMAT_VAL() may be used to format a + 128-bit ID in a + printf3 + format string, as shown in the following example: + + int main(int argc, char *argv[]) { + sd_id128_t id; + id = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); + printf("The ID encoded in this C file is " SD_ID128_FORMAT_STR ".\n", SD_ID128_FORMAT_VAL(id)); + return 0; +} + + Use sd_id128_equal() to compare two 128-bit IDs: + + int main(int argc, char *argv[]) { + sd_id128_t a, b, c; + a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); + b = SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e); + c = a; + assert(sd_id128_equal(a, c)); + assert(!sd_id128_equal(a, b)); + return 0; +} + + Note that new, randomized IDs may be generated with + journalctl1's + option. + + + + + + See Also + + systemd1, + sd_id128_to_string3, + sd_id128_randomize3, + sd_id128_get_machine3, + printf3, + journalctl1, + sd-journal7, + pkg-config1, + machine-id5 + + + + diff --git a/src/libsystemd/src/sd-journal/sd-journal.xml b/src/libsystemd/src/sd-journal/sd-journal.xml new file mode 100644 index 0000000000..09747a480c --- /dev/null +++ b/src/libsystemd/src/sd-journal/sd-journal.xml @@ -0,0 +1,133 @@ + + + + + + + + + sd-journal + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd-journal + 3 + + + + sd-journal + APIs for submitting and querying log entries to and + from the journal + + + + + #include <systemd/sd-journal.h> + + + + pkg-config --cflags --libs libsystemd + + + + + + Description + + sd-journal.h provides APIs to submit + and query log entries. The APIs exposed act both as client for the + systemd-journald.service8 + journal service and as parser for the journal files on disk. + + + See + sd_journal_print3, + sd_journal_stream_fd3, + sd_journal_open3, + sd_journal_next3, + sd_journal_get_realtime_usec3, + sd_journal_add_match3, + sd_journal_seek_head3, + sd_journal_query_enumerate3, + sd_journal_enumerate_fields3, + sd_journal_get_cursor3, + sd_journal_get_cutoff_realtime_usec3, + sd_journal_get_cutoff_monotonic_usec3, + sd_journal_get_usage3, + sd_journal_get_catalog3, + sd_journal_get_fd3, + sd_journal_has_runtime_files3 + and + sd_journal_has_persistent_files3 + for more information about the functions implemented. + + Command line access for submitting entries to the journal is + available with the + systemd-cat1 + tool. Command line access for querying entries from the journal is + available with the + journalctl1 + tool. + + + + + + See Also + + systemd1, + sd_journal_print3, + sd_journal_stream_fd3, + sd_journal_open3, + sd_journal_next3, + sd_journal_get_data3, + sd_journal_get_realtime_usec3, + sd_journal_add_match3, + sd_journal_seek_head3, + sd_journal_query_enumerate3, + sd_journal_enumerate_fields3, + sd_journal_get_cursor3, + sd_journal_get_cutoff_realtime_usec3, + sd_journal_get_cutoff_monotonic_usec3, + sd_journal_get_usage3, + sd_journal_get_fd3, + sd_journal_query_unique3, + sd_journal_get_catalog3, + sd_journal_has_runtime_files3, + sd_journal_has_persistent_files3, + journalctl1, + sd-id1283, + pkg-config1 + + + + diff --git a/src/libsystemd/src/sd-login/sd-login.xml b/src/libsystemd/src/sd-login/sd-login.xml new file mode 100644 index 0000000000..328f71164d --- /dev/null +++ b/src/libsystemd/src/sd-login/sd-login.xml @@ -0,0 +1,135 @@ + + + + + + + + + sd-login + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd-login + 3 + + + + sd-login + APIs for + tracking logins + + + + + #include <systemd/sd-login.h> + + + + pkg-config --cflags --libs libsystemd + + + + + Description + + sd-login.h provides APIs to introspect + and monitor seat, login session and user status information on the + local system. + + See Multi-Seat + on Linux for an introduction into multi-seat support on + Linux, the background for this set of APIs. + + Note that these APIs only allow purely passive access and + monitoring of seats, sessions and users. To actively make changes + to the seat configuration, terminate login sessions, or switch + session on a seat you need to utilize the D-Bus API of + systemd-logind, instead. + + These functions synchronously access data in + /proc, /sys/fs/cgroup + and /run. All of these are virtual file + systems, hence the runtime cost of the accesses is relatively + cheap. + + It is possible (and often a very good choice) to mix calls + to the synchronous interface of sd-login.h + with the asynchronous D-Bus interface of systemd-logind. However, + if this is done you need to think a bit about possible races since + the stream of events from D-Bus and from + sd-login.h interfaces such as the login + monitor are asynchronous and not ordered against each + other. + + If the functions return string arrays, these are generally + NULL terminated and need to be freed by the + caller with the libc + free3 + call after use, including the strings referenced therein. + Similarly, individual strings returned need to be freed, as + well. + + As a special exception, instead of an empty string array + NULL may be returned, which should be treated + equivalent to an empty string array. + + See + sd_pid_get_session3, + sd_uid_get_state3, + sd_session_is_active3, + sd_seat_get_active3, + sd_get_seats3, + sd_login_monitor_new3 + for more information about the functions + implemented. + + + + + + See Also + + systemd1, + sd_pid_get_session3, + sd_uid_get_state3, + sd_session_is_active3, + sd_seat_get_active3, + sd_get_seats3, + sd_login_monitor_new3, + sd-daemon3, + pkg-config1 + + + + diff --git a/src/libudev/libudev.xml b/src/libudev/libudev.xml new file mode 100644 index 0000000000..7ef978463c --- /dev/null +++ b/src/libudev/libudev.xml @@ -0,0 +1,125 @@ + + +%entities; +]> + + + + + + + libudev + systemd + + + + Developer + David + Herrmann + dh.herrmann@gmail.com + + + + + + libudev + 3 + + + + libudev + API for enumerating and introspecting local devices + + + + + #include <libudev.h> + + + + pkg-config --cflags --libs libudev + + + + + Description + + libudev.h provides APIs to introspect + and enumerate devices on the local system. + + All functions require a libudev context to operate. This + context can be create via + udev_new3. + It is used to track library state and link objects together. No + global state is used by libudev, everything is always linked to + a udev context. Furthermore, multiple different udev contexts can + be used in parallel by multiple threads. However, a single context + must not be accessed by multiple threads in parallel. The caller + is responsible for providing suitable locking if they intend to use + it from multiple threads. + + To introspect a local device on a system, a udev device + object can be created via + udev_device_new_from_syspath3 + and friends. The device object allows to query current state, + read and write attributes and lookup properties of the device in + question. + + To enumerate local devices on the system, an enumeration + object can be created via + udev_enumerate_new3. + + To monitor the local system for hotplugged or unplugged + devices, a monitor can be created via + udev_monitor_new_from_netlink3. + + Whenever libudev returns a list of objects, the + udev_list_entry3 + API should be used to iterate, access and modify those lists. + + Furthermore, libudev also exports legacy APIs that should + not be used by new software (and as such are not documented as + part of this manual). This includes the hardware database known + as udev_hwdb (please use the new + sd-hwdb3 + API instead) and the udev_queue object to + query the udev daemon (which should not be used by new software + at all). + + + + See Also + + udev_new3, + udev_device_new_from_syspath3, + udev_enumerate_new3, + udev_monitor_new_from_netlink3, + udev_list_entry3, + systemd1, + sd-device3, + sd-hwdb3, + pkg-config1 + + + + diff --git a/src/libudev/udev_device_get_syspath.xml b/src/libudev/udev_device_get_syspath.xml new file mode 100644 index 0000000000..b54749ed56 --- /dev/null +++ b/src/libudev/udev_device_get_syspath.xml @@ -0,0 +1,207 @@ + + +%entities; +]> + + + + + + + udev_device_get_syspath + systemd + + + + Developer + David + Herrmann + dh.herrmann@gmail.com + + + + + + udev_device_get_syspath + 3 + + + + udev_device_get_syspath + udev_device_get_sysname + udev_device_get_sysnum + udev_device_get_devpath + udev_device_get_devnode + udev_device_get_devnum + udev_device_get_devtype + udev_device_get_subsystem + udev_device_get_driver + udev_device_get_udev + udev_device_get_parent + udev_device_get_parent_with_subsystem_devtype + udev_device_get_is_initialized + udev_device_get_action + + Query device properties + + + + + #include <libudev.h> + + + const char *udev_device_get_syspath + struct udev_device *udev_device + + + + const char *udev_device_get_sysname + struct udev_device *udev_device + + + + const char *udev_device_get_sysnum + struct udev_device *udev_device + + + + const char *udev_device_get_devpath + struct udev_device *udev_device + + + + const char *udev_device_get_devnode + struct udev_device *udev_device + + + + dev_t udev_device_get_devnum + struct udev_device *udev_device + + + + const char *udev_device_get_devtype + struct udev_device *udev_device + + + + const char *udev_device_get_subsystem + struct udev_device *udev_device + + + + const char *udev_device_get_driver + struct udev_device *udev_device + + + + struct udev *udev_device_get_udev + struct udev_device *udev_device + + + + struct udev_device *udev_device_get_parent + struct udev_device *udev_device + + + + struct udev_device *udev_device_get_parent_with_subsystem_devtype + struct udev_device *udev_device + const char *subsystem + const char *devtype + + + + int udev_device_get_is_initialized + struct udev_device *udev_device + + + + const char *udev_device_get_action + struct udev_device *udev_device + + + + + + + + + Return Value + + On success, udev_device_get_syspath(), + udev_device_get_sysname(), + udev_device_get_sysnum(), + udev_device_get_devpath(), + udev_device_get_devnode(), + udev_device_get_devtype(), + udev_device_get_subsystem(), + udev_device_get_driver() and + udev_device_get_action() return a pointer + to a constant string that describes the requested property. The + lifetime of this string is bound to the device it was requested + on. On failure, each function may return + NULL. + + On success, udev_device_get_devnum() + returns the device type of the passed device. On failure, a + device type with minor and major number set to + 0 is returned. + + udev_device_get_udev() always returns + a valid pointer to the udev context that this device belongs + to. + + On success, udev_device_get_parent() + and + udev_device_get_parent_with_subsystem_devtype() + return a pointer to the parent device. No additional reference + to this device is acquired, but the child device owns a reference + to such a parent device. On failure, NULL + is returned. + + On success, udev_device_get_is_initialized() + returns either 1 or 0, + depending on whether the passed device is initialized or not. On + failure, a negative error code is returned. + + + + See Also + + + udev_new3, + udev_device_new_from_syspath3, + udev_device_has_tag3, + udev_enumerate_new3, + udev_monitor_new_from_netlink3, + udev_list_entry3, + systemd1, + + + + diff --git a/src/libudev/udev_device_has_tag.xml b/src/libudev/udev_device_has_tag.xml new file mode 100644 index 0000000000..480257343c --- /dev/null +++ b/src/libudev/udev_device_has_tag.xml @@ -0,0 +1,163 @@ + + +%entities; +]> + + + + + + + udev_device_has_tag + systemd + + + + Developer + David + Herrmann + dh.herrmann@gmail.com + + + + + + udev_device_has_tag + 3 + + + + udev_device_has_tag + udev_device_get_devlinks_list_entry + udev_device_get_properties_list_entry + udev_device_get_tags_list_entry + udev_device_get_sysattr_list_entry + udev_device_get_property_value + udev_device_get_sysattr_value + udev_device_set_sysattr_value + + Retrieve or set device attributes + + + + + #include <libudev.h> + + + struct udev_list_entry *udev_device_get_devlinks_list_entry + struct udev_device *udev_device + + + + struct udev_list_entry *udev_device_get_properties_list_entry + struct udev_device *udev_device + + + + struct udev_list_entry *udev_device_get_tags_list_entry + struct udev_device *udev_device + + + + struct udev_list_entry *udev_device_get_sysattr_list_entry + struct udev_device *udev_device + + + + const char *udev_device_get_property_value + struct udev_device *udev_device + const char *key + + + + int udev_device_has_tag + struct udev_device *udev_device + const char *tag + + + + const char *udev_device_get_sysattr_value + struct udev_device *udev_device + const char *sysattr + + + + int udev_device_set_sysattr_value + struct udev_device *udev_device + const char *sysattr + const char *value + + + + + + + + + Return Value + + On success, + udev_device_get_devlinks_list_entry(), + udev_device_get_properties_list_entry(), + udev_device_get_tags_list_entry() and + udev_device_get_sysattr_list_entry() return + a pointer to the first entry of the retrieved list. If that list + is empty, or if an error occurred, NULL is + returned. + + On success, + udev_device_get_property_value() and + udev_device_get_sysattr_value() return a + pointer to a constant string of the requested value. On error, + NULL is returned. + + On success, + udev_device_set_sysattr_value() returns + an integer greater than, or equal to, 0. + On failure, a negative error code is returned. + + On success, udev_device_has_tag() + returns 1 or 0, + depending on whether the device has the given tag or not. + On failure, a negative error code is returned. + + + + See Also + + + udev_new3, + udev_device_new_from_syspath3, + udev_device_get_syspath3, + udev_enumerate_new3, + udev_monitor_new_from_netlink3, + udev_list_entry3, + systemd1, + + + + diff --git a/src/libudev/udev_device_new_from_syspath.xml b/src/libudev/udev_device_new_from_syspath.xml new file mode 100644 index 0000000000..0bb71c8e91 --- /dev/null +++ b/src/libudev/udev_device_new_from_syspath.xml @@ -0,0 +1,214 @@ + + +%entities; +]> + + + + + + + udev_device_new_from_syspath + systemd + + + + Developer + David + Herrmann + dh.herrmann@gmail.com + + + + + + udev_device_new_from_syspath + 3 + + + + udev_device_new_from_syspath + udev_device_new_from_devnum + udev_device_new_from_subsystem_sysname + udev_device_new_from_device_id + udev_device_new_from_environment + udev_device_ref + udev_device_unref + + Create, acquire and release a udev device object + + + + + #include <libudev.h> + + + struct udev_device *udev_device_new_from_syspath + struct udev *udev + const char *syspath + + + + struct udev_device *udev_device_new_from_devnum + struct udev *udev + char type + dev_t devnum + + + + struct udev_device *udev_device_new_from_subsystem_sysname + struct udev *udev + const char *subsystem + const char *sysname + + + + struct udev_device *udev_device_new_from_device_id + struct udev *udev + const char *id + + + + struct udev_device *udev_device_new_from_environment + struct udev *udev + + + + struct udev_device *udev_device_ref + struct udev_device *udev_device + + + + struct udev_device *udev_device_unref + struct udev_device *udev_device + + + + + + + Description + + udev_device_new_from_syspath, + udev_device_new_from_devnum, + udev_device_new_from_subsystem_sysname, + udev_device_new_from_device_id, and + udev_device_new_from_environment + allocate a new udev device object and returns a pointer to it. This + object is opaque and must not be accessed by the caller via different + means than functions provided by libudev. Initially, the reference count + of the device is 1. You can acquire further references, and drop + gained references via udev_device_ref() and + udev_device_unref(). Once the reference count hits 0, + the device object is destroyed and freed. + + udev_device_new_from_syspath, + udev_device_new_from_devnum, + udev_device_new_from_subsystem_sysname, and + udev_device_new_from_device_id + create the device object based on information found in + /sys, annotated with properties from the udev-internal + device database. A syspath is any subdirectory of /sys, + with the restriction that a subdirectory of /sys/devices + (or a symlink to one) represents a real device and as such must contain + a uevent file. udev_device_new_from_devnum + takes a device type, which can be b for block devices or + c for character devices, as well as a devnum (see + makedev3). + udev_device_new_from_subsystem_sysname looks up devices based + on the provided subsystem and sysname + (see udev_device_get_subsystem3 + and + udev_device_get_sysname3) + and udev_device_new_from_device_id looks up devices based on the provided + device ID, which is a special string in one of the following four forms: + + Device ID strings + + + + + + Example + Explanation + + + b8:2 + block device major:minor + + c128:1 + char device major:minor + + n3 + network device ifindex + + +sound:card29 + kernel driver core subsystem:device name + + +
+ + + udev_device_new_from_environment + creates a device from the current environment (see + environ7). + Each key-value pair is interpreted in the same way as if it was + received in an uevent (see + udev_monitor_receive_device3). + The keys DEVPATH, SUBSYSTEM, + ACTION, and SEQNUM are mandatory. + + + + + Return Value + + On success, udev_device_new_from_syspath(), + udev_device_new_from_devnum(), + udev_device_new_from_subsystem_sysname(), + udev_device_new_from_device_id() and + udev_device_new_from_environment() return a + pointer to the allocated udev device. On failure, + NULL is returned, + and errno is set appropriately. + udev_device_ref() returns the argument + that it was passed, unmodified. + udev_device_unref() always returns + NULL. + + + + See Also + + + udev_new3, + udev_device_get_syspath3, + udev_device_has_tag3, + udev_enumerate_new3, + udev_monitor_new_from_netlink3, + udev_list_entry3, + systemd1, + + + + diff --git a/src/libudev/udev_enumerate_add_match_subsystem.xml b/src/libudev/udev_enumerate_add_match_subsystem.xml new file mode 100644 index 0000000000..5acce00bb0 --- /dev/null +++ b/src/libudev/udev_enumerate_add_match_subsystem.xml @@ -0,0 +1,163 @@ + + +%entities; +]> + + + + + + + udev_enumerate_add_match_subsystem + systemd + + + + Developer + David + Herrmann + dh.herrmann@gmail.com + + + + + + udev_enumerate_add_match_subsystem + 3 + + + + udev_enumerate_add_match_subsystem + udev_enumerate_add_nomatch_subsystem + udev_enumerate_add_match_sysattr + udev_enumerate_add_nomatch_sysattr + udev_enumerate_add_match_property + udev_enumerate_add_match_sysname + udev_enumerate_add_match_tag + udev_enumerate_add_match_parent + udev_enumerate_add_match_is_initialized + + Modify filters + + + + + #include <libudev.h> + + + int udev_enumerate_add_match_subsystem + struct udev_enumerate *udev_enumerate + const char *subsystem + + + + int udev_enumerate_add_nomatch_subsystem + struct udev_enumerate *udev_enumerate + const char *subsystem + + + + int udev_enumerate_add_match_sysattr + struct udev_enumerate *udev_enumerate + const char *sysattr + const char *value + + + + int udev_enumerate_add_nomatch_sysattr + struct udev_enumerate *udev_enumerate + const char *sysattr + const char *value + + + + int udev_enumerate_add_match_property + struct udev_enumerate *udev_enumerate + const char *property + const char *value + + + + int udev_enumerate_add_match_sysname + struct udev_enumerate *udev_enumerate + const char *sysname + + + + int udev_enumerate_add_match_tag + struct udev_enumerate *udev_enumerate + const char *tag + + + + int udev_enumerate_add_match_parent + struct udev_enumerate *udev_enumerate + struct udev_device *parent + + + + int udev_enumerate_add_match_is_initialized + struct udev_enumerate *udev_enumerate + + + + + + + + + Return Value + + On success, + udev_enumerate_add_match_subsystem, + udev_enumerate_add_nomatch_subsystem, + udev_enumerate_add_match_sysattr, + udev_enumerate_add_nomatch_sysattr, + udev_enumerate_add_match_property, + udev_enumerate_add_match_sysname, + udev_enumerate_add_match_tag, + udev_enumerate_add_match_parent and + udev_enumerate_add_match_is_initialized + return an integer greater than, or equal to, + 0. + + + + See Also + + + udev_new3, + udev_device_new_from_syspath3, + udev_enumerate_new3, + udev_enumerate_scan_devices3, + udev_monitor_new_from_netlink3, + udev_list_entry3, + systemd1, + + + + diff --git a/src/libudev/udev_enumerate_new.xml b/src/libudev/udev_enumerate_new.xml new file mode 100644 index 0000000000..b5856c5577 --- /dev/null +++ b/src/libudev/udev_enumerate_new.xml @@ -0,0 +1,111 @@ + + +%entities; +]> + + + + + + + udev_enumerate_new + systemd + + + + Developer + David + Herrmann + dh.herrmann@gmail.com + + + + + + udev_enumerate_new + 3 + + + + udev_enumerate_new + udev_enumerate_ref + udev_enumerate_unref + + Create, acquire and release a udev enumerate object + + + + + #include <libudev.h> + + + struct udev_enumerate *udev_enumerate_new + struct udev *udev + + + + struct udev_enumerate *udev_enumerate_ref + struct udev_enumerate *udev_enumerate + + + + struct udev_enumerate *udev_enumerate_unref + struct udev_enumerate *udev_enumerate + + + + + + + + + Return Value + + On success, udev_enumerate_new() returns a + pointer to the allocated udev monitor. On failure, + NULL is returned. + udev_enumerate_ref() returns the argument + that it was passed, unmodified. + udev_enumerate_unref() always returns + NULL. + + + + See Also + + + udev_new3, + udev_device_new_from_syspath3, + udev_enumerate_add_match_subsystem3, + udev_enumerate_scan_devices3, + udev_monitor_new_from_netlink3, + udev_list_entry3, + systemd1, + + + + diff --git a/src/libudev/udev_enumerate_scan_devices.xml b/src/libudev/udev_enumerate_scan_devices.xml new file mode 100644 index 0000000000..e0b6bfba32 --- /dev/null +++ b/src/libudev/udev_enumerate_scan_devices.xml @@ -0,0 +1,133 @@ + + +%entities; +]> + + + + + + + udev_enumerate_scan_devices + systemd + + + + Developer + David + Herrmann + dh.herrmann@gmail.com + + + + + + udev_enumerate_scan_devices + 3 + + + + udev_enumerate_scan_devices + udev_enumerate_scan_subsystems + udev_enumerate_get_list_entry + udev_enumerate_add_syspath + udev_enumerate_get_udev + + Query or modify a udev enumerate object + + + + + #include <libudev.h> + + + int udev_enumerate_scan_devices + struct udev_enumerate *udev_enumerate + + + + int udev_enumerate_scan_subsystems + struct udev_enumerate *udev_enumerate + + + + struct udev_list_entry *udev_enumerate_get_list_entry + struct udev_enumerate *udev_enumerate + + + + int udev_enumerate_add_syspath + struct udev_enumerate *udev_enumerate + const char *syspath + + + + struct udev *udev_enumerate_get_udev + struct udev_enumerate *udev_enumerate + + + + + + + + + Return Value + + On success, + udev_enumerate_scan_devices(), + udev_enumerate_scan_subsystems() and + udev_enumerate_add_syspath() + return an integer greater than, or equal to, + 0. + + On success, + udev_enumerate_get_list_entry() + returns a pointer to the first entry in the list of found + devices. If the list is empty, or on failure, + NULL is returned. + + udev_enumerate_get_udev() always + returns a pointer to the udev context that this enumerated + object is associated with. + + + + See Also + + + udev_new3, + udev_device_new_from_syspath3, + udev_enumerate_new3, + udev_enumerate_add_match_subsystem3, + udev_monitor_new_from_netlink3, + udev_list_entry3, + systemd1, + + + + diff --git a/src/libudev/udev_list_entry.xml b/src/libudev/udev_list_entry.xml new file mode 100644 index 0000000000..a1b531d52a --- /dev/null +++ b/src/libudev/udev_list_entry.xml @@ -0,0 +1,123 @@ + + +%entities; +]> + + + + + + + udev_list_entry + systemd + + + + Developer + David + Herrmann + dh.herrmann@gmail.com + + + + + + udev_list_entry + 3 + + + + udev_list_entry + udev_list_entry_get_next + udev_list_entry_get_by_name + udev_list_entry_get_name + udev_list_entry_get_value + + Iterate and access udev lists + + + + + #include <libudev.h> + + + struct udev_list_entry *udev_list_entry_get_next + struct udev_list_entry *list_entry + + + + struct udev_list_entry *udev_list_entry_get_by_name + struct udev_list_entry *list_entry + const char *name + + + + const char *udev_list_entry_get_name + struct udev_list_entry *list_entry + + + + const char *udev_list_entry_get_value + struct udev_list_entry *list_entry + + + + + + + + + Return Value + + On success, + udev_list_entry_get_next() and + udev_list_entry_get_by_name() return + a pointer to the requested list entry. If no such entry can + be found, or on failure, NULL is + returned. + + On success, + udev_list_entry_get_name() and + udev_list_entry_get_value() return a + pointer to a constant string representing the requested value. + The string is bound to the lifetime of the list entry itself. + On failure, NULL is returned. + + + + See Also + + + udev_new3, + udev_device_new_from_syspath3, + udev_enumerate_new3, + udev_monitor_new_from_netlink3, + systemd1, + + + + diff --git a/src/libudev/udev_monitor_filter_update.xml b/src/libudev/udev_monitor_filter_update.xml new file mode 100644 index 0000000000..f129595618 --- /dev/null +++ b/src/libudev/udev_monitor_filter_update.xml @@ -0,0 +1,122 @@ + + +%entities; +]> + + + + + + + udev_monitor_filter_update + systemd + + + + Developer + David + Herrmann + dh.herrmann@gmail.com + + + + + + udev_monitor_filter_update + 3 + + + + udev_monitor_filter_update + udev_monitor_filter_remove + udev_monitor_filter_add_match_subsystem_devtype + udev_monitor_filter_add_match_tag + + Modify filters + + + + + #include <libudev.h> + + + int udev_monitor_filter_update + struct udev_monitor *udev_monitor + + + + int udev_monitor_filter_remove + struct udev_monitor *udev_monitor + + + + int udev_monitor_filter_add_match_subsystem_devtype + struct udev_monitor *udev_monitor + const char *subsystem + const char *devtype + + + + int udev_monitor_filter_add_match_tag + struct udev_monitor *udev_monitor + const char *tag + + + + + + + + + Return Value + + On success, + udev_monitor_filter_update(), + udev_monitor_filter_remove(), + udev_monitor_filter_add_match_subsystem_devtype() + and + udev_monitor_filter_add_match_tag() + return an integer greater than, or equal to, + 0. On failure, a negative error code is + returned. + + + + See Also + + + udev_new3, + udev_device_new_from_syspath3, + udev_enumerate_new3, + udev_monitor_new_from_netlink3, + udev_monitor_receive_device3, + udev_list_entry3, + systemd1, + + + + diff --git a/src/libudev/udev_monitor_new_from_netlink.xml b/src/libudev/udev_monitor_new_from_netlink.xml new file mode 100644 index 0000000000..d73a4acaec --- /dev/null +++ b/src/libudev/udev_monitor_new_from_netlink.xml @@ -0,0 +1,113 @@ + + +%entities; +]> + + + + + + + udev_monitor_new_from_netlink + systemd + + + + Developer + David + Herrmann + dh.herrmann@gmail.com + + + + + + udev_monitor_new_from_netlink + 3 + + + + udev_monitor_new_from_netlink + udev_monitor_ref + udev_monitor_unref + + Create, acquire and release a udev monitor object + + + + + #include <libudev.h> + + + struct udev_monitor *udev_monitor_new_from_netlink + struct udev *udev + const char *name + + + + struct udev_monitor *udev_monitor_ref + struct udev_monitor *udev_monitor + + + + struct udev_monitor *udev_monitor_unref + struct udev_monitor *udev_monitor + + + + + + + + + Return Value + + On success, + udev_monitor_new_from_netlink() returns a + pointer to the allocated udev monitor. On failure, + NULL is returned. + udev_monitor_ref() returns the argument + that it was passed, unmodified. + udev_monitor_unref() always returns + NULL. + + + + See Also + + + udev_new3, + udev_device_new_from_syspath3, + udev_enumerate_new3, + udev_monitor_filter_update3, + udev_monitor_receive_device3, + udev_list_entry3, + systemd1, + + + + diff --git a/src/libudev/udev_monitor_receive_device.xml b/src/libudev/udev_monitor_receive_device.xml new file mode 100644 index 0000000000..7e842f88df --- /dev/null +++ b/src/libudev/udev_monitor_receive_device.xml @@ -0,0 +1,137 @@ + + +%entities; +]> + + + + + + + udev_monitor_receive_device + systemd + + + + Developer + David + Herrmann + dh.herrmann@gmail.com + + + + + + udev_monitor_receive_device + 3 + + + + udev_monitor_receive_device + udev_monitor_enable_receiving + udev_monitor_set_receive_buffer_size + udev_monitor_get_fd + udev_monitor_get_udev + + Query and modify device monitor + + + + + #include <libudev.h> + + + struct udev_device *udev_monitor_receive_device + struct udev_monitor *udev_monitor + + + + int udev_monitor_enable_receiving + struct udev_monitor *udev_monitor + + + + int udev_monitor_set_receive_buffer_size + struct udev_monitor *udev_monitor + int size + + + + int udev_monitor_get_fd + struct udev_monitor *udev_monitor + + + + struct udev *udev_monitor_get_udev + struct udev_monitor *udev_monitor + + + + + + + + + Return Value + + On success, + udev_monitor_receive_device() returns a + pointer to a newly referenced device that was received via the + monitor. The caller is responsible to drop this reference when + done. On failure, NULL is returned. + + On success, + udev_monitor_enable_receiving() and + udev_monitor_set_receive_buffer_size() + return an integer greater than, or equal to, + 0. On failure, a negative error code is + returned. + + On success, udev_monitor_get_fd() + returns the file descriptor used by this monitor. On failure, + a negative error code is returned. + + udev_monitor_get_udev() always returns + a pointer to the udev context that this monitor is associated + with. + + + + See Also + + + udev_new3, + udev_device_new_from_syspath3, + udev_enumerate_new3, + udev_monitor_new_from_netlink3, + udev_monitor_filter_update3, + udev_list_entry3, + systemd1, + + + + diff --git a/src/libudev/udev_new.xml b/src/libudev/udev_new.xml new file mode 100644 index 0000000000..587835a3ca --- /dev/null +++ b/src/libudev/udev_new.xml @@ -0,0 +1,110 @@ + + +%entities; +]> + + + + + + + udev_new + systemd + + + + Developer + David + Herrmann + dh.herrmann@gmail.com + + + + + + udev_new + 3 + + + + udev_new + udev_ref + udev_unref + + Create, acquire and release a udev context object + + + + + #include <libudev.h> + + + struct udev *udev_new + void + + + + struct udev *udev_ref + struct udev *udev + + + + struct udev *udev_unref + struct udev *udev + + + + + + + Description + + udev_new() allocates a new udev context + object and returns a pointer to it. This object is opaque and must + not be accessed by the caller via different means than functions + provided by libudev. Initially, the reference count of the context + is 1. You can acquire further references, and drop gained references + via udev_ref() and + udev_unref(). Once the reference count hits 0, + the context object is destroyed and freed. + + + + Return Value + + On success, udev_new() returns a pointer + to the allocated udev context. On failure, NULL + is returned. udev_ref() returns the argument + that it was passed, unmodified. udev_unref() + always returns NULL. + + + + See Also + + + systemd1, + + + + diff --git a/src/nss-myhostname/nss-myhostname.xml b/src/nss-myhostname/nss-myhostname.xml new file mode 100644 index 0000000000..a920ec334f --- /dev/null +++ b/src/nss-myhostname/nss-myhostname.xml @@ -0,0 +1,148 @@ + + + + + + + + + nss-myhostname + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + nss-myhostname + 8 + + + + nss-myhostname + libnss_myhostname.so.2 + Provide hostname resolution for the locally + configured system hostname. + + + + libnss_myhostname.so.2 + + + + Description + + nss-myhostname is a plug-in module for the GNU Name Service Switch (NSS) functionality of + the GNU C Library (glibc), primarily providing hostname resolution for the locally configured + system hostname as returned by + gethostname2. The precise + hostnames resolved by this module are: + + + The local, configured hostname is resolved to + all locally configured IP addresses ordered by their scope, or + — if none are configured — the IPv4 address 127.0.0.2 (which + is on the local loopback) and the IPv6 address ::1 (which is the + local host). + + The hostnames localhost and + localhost.localdomain (as well as any hostname + ending in .localhost or .localhost.localdomain) + are resolved to the IP addresses 127.0.0.1 and ::1. + + The hostname gateway is + resolved to all current default routing gateway addresses, + ordered by their metric. This assigns a stable hostname to the + current gateway, useful for referencing it independently of the + current network configuration state. + + + Various software relies on an always-resolvable local + hostname. When using dynamic hostnames, this is traditionally + achieved by patching /etc/hosts at the same + time as changing the hostname. This is problematic since it + requires a writable /etc file system and is + fragile because the file might be edited by the administrator at + the same time. With nss-myhostname enabled, + changing /etc/hosts is unnecessary, and on + many systems, the file becomes entirely optional. + + To activate the NSS modules, add myhostname to the line starting with + hosts: in /etc/nsswitch.conf. + + It is recommended to place myhostname last in the nsswitch.conf' + hosts: line to make sure that this mapping is only used as fallback, and that any DNS or + /etc/hosts based mapping takes precedence. + + + + Example + + Here is an example /etc/nsswitch.conf file that enables + nss-myhostname correctly: + +passwd: compat mymachines +group: compat mymachines +shadow: compat + +hosts: files mymachines resolve myhostname +networks: files + +protocols: db files +services: db files +ethers: db files +rpc: db files + +netgroup: nis + + To test, use glibc's getent tool: + + $ getent ahosts `hostname` +::1 STREAM omega +::1 DGRAM +::1 RAW +127.0.0.2 STREAM +127.0.0.2 DGRAM +127.0.0.2 RAW + + In this case, the local hostname is omega. + + + + + See Also + + systemd1, + nss-resolve8, + nss-mymachines8, + nsswitch.conf5, + getent1 + + + + diff --git a/src/systemd-ask-password/systemd-ask-password.xml b/src/systemd-ask-password/systemd-ask-password.xml new file mode 100644 index 0000000000..2b6fb5a82f --- /dev/null +++ b/src/systemd-ask-password/systemd-ask-password.xml @@ -0,0 +1,227 @@ + + + + + + + + + systemd-ask-password + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-ask-password + 1 + + + + systemd-ask-password + Query the user for a system password + + + + + systemd-ask-password OPTIONS MESSAGE + + + + + Description + + systemd-ask-password may be used to query + a system password or passphrase from the user, using a question + message specified on the command line. When run from a TTY it will + query a password on the TTY and print it to standard output. When + run with no TTY or with it will query + the password system-wide and allow active users to respond via + several agents. The latter is only available to privileged + processes. + + The purpose of this tool is to query system-wide passwords + — that is passwords not attached to a specific user account. + Examples include: unlocking encrypted hard disks when they are + plugged in or at boot, entering an SSL certificate passphrase for + web and VPN servers. + + Existing agents are: + + + A boot-time password agent asking the user for + passwords using Plymouth + + A boot-time password agent querying the user + directly on the console + + An agent requesting password input via a + wall1 + message + + A command line agent which can be started + temporarily to process queued password + requests + + A TTY agent that is temporarily spawned during + systemctl1 + invocations + + + Additional password agents may be implemented according to + the systemd + Password Agent Specification. + + If a password is queried on a TTY, the user may press TAB to + hide the asterisks normally shown for each character typed. + Pressing Backspace as first key achieves the same effect. + + + + + Options + + The following options are understood: + + + + + + Specify an icon name alongside the password + query, which may be used in all agents supporting graphical + display. The icon name should follow the XDG + Icon Naming Specification. + + + + + Specify an identifier for this password + query. This identifier is freely choosable and allows + recognition of queries by involved agents. It should include + the subsystem doing the query and the specific object the + query is done for. Example: + --id=cryptsetup:/dev/sda5. + + + + + Configure a kernel keyring key name to use as + cache for the password. If set, then the tool will try to push + any collected passwords into the kernel keyring of the root + user, as a key of the specified name. If combined with + , it will also try to retrieve + such cached passwords from the key in the kernel keyring + instead of querying the user right away. By using this option, + the kernel keyring may be used as effective cache to avoid + repeatedly asking users for passwords, if there are multiple + objects that may be unlocked with the same password. The + cached key will have a timeout of 2.5min set, after which it + will be purged from the kernel keyring. Note that it is + possible to cache multiple passwords under the same keyname, + in which case they will be stored as NUL-separated list of + passwords. Use + keyctl1 + to access the cached key via the kernel keyring + directly. Example: --keyname=cryptsetup + + + + + + Specify the query timeout in seconds. Defaults + to 90s. A timeout of 0 waits indefinitely. + + + + + + Echo the user input instead of masking it. + This is useful when using + systemd-ask-password to query for + usernames. + + + + + + Never ask for password on current TTY even if + one is available. Always use agent system. + + + + + + If passed, accept cached passwords, i.e. + passwords previously entered. + + + + + + When used in conjunction with + accept multiple passwords. + This will output one password per line. + + + + + + Do not print passwords to standard output. + This is useful if you want to store a password in kernel + keyring with but do not want it + to show up on screen or in logs. + + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + See Also + + systemd1, + systemctl1, + keyctl1, + plymouth8, + wall1 + + + + diff --git a/src/systemd-cgls/systemd-cgls.xml b/src/systemd-cgls/systemd-cgls.xml new file mode 100644 index 0000000000..e8f0368f48 --- /dev/null +++ b/src/systemd-cgls/systemd-cgls.xml @@ -0,0 +1,139 @@ + + + + + + + + + systemd-cgls + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-cgls + 1 + + + + systemd-cgls + Recursively show control group contents + + + + + systemd-cgls + OPTIONS + CGROUP + + + + + Description + + systemd-cgls recursively shows the + contents of the selected Linux control group hierarchy in a tree. + If arguments are specified, shows all member processes of the + specified control groups plus all their subgroups and their + members. The control groups may either be specified by their full + file paths or are assumed in the systemd control group hierarchy. + If no argument is specified and the current working directory is + beneath the control group mount point + /sys/fs/cgroup, shows the contents of the + control group the working directory refers to. Otherwise, the full + systemd control group hierarchy is shown. + + By default, empty control groups are not shown. + + + + Options + + The following options are understood: + + + + + + Do not hide empty control groups in the + output. + + + + + + + Do not ellipsize process tree members. + + + + + + + Include kernel threads in output. + + + + + + + + Limit control groups shown to the part + corresponding to the container + MACHINE. + + + + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + See Also + + systemd1, + systemctl1, + systemd-cgtop1, + systemd-nspawn1, + ps1 + + + + diff --git a/src/systemd-cgtop/systemd-cgtop.xml b/src/systemd-cgtop/systemd-cgtop.xml new file mode 100644 index 0000000000..c76f646984 --- /dev/null +++ b/src/systemd-cgtop/systemd-cgtop.xml @@ -0,0 +1,373 @@ + + + + + + + + + systemd-cgtop + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-cgtop + 1 + + + + systemd-cgtop + Show top control groups by their resource usage + + + + + systemd-cgtop + OPTIONS + + + + + Description + + systemd-cgtop shows the top control + groups of the local Linux control group hierarchy, ordered by + their CPU, memory, or disk I/O load. The display is refreshed in + regular intervals (by default every 1s), similar in style to + top1. + + If systemd-cgtop is not connected to a + tty, no column headers are printed and the default is to only run + one iteration. The --iterations= argument, if + given, is honored. This mode is suitable for scripting. + + Resource usage is only accounted for control groups in the + relevant hierarchy, i.e. CPU usage is only accounted for control + groups in the cpuacct hierarchy, memory usage + only for those in memory and disk I/O usage for + those in blkio. If resource monitoring for + these resources is required, it is recommended to add the + CPUAccounting=1, + MemoryAccounting=1 and + BlockIOAccounting=1 settings in the unit files + in question. See + systemd.resource-control5 + for details. + + The CPU load value can be between 0 and 100 times the number of + processors the system has. For example, if the system has 8 processors, + the CPU load value is going to be between 0% and 800%. The number of + processors can be found in /proc/cpuinfo. + + To emphasize this: unless + CPUAccounting=1, + MemoryAccounting=1 and + BlockIOAccounting=1 are enabled for the + services in question, no resource accounting will be available for + system services and the data shown by + systemd-cgtop will be incomplete. + + + + Options + + The following options are understood: + + + + + + + Order by control group + path name. + + + + + + + Order by number of tasks/processes in the control group. + + + + + + + Order by CPU load. + + + + + + + Order by memory usage. + + + + + + + Order by disk I/O load. + + + + + + + Run in "batch" mode: do not accept input and + run until the iteration limit set with + is exhausted or until killed. + This mode could be useful for sending output from + systemd-cgtop to other programs or to a + file. + + + + + + + Format byte counts (as in memory usage and I/O metrics) + with raw numeric values rather than human-readable + numbers. + + + + + + + Controls whether the CPU usage is shown as + percentage or time. By default, the CPU usage is shown as + percentage. This setting may also be toggled at runtime by + pressing the % key. + + + + + + Count only userspace processes instead of all + tasks. By default, all tasks are counted: each kernel thread + and each userspace thread individually. With this setting, + kernel threads are excluded from the counting and each + userspace process only counts as one, regardless how many + threads it consists of. This setting may also be toggled at + runtime by pressing the P key. This option + may not be combined with + . + + + + + + Count only userspace processes and kernel + threads instead of all tasks. By default, all tasks are + counted: each kernel thread and each userspace thread + individually. With this setting, kernel threads are included in + the counting and each userspace process only counts as on one, + regardless how many threads it consists of. This setting may + also be toggled at runtime by pressing the k + key. This option may not be combined with + . + + + + + + Controls whether the number of processes shown + for a control group shall include all processes that are + contained in any of the child control groups as well. Takes a + boolean argument, which defaults to yes. If + enabled, the processes in child control groups are included, if + disabled, only the processes in the control group itself are + counted. This setting may also be toggled at runtime by + pressing the r key. Note that this setting + only applies to process counting, i.e. when the + or options are + used. It has not effect if all tasks are counted, in which + case the counting is always recursive. + + + + + + + Perform only this many iterations. A value of + 0 indicates that the program should run + indefinitely. + + + + + + + Specify refresh delay in seconds (or if one of + ms, us, + min is specified as unit in this time + unit). This setting may also be increased and decreased at + runtime by pressing the + and + - keys. + + + + + + Maximum control group tree traversal depth. + Specifies how deep systemd-cgtop shall + traverse the control group hierarchies. If 0 is specified, + only the root group is monitored. For 1, only the first level + of control groups is monitored, and so on. Defaults to + 3. + + + + + + + Limit control groups shown to the part + corresponding to the container + MACHINE. + + + + + + + + + + Keys + + systemd-cgtop is an interactive tool and + may be controlled via user input using the following keys: + + + + h + + Shows a short help text. + + + + + + Immediately refresh output. + + + + q + + Terminate the program. + + + + p + t + c + m + i + + Sort the control groups by path, number of + tasks, CPU load, memory usage, or I/O load, respectively. This + setting may also be controlled using the + command line + switch. + + + + % + + Toggle between showing CPU time as time or + percentage. This setting may also be controlled using the + command line switch. + + + + + + - + + Increase or decrease refresh delay, + respectively. This setting may also be controlled using the + command line + switch. + + + + P + + Toggle between counting all tasks, or only + userspace processes. This setting may also be controlled using + the command line switch (see + above). + + + + k + + Toggle between counting all tasks, or only + userspace processes and kernel threads. This setting may also + be controlled using the command line + switch (see above). + + + + r + + Toggle between recursively including or + excluding processes in child control groups in control group + process counts. This setting may also be controlled using the + command line switch. This key is + not available if all tasks are counted, it is only available + if processes are counted, as enabled with the + P or k + keys. + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + See Also + + systemd1, + systemctl1, + systemd-cgls1, + systemd.resource-control5, + top1 + + + + diff --git a/src/systemd-cryptsetup/crypttab.xml b/src/systemd-cryptsetup/crypttab.xml new file mode 100644 index 0000000000..1de834a045 --- /dev/null +++ b/src/systemd-cryptsetup/crypttab.xml @@ -0,0 +1,416 @@ + + + + + + + + crypttab + systemd + + + + Documentation + Miloslav + Trmac + mitr@redhat.com + + + Documentation + Lennart + Poettering + lennart@poettering.net + + + + + + crypttab + 5 + + + + crypttab + Configuration for encrypted block devices + + + + /etc/crypttab + + + + Description + + The /etc/crypttab file describes + encrypted block devices that are set up during system boot. + + Empty lines and lines starting with the # + character are ignored. Each of the remaining lines describes one + encrypted block device, fields on the line are delimited by white + space. The first two fields are mandatory, the remaining two are + optional. + + Setting up encrypted block devices using this file supports + three encryption modes: LUKS, TrueCrypt and plain. See + cryptsetup8 + for more information about each mode. When no mode is specified in + the options field and the block device contains a LUKS signature, + it is opened as a LUKS device; otherwise, it is assumed to be in + raw dm-crypt (plain mode) format. + + The first field contains the name of the resulting encrypted + block device; the device is set up within + /dev/mapper/. + + The second field contains a path to the underlying block + device or file, or a specification of a block device via + UUID= followed by the UUID. + + The third field specifies the encryption password. If the + field is not present or the password is set to + none or -, the password has + to be manually entered during system boot. Otherwise, the field is + interpreted as a absolute path to a file containing the encryption + password. For swap encryption, /dev/urandom + or the hardware device /dev/hw_random can be + used as the password file; using /dev/random + may prevent boot completion if the system does not have enough + entropy to generate a truly random encryption key. + + The fourth field, if present, is a comma-delimited list of + options. The following options are recognized: + + + + + + + Allow discard requests to be passed through + the encrypted block device. This improves performance on SSD + storage but has security implications. + + + + + + Specifies the cipher to use. See + cryptsetup8 + for possible values and the default value of this option. A + cipher with unpredictable IV values, such as + aes-cbc-essiv:sha256, is + recommended. + + + + + + Specifies the hash to use for password + hashing. See + cryptsetup8 + for possible values and the default value of this + option. + + + + + + Use a detached (separated) metadata device or + file where the LUKS header is stored. This option is only + relevant for LUKS devices. See + cryptsetup8 + for possible values and the default value of this + option. + + + + + + Start offset in the backend device, in 512-byte sectors. + This option is only relevant for plain devices. + + + + + + + How many 512-byte sectors of the encrypted data to skip + at the beginning. This is different from the + option with respect to the sector numbers used in initialization vector + (IV) calculation. Using will shift the IV + calculation by the same negative amount. Hence, if is given, + sector n will get a sector number of 0 for the IV calculation. + Using causes sector n to also be the first + sector of the mapped device, but with its number for IV generation being n. + + This option is only relevant for plain devices. + + + + + + + Specifies the number of bytes to skip at the + start of the key file. See + cryptsetup8 + for possible values and the default value of this + option. + + + + + + Specifies the maximum number of bytes to read + from the key file. See + cryptsetup8 + for possible values and the default value of this option. This + option is ignored in plain encryption mode, as the key file + size is then given by the key size. + + + + + + Specifies the key slot to compare the + passphrase or key against. If the key slot does not match the + given passphrase or key, but another would, the setup of the + device will fail regardless. This option implies + . See + cryptsetup8 + for possible values. The default is to try all key slots in + sequential order. + + + + + + Force LUKS mode. When this mode is used, the + following options are ignored since they are provided by the + LUKS header on the device: , + , + . + + + + + + This device will not be automatically unlocked + on boot. + + + + + + The system will not wait for the device to + show up and be unlocked at boot, and not fail the boot if it + does not show up. + + + + + + Force plain encryption mode. + + + + + + Set up the encrypted block device in read-only + mode. + + + + + + Specifies the key size in bits. See + cryptsetup8 + for possible values and the default value of this + option. + + + + + + The encrypted block device will be used as a + swap device, and will be formatted accordingly after setting + up the encrypted block device, with + mkswap8. + This option implies . + + WARNING: Using the option will + destroy the contents of the named partition during every boot, + so make sure the underlying block device is specified + correctly. + + + + + + Use TrueCrypt encryption mode. When this mode + is used, the following options are ignored since they are + provided by the TrueCrypt header on the device or do not + apply: + , + , + , + , + . + + When this mode is used, the passphrase is read from the + key file given in the third field. Only the first line of this + file is read, excluding the new line character. + + Note that the TrueCrypt format uses both passphrase and + key files to derive a password for the volume. Therefore, the + passphrase and all key files need to be provided. Use + to provide the absolute path + to all key files. When using an empty passphrase in + combination with one or more key files, use + /dev/null as the password file in the third + field. + + + + + + Use the hidden TrueCrypt volume. This option + implies . + + This will map the hidden volume that is inside of the + volume provided in the second field. Please note that there is + no protection for the hidden volume if the outer volume is + mounted instead. See + cryptsetup8 + for more information on this limitation. + + + + + + Specifies the absolute path to a key file to + use for a TrueCrypt volume. This implies + and can be used more than once to + provide several key files. + + See the entry for on the + behavior of the passphrase and key files when using TrueCrypt + encryption mode. + + + + + + Use TrueCrypt in system encryption mode. This + option implies . + + + + + + Specifies the timeout for querying for a + password. If no unit is specified, seconds is used. Supported + units are s, ms, us, min, h, d. A timeout of 0 waits + indefinitely (which is the default). + + + + + + Specifies how long systemd should wait for a + device to show up before giving up on the entry. The argument + is a time in seconds or explicitly specified units of + s, + min, + h, + ms. + + + + + + + The encrypted block device will be prepared + for using it as /tmp; it will be + formatted using + mke2fs8. + This option implies . + + WARNING: Using the option will + destroy the contents of the named partition during every boot, + so make sure the underlying block device is specified + correctly. + + + + + + Specifies the maximum number of times the user + is queried for a password. The default is 3. If set to 0, the + user is queried for a password indefinitely. + + + + + + If the encryption password is read from + console, it has to be entered twice to prevent + typos. + + + + + At early boot and when the system manager configuration is + reloaded, this file is translated into native systemd units by + systemd-cryptsetup-generator8. + + + + Example + + /etc/crypttab example + Set up four encrypted block devices. One using LUKS for + normal storage, another one for usage as a swap device and two + TrueCrypt volumes. + + luks UUID=2505567a-9e27-4efe-a4d5-15ad146c258b +swap /dev/sda7 /dev/urandom swap +truecrypt /dev/sda2 /etc/container_password tcrypt +hidden /mnt/tc_hidden /dev/null tcrypt-hidden,tcrypt-keyfile=/etc/keyfile + + + + + See Also + + systemd1, + systemd-cryptsetup@.service8, + systemd-cryptsetup-generator8, + cryptsetup8, + mkswap8, + mke2fs8 + + + + diff --git a/src/systemd-cryptsetup/systemd-cryptsetup-generator.xml b/src/systemd-cryptsetup/systemd-cryptsetup-generator.xml new file mode 100644 index 0000000000..f036ab9744 --- /dev/null +++ b/src/systemd-cryptsetup/systemd-cryptsetup-generator.xml @@ -0,0 +1,193 @@ + + + + + + + + systemd-cryptsetup-generator + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-cryptsetup-generator + 8 + + + + systemd-cryptsetup-generator + Unit generator for /etc/crypttab + + + + /usr/lib/systemd/system-generators/systemd-cryptsetup-generator + + + + Description + + systemd-cryptsetup-generator is a + generator that translates /etc/crypttab into + native systemd units early at boot and when configuration of the + system manager is reloaded. This will create + systemd-cryptsetup@.service8 + units as necessary. + + systemd-cryptsetup-generator implements + systemd.generator7. + + + + Kernel Command Line + + systemd-cryptsetup-generator + understands the following kernel command line parameters: + + + + luks= + rd.luks= + + Takes a boolean argument. Defaults to + yes. If no, disables the + generator entirely. rd.luks= is honored + only by initial RAM disk (initrd) while + luks= is honored by both the main system + and the initrd. + + + + luks.crypttab= + rd.luks.crypttab= + + Takes a boolean argument. Defaults to + yes. If no, causes the + generator to ignore any devices configured in + /etc/crypttab + (luks.uuid= will still work however). + rd.luks.crypttab= is honored only by + initial RAM disk (initrd) while + luks.crypttab= is honored by both the main + system and the initrd. + + + + luks.uuid= + rd.luks.uuid= + + Takes a LUKS superblock UUID as argument. This + will activate the specified device as part of the boot process + as if it was listed in /etc/crypttab. + This option may be specified more than once in order to set up + multiple devices. rd.luks.uuid= is honored + only by initial RAM disk (initrd) while + luks.uuid= is honored by both the main + system and the initrd. + If /etc/crypttab contains entries with the same UUID, + then the name, keyfile and options specified there will be + used. Otherwise, the device will have the name + luks-UUID. + If /etc/crypttab exists, only those UUIDs + specified on the kernel command line + will be activated in the initrd or the real root. + + + + + luks.name= + rd.luks.name= + + Takes a LUKS super block UUID followed by an + = and a name. This implies + rd.luks.uuid= or + luks.uuid= and will additionally make the + LUKS device given by the UUID appear under the provided + name. + + rd.luks.name= is honored only by + initial RAM disk (initrd) while luks.name= + is honored by both the main system and the initrd. + + + + + luks.options= + rd.luks.options= + + Takes a LUKS super block UUID followed by an + = and a string of options separated by + commas as argument. This will override the options for the + given UUID. + If only a list of options, without an UUID, is + specified, they apply to any UUIDs not specified elsewhere, + and without an entry in + /etc/crypttab. + rd.luks.options= is honored only by initial + RAM disk (initrd) while luks.options= is + honored by both the main system and the initrd. + + + + + luks.key= + rd.luks.key= + + Takes a password file name as argument or a + LUKS super block UUID followed by a = and a + password file name. + + For those entries specified with + rd.luks.uuid= or + luks.uuid=, the password file will be set + to the one specified by rd.luks.key= or + luks.key= of the corresponding UUID, or the + password file that was specified without a UUID. + rd.luks.key= + is honored only by initial RAM disk + (initrd) while + luks.key= is + honored by both the main system and + the initrd. + + + + + + + See Also + + systemd1, + crypttab5, + systemd-cryptsetup@.service8, + cryptsetup8, + systemd-fstab-generator8 + + + + diff --git a/src/systemd-cryptsetup/systemd-cryptsetup@.service.xml b/src/systemd-cryptsetup/systemd-cryptsetup@.service.xml new file mode 100644 index 0000000000..ea524851eb --- /dev/null +++ b/src/systemd-cryptsetup/systemd-cryptsetup@.service.xml @@ -0,0 +1,85 @@ + + + + + + + + systemd-cryptsetup@.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-cryptsetup@.service + 8 + + + + systemd-cryptsetup@.service + systemd-cryptsetup + Full disk decryption logic + + + + systemd-cryptsetup@.service + /usr/lib/systemd/systemd-cryptsetup + + + + Description + + systemd-cryptsetup@.service is a + service responsible for setting up encrypted block devices. It is + instantiated for each device that requires decryption for + access. + + systemd-cryptsetup@.service will ask + for hard disk passwords via the + password agent logic, in order to query the user for the + password using the right mechanism at boot and during + runtime. + + At early boot and when the system manager configuration is + reloaded this /etc/crypttab is translated + into systemd-cryptsetup@.service units by + systemd-cryptsetup-generator8. + + + + See Also + + systemd1, + systemd-cryptsetup-generator8, + crypttab5, + cryptsetup8 + + + + diff --git a/src/systemd-debug-generator/systemd-debug-generator.xml b/src/systemd-debug-generator/systemd-debug-generator.xml new file mode 100644 index 0000000000..5c5e9fc4a1 --- /dev/null +++ b/src/systemd-debug-generator/systemd-debug-generator.xml @@ -0,0 +1,95 @@ + + + + + + + + systemd-debug-generator + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-debug-generator + 8 + + + + systemd-debug-generator + Generator for enabling a runtime debug shell and + masking specific units at boot + + + + /usr/lib/systemd/system-generators/systemd-debug-generator + + + + Description + + systemd-debug-generator is a generator + that reads the kernel command line and understands three + options: + + If the option is specified + and followed by a unit name, this unit is masked for the runtime, + similar to the effect of + systemctl1's + mask command. This is useful to boot with + certain units removed from the initial boot transaction for + debugging system startup. May be specified more than once. + + If the option is specified + and followed by a unit name, a start job for this unit is added to + the initial transaction. This is useful to start one or more + additional units at boot. May be specified more than once. + + If the option is + specified, the debug shell service + debug-shell.service is pulled into the boot + transaction. It will spawn a debug shell on tty9 during early + system startup. Note that the shell may also be turned on + persistently by enabling it with + systemctl1's + enable command. + + systemd-debug-generator implements + systemd.generator7. + + + + See Also + + systemd1, + systemctl1, + kernel-command-line7 + + + + diff --git a/src/systemd-getty-generator/systemd-getty-generator.xml b/src/systemd-getty-generator/systemd-getty-generator.xml new file mode 100644 index 0000000000..338925964d --- /dev/null +++ b/src/systemd-getty-generator/systemd-getty-generator.xml @@ -0,0 +1,96 @@ + + + + + + + + systemd-getty-generator + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-getty-generator + 8 + + + + systemd-getty-generator + Generator for enabling getty instances on the + console + + + + /usr/lib/systemd/system-generators/systemd-getty-generator + + + + Description + + systemd-getty-generator is a generator + that automatically instantiates + serial-getty@.service on the kernel console + /dev/console if that is not directed to the + virtual console subsystem. It will also instantiate + serial-getty@.service instances for + virtualizer consoles, if execution in a virtualized environment is + detected. Finally, it will instantiate + container-getty@.service instances for + additional container pseudo TTYs as requested by the container + manager (see Container + Interface). This should ensure that the user is + shown a login prompt at the right place, regardless of which + environment the system is started in. For example, it is + sufficient to redirect the kernel console with a kernel command + line argument such as console= to get both + kernel messages and a getty prompt on a serial TTY. See kernel-parameters.txt + for more information on the console= kernel + parameter. + + systemd-getty-generator implements + systemd.generator7. + + Further information about configuration of gettys you may + find in + systemd + for Administrators, Part XVI: Gettys on Serial Consoles (and + Elsewhere). + + + + See Also + + systemd1, + agetty8 + + + + diff --git a/src/systemd-gpt-auto-generator/systemd-gpt-auto-generator.xml b/src/systemd-gpt-auto-generator/systemd-gpt-auto-generator.xml new file mode 100644 index 0000000000..e890c4dce2 --- /dev/null +++ b/src/systemd-gpt-auto-generator/systemd-gpt-auto-generator.xml @@ -0,0 +1,186 @@ + + + + + + + + systemd-gpt-auto-generator + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-gpt-auto-generator + 8 + + + + systemd-gpt-auto-generator + Generator for automatically discovering + and mounting root, /home and + /srv partitions, as well as + discovering and enabling swap partitions, based on GPT + partition type GUIDs. + + + + /usr/lib/systemd/system-generators/systemd-gpt-auto-generator + + + + Description + + systemd-gpt-auto-generator is a unit + generator that automatically discovers root, + /home, /srv and swap + partitions and creates mount and swap units for them, based on the + partition type GUIDs of GUID partition tables (GPT). It implements + the Discoverable + Partitions Specification. Note that this generator has no + effect on non-GPT systems, or where the directories under the + mount points are already non-empty. Also, on systems where the + units are explicitly configured (for example, listed in + fstab5), + the units this generator creates are overridden, but additional + automatic dependencies might be created. + + This generator will only look for root partitions on the + same physical disk the EFI System Partition (ESP) is located on. + It will only look for the other partitions on the same physical + disk the root file system is located on. These partitions will not + be searched on systems where the root file system is distributed + on multiple disks, for example via btrfs RAID. + + systemd-gpt-auto-generator is useful + for centralizing file system configuration in the partition table + and making manual configuration in /etc/fstab + or suchlike unnecessary. + + This generator looks for the partitions based on their + partition type GUID. The following partition type GUIDs are + identified: + + + Partition Type GUIDs + + + + + + + Partition Type GUID + Name + Explanation + + + + + 44479540-f297-41b2-9af7-d131d5f0458a + Root Partition (x86) + On 32-bit x86 systems, the first x86 root partition on the disk the EFI ESP is located on is mounted to the root directory /. + + + 4f68bce3-e8cd-4db1-96e7-fbcaf984b709 + Root Partition (x86-64) + On 64-bit x86 systems, the first x86-64 root partition on the disk the EFI ESP is located on is mounted to the root directory /. + + + 69dad710-2ce4-4e3c-b16c-21a1d49abed3 + Root Partition (32-bit ARM) + On 32-bit ARM systems, the first ARM root partition on the disk the EFI ESP is located on is mounted to the root directory /. + + + b921b045-1df0-41c3-af44-4c6f280d3fae + Root Partition (64-bit ARM) + On 64-bit ARM systems, the first ARM root partition on the disk the EFI ESP is located on is mounted to the root directory /. + + + 933ac7e1-2eb4-4f13-b844-0e14e2aef915 + Home Partition + The first home partition on the disk the root partition is located on is mounted to /home. + + + 3b8f8425-20e0-4f3b-907f-1a25a76f98e8 + Server Data Partition + The first server data partition on the disk the root partition is located on is mounted to /srv. + + + 0657fd6d-a4ab-43c4-84e5-0933c84b4f4f + Swap + All swap partitions located on the disk the root partition is located on are enabled. + + + +
+ + The /home and /srv + partitions may be encrypted in LUKS format. In this case, a device + mapper device is set up under the names + /dev/mapper/home and + /dev/mapper/srv. Note that this might create + conflicts if the same partition is listed in + /etc/crypttab with a different device mapper + device name. + + Mount and automount units for the EFI System Partition (ESP), + mounting it to /boot, are generated on EFI + systems where the boot loader communicates the used ESP to the operating + system. Since this generator creates an automount unit, the mount will + only be activated on-demand, when accessed. On systems where + /boot is an explicitly configured mount + (for example, listed in + fstab5) + or where the /boot mount point is non-empty, no + mount units are generated. + + When using this generator in conjunction with btrfs file + systems, make sure to set the correct default subvolumes on them, + using btrfs subvolume set-default. + + systemd-gpt-auto-generator implements + systemd.generator7. + + + + See Also + + systemd1, + systemd.mount5, + systemd.swap5, + systemd-fstab-generator8, + systemd-cryptsetup@.service8, + cryptsetup8, + fstab5, + btrfs8 + + + + diff --git a/src/systemd-initctl/systemd-initctl.service.xml b/src/systemd-initctl/systemd-initctl.service.xml new file mode 100644 index 0000000000..5c7f9a4a16 --- /dev/null +++ b/src/systemd-initctl/systemd-initctl.service.xml @@ -0,0 +1,76 @@ + + + + + + + + + systemd-initctl.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-initctl.service + 8 + + + + systemd-initctl.service + systemd-initctl.socket + systemd-initctl + /dev/initctl compatibility + + + + systemd-initctl.service + systemd-initctl.socket + /usr/lib/systemd/systemd-initctl + + + + Description + + systemd-initctl is a system service + that implements compatibility with the + /dev/initctl FIFO file system object, as + implemented by the SysV init system. + systemd-initctl is automatically activated on + request and terminates itself when it is unused. + + + + See Also + + systemd1 + + + + diff --git a/src/systemd-machine-id-setup/systemd-machine-id-commit.service.xml b/src/systemd-machine-id-setup/systemd-machine-id-commit.service.xml new file mode 100644 index 0000000000..39da1922cc --- /dev/null +++ b/src/systemd-machine-id-setup/systemd-machine-id-commit.service.xml @@ -0,0 +1,95 @@ + + + + + + + + systemd-machine-id-commit.service + systemd + + + + Developer + Didier + Roche + didrocks@ubuntu.com + + + + + + systemd-machine-id-commit.service + 8 + + + + systemd-machine-id-commit.service + Commit a transient machine ID to disk + + + + systemd-machine-id-commit.service + + + + Description + + systemd-machine-id-commit.service is an + early boot service responsible for committing transient + /etc/machine-id files to a writable disk file + system. See + machine-id5 + for more information about machine IDs. + + This service is started after + local-fs.target in case + /etc/machine-id is a mount point of its own + (usually from a memory file system such as + tmpfs) and /etc is writable. The service will + invoke systemd-machine-id-setup --commit, which + writes the current transient machine ID to disk and unmount the + /etc/machine-id file in a race-free manner to + ensure that file is always valid and accessible for other + processes. See + systemd-machine-id-setup1 + for details. + + The main use case of this service are systems where + /etc/machine-id is read-only and initially + not initialized. In this case, the system manager will generate a + transient machine ID file on a memory file system, and mount it + over /etc/machine-id, during the early boot + phase. This service is then invoked in a later boot phase, as soon + as /etc has been remounted writable and the + ID may thus be committed to disk to make it permanent. + + + + See Also + + systemd1, + systemd-machine-id-setup1, + machine-id5, + systemd-firstboot1 + + + + diff --git a/src/systemd-machine-id-setup/systemd-machine-id-setup.xml b/src/systemd-machine-id-setup/systemd-machine-id-setup.xml new file mode 100644 index 0000000000..bfcd74f436 --- /dev/null +++ b/src/systemd-machine-id-setup/systemd-machine-id-setup.xml @@ -0,0 +1,178 @@ + + + + + + + + + systemd-machine-id-setup + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + Developer + Didier + Roche + didrocks@ubuntu.com + + + + + + systemd-machine-id-setup + 1 + + + + systemd-machine-id-setup + Initialize the machine ID in /etc/machine-id + + + + + systemd-machine-id-setup + + + + + Description + + systemd-machine-id-setup may be used by + system installer tools to initialize the machine ID stored in + /etc/machine-id at install time, with a + provisioned or randomly generated ID. See + machine-id5 + for more information about this file. + + If the tool is invoked without the + switch, /etc/machine-id is initialized with a + valid, new machined ID if it is missing or empty. The new machine + ID will be acquired in the following fashion: + + + If a valid D-Bus machine ID is already + configured for the system, the D-Bus machine ID is copied and + used to initialize the machine ID in + /etc/machine-id. + + If run inside a KVM virtual machine and a UUID + is was configured (via the + option), this UUID is used to initialize the machine ID. The + caller must ensure that the UUID passed is sufficiently unique + and is different for every booted instance of the + VM. + + Similarly, if run inside a Linux container + environment and a UUID is configured for the container, this is + used to initialize the machine ID. For details, see the + documentation of the Container + Interface. + + Otherwise, a new ID is randomly + generated. + + + The switch may be used to commit a + transient machined ID to disk, making it persistent. For details, + see below. + + Use + systemd-firstboot1 + to initialize the machine ID on mounted (but not booted) system + images. + + + + + Options + + The following options are understood: + + + + + + Takes a directory path as argument. All paths + operated will be prefixed with the given alternate + root path, including the path for + /etc/machine-id itself. + + + + + Commit a transient machine ID to disk. This + command may be used to convert a transient machine ID into a + persistent one. A transient machine ID file is one that was + bind mounted from a memory file system (usually + tmpfs) to + /etc/machine-id during the early phase of + the boot process. This may happen because + /etc is initially read-only and was + missing a valid machine ID file at that point. + + This command will execute no operation if + /etc/machine-id is not mounted from a + memory file system, or if /etc is + read-only. The command will write the current transient + machine ID to disk and unmount the + /etc/machine-id mount point in a + race-free manner to ensure that this file is always valid and + accessible for other processes. + + This command is primarily used by the + systemd-machine-id-commit.service8 + early boot service. + + + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + See Also + + systemd1, + machine-id5, + systemd-machine-id-commit.service8, + dbus-uuidgen1, + systemd-firstboot1 + + + + diff --git a/src/systemd-nspawn/systemd-nspawn.xml b/src/systemd-nspawn/systemd-nspawn.xml new file mode 100644 index 0000000000..476cc2932f --- /dev/null +++ b/src/systemd-nspawn/systemd-nspawn.xml @@ -0,0 +1,1066 @@ + + + + + + + + + systemd-nspawn + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-nspawn + 1 + + + + systemd-nspawn + Spawn a namespace container for debugging, testing and building + + + + + systemd-nspawn + OPTIONS + COMMAND + ARGS + + + + systemd-nspawn + --boot + OPTIONS + ARGS + + + + + Description + + systemd-nspawn may be used to run a + command or OS in a light-weight namespace container. In many ways + it is similar to + chroot1, + but more powerful since it fully virtualizes the file system + hierarchy, as well as the process tree, the various IPC subsystems + and the host and domain name. + + systemd-nspawn limits access to various + kernel interfaces in the container to read-only, such as + /sys, /proc/sys or + /sys/fs/selinux. Network interfaces and the + system clock may not be changed from within the container. Device + nodes may not be created. The host system cannot be rebooted and + kernel modules may not be loaded from within the container. + + Note that even though these security precautions are taken + systemd-nspawn is not suitable for fully secure + container setups. Many of the security features may be + circumvented and are hence primarily useful to avoid accidental + changes to the host system from the container. + + In contrast to + chroot1 systemd-nspawn + may be used to boot full Linux-based operating systems in a + container. + + Use a tool like + dnf8, + debootstrap8, + or + pacman8 + to set up an OS directory tree suitable as file system hierarchy + for systemd-nspawn containers. + + Note that systemd-nspawn will mount file + systems private to the container to /dev, + /run and similar. These will not be visible + outside of the container, and their contents will be lost when the + container exits. + + Note that running two systemd-nspawn + containers from the same directory tree will not make processes in + them see each other. The PID namespace separation of the two + containers is complete and the containers will share very few + runtime objects except for the underlying file system. Use + machinectl1's + login command to request an additional login + prompt in a running container. + + systemd-nspawn implements the + Container + Interface specification. + + As a safety check systemd-nspawn will + verify the existence of /usr/lib/os-release + or /etc/os-release in the container tree + before starting the container (see + os-release5). + It might be necessary to add this file to the container tree + manually if the OS of the container is too old to contain this + file out-of-the-box. + + + + Options + + If option is specified, the arguments + are used as arguments for the init binary. Otherwise, + COMMAND specifies the program to launch + in the container, and the remaining arguments are used as + arguments for this program. If is not used and + no arguments are specified, a shell is launched in the + container. + + The following options are understood: + + + + + + + Directory to use as file system root for the + container. + + If neither , nor + is specified the directory is + determined by searching for a directory named the same as the + machine name specified with . See + machinectl1 + section "Files and Directories" for the precise search path. + + If neither , + , nor + are specified, the current directory will + be used. May not be specified together with + . + + + + + + Directory or btrfs + subvolume to use as template for the container's root + directory. If this is specified and the container's root + directory (as configured by ) + does not yet exist it is created as btrfs + subvolume and populated from this template tree. Ideally, the + specified template path refers to the root of a + btrfs subvolume, in which case a simple + copy-on-write snapshot is taken, and populating the root + directory is instant. If the specified template path does not + refer to the root of a btrfs subvolume (or + not even to a btrfs file system at all), + the tree is copied, which can be substantially more + time-consuming. Note that if this option is used the + container's root directory (in contrast to the template + directory!) must be located on a btrfs file + system, so that the btrfs subvolume may be + created. May not be specified together with + or + . + + Note that this switch leaves host name, machine ID and + all other settings that could identify the instance + unmodified. + + + + + + + If specified, the container is run with a + temporary btrfs snapshot of its root + directory (as configured with ), + that is removed immediately when the container terminates. + This option is only supported if the root file system is + btrfs. May not be specified together with + or + . + Note that this switch leaves host name, machine ID and + all other settings that could identify the instance + unmodified. + + + + + + + Disk image to mount the root directory for the + container from. Takes a path to a regular file or to a block + device node. The file or block device must contain + either: + + + An MBR partition table with a single + partition of type 0x83 that is marked + bootable. + + A GUID partition table (GPT) with a single + partition of type + 0fc63daf-8483-4772-8e79-3d69d8477de4. + + A GUID partition table (GPT) with a marked + root partition which is mounted as the root directory of the + container. Optionally, GPT images may contain a home and/or + a server data partition which are mounted to the appropriate + places in the container. All these partitions must be + identified by the partition types defined by the Discoverable + Partitions Specification. + + + Any other partitions, such as foreign partitions, swap + partitions or EFI system partitions are not mounted. May not + be specified together with , + or + . + + + + + + + Invoke the shell or specified program as process ID (PID) 2 instead of PID 1 (init). By + default, if neither this option nor is used, the selected binary is run as process with + PID 1, a mode only suitable for programs that are aware of the special semantics that the process with PID 1 + has on UNIX. For example, it needs to reap all processes reparented to it, and should implement + sysvinit compatible signal handling (specifically: it needs to reboot on SIGINT, reexecute + on SIGTERM, reload configuration on SIGHUP, and so on). With a minimal stub init + process is run as PID 1 and the selected binary is executed as PID 2 (and hence does not need to implement any + special semantics). The stub init process will reap processes as necessary and react appropriately to + signals. It is recommended to use this mode to invoke arbitrary commands in containers, unless they have been + modified to run correctly as PID 1. Or in other words: this switch should be used for pretty much all commands, + except when the command refers to an init or shell implementation, as these are generally capable of running + correctly as PID 1. This option may not be combined with or + . + + + + + + + + Automatically search for an init binary and invoke it as PID 1, instead of a shell or a user + supplied program. If this option is used, arguments specified on the command line are used as arguments for the + init binary. This option may not be combined with or + . + + The following table explains the different modes of invocation and relationship to + (see above): + + + Invocation Mode + + + + + + Switch + Explanation + + + + + Neither nor specified + The passed parameters are interpreted as the command line, which is executed as PID 1 in the container. + + + + specified + The passed parameters are interpreted as the command line, which is executed as PID 2 in the container. A stub init process is run as PID 1. + + + + specified + An init binary as automatically searched and run as PID 1 in the container. The passed parameters are used as invocation parameters for this process. + + + + +
+ + + + + + + Change to the specified working directory before invoking the process in the container. Expects + an absolute path in the container's file system namespace. + + + + + + + After transitioning into the container, change + to the specified user-defined in the container's user + database. Like all other systemd-nspawn features, this is not + a security feature and provides protection against accidental + destructive operations only. + + + + + + + Sets the machine name for this container. This + name may be used to identify this container during its runtime + (for example in tools like + machinectl1 + and similar), and is used to initialize the container's + hostname (which the container can choose to override, + however). If not specified, the last component of the root + directory path of the container is used, possibly suffixed + with a random identifier in case + mode is selected. If the root directory selected is the host's + root directory the host's hostname is used as default + instead. + + + + + + Set the specified UUID for the container. The + init system will initialize + /etc/machine-id from this if this file is + not set yet. Note that this option takes effect only if + /etc/machine-id in the container is + unpopulated. + + + + + + Make the container part of the specified + slice, instead of the default + machine.slice. This is only applies if + the machine is run in its own scope unit, i.e. if + is not used. + + + + + + + Set a unit property on the scope unit to + register for the machine. This only applies if the machine is + run in its own scope unit, i.e. if + is not used. Takes unit property + assignments in the same format as systemctl + set-property. This is useful to set memory limits + and similar for machines. + + + + + + + Controls user namespacing. If enabled, the container will run with its own private set of UNIX + user and group ids (UIDs and GIDs). This involves mapping the private UIDs/GIDs used in the container (starting + with the container's root user 0 and up) to a range of UIDs/GIDs on the host that are not used for other + purposes (usually in the range beyond the host's UID/GID 65536). The parameter may be specified as follows: + + + The value no turns off user namespacing. This is the default. + + The value yes (or the omission of a parameter) turns on user + namespacing. The UID/GID range to use is determined automatically from the file ownership of the root + directory of the container's directory tree. To use this option, make sure to prepare the directory tree in + advance, and ensure that all files and directories in it are owned by UIDs/GIDs in the range you'd like to + use. Also, make sure that used file ACLs exclusively reference UIDs/GIDs in the appropriate range. If this + mode is used the number of UIDs/GIDs assigned to the container for use is 65536, and the UID/GID of the + root directory must be a multiple of 65536. + + The value "pick" turns on user namespacing. In this case the UID/GID range is automatically + chosen. As first step, the file owner of the root directory of the container's directory tree is read, and it + is checked that it is currently not used by the system otherwise (in particular, that no other container is + using it). If this check is successful, the UID/GID range determined this way is used, similar to the + behaviour if "yes" is specified. If the check is not successful (and thus the UID/GID range indicated in the + root directory's file owner is already used elsewhere) a new – currently unused – UID/GID range of 65536 + UIDs/GIDs is randomly chosen between the host UID/GIDs of 524288 and 1878982656, always starting at a + multiple of 65536. This setting implies (see below), which has the + effect that the files and directories in the container's directory tree will be owned by the appropriate + users of the range picked. Using this option makes user namespace behaviour fully automatic. Note that the + first invocation of a previously unused container image might result in picking a new UID/GID range for it, + and thus in the (possibly expensive) file ownership adjustment operation. However, subsequent invocations of + the container will be cheap (unless of course the picked UID/GID range is assigned to a different use by + then). + + Finally if one or two colon-separated numeric parameters are specified, user namespacing is + turned on, too. The first parameter specifies the first host UID/GID to assign to the container, the second + parameter specifies the number of host UIDs/GIDs to assign to the container. If the second parameter is + omitted, 65536 UIDs/GIDs are assigned. + + + It is recommended to assign at least 65536 UIDs/GIDs to each container, so that the usable UID/GID range in the + container covers 16 bit. For best security, do not assign overlapping UID/GID ranges to multiple containers. It is + hence a good idea to use the upper 16 bit of the host 32-bit UIDs/GIDs as container identifier, while the lower 16 + bit encode the container UID/GID used. This is in fact the behaviour enforced by the + option. + + When user namespaces are used, the GID range assigned to each container is always chosen identical to the + UID range. + + In most cases, using is the recommended option as it enhances + container security massively and operates fully automatically in most cases. + + Note that the picked UID/GID range is not written to /etc/passwd or + /etc/group. In fact, the allocation of the range is not stored persistently anywhere, + except in the file ownership of the files and directories of the container. + + + + + + If the kernel supports the user namespaces feature, equivalent to + , otherwise equivalent to + . + + + + + + If specified, all files and directories in the container's directory tree will adjusted so that + they are owned to the appropriate UIDs/GIDs selected for the container (see above). This operation is + potentially expensive, as it involves descending and iterating through the full directory tree of the + container. Besides actual file ownership, file ACLs are adjusted as well. + + This option is implied if is used. This option has no effect if + user namespacing is not used. + + + + + + Disconnect networking of the container from + the host. This makes all network interfaces unavailable in the + container, with the exception of the loopback device and those + specified with and + configured with . If this + option is specified, the CAP_NET_ADMIN capability will be + added to the set of capabilities the container retains. The + latter may be disabled by using + . + + + + + + Assign the specified network interface to the + container. This will remove the specified interface from the + calling namespace and place it in the container. When the + container terminates, it is moved back to the host namespace. + Note that implies + . This option may be used + more than once to add multiple network interfaces to the + container. + + + + + + Create a macvlan interface + of the specified Ethernet network interface and add it to the + container. A macvlan interface is a virtual + interface that adds a second MAC address to an existing + physical Ethernet link. The interface in the container will be + named after the interface on the host, prefixed with + mv-. Note that + implies + . This option may be used + more than once to add multiple network interfaces to the + container. + + + + + + Create an ipvlan interface + of the specified Ethernet network interface and add it to the + container. An ipvlan interface is a virtual + interface, similar to a macvlan interface, + which uses the same MAC address as the underlying interface. + The interface in the container will be named after the + interface on the host, prefixed with iv-. + Note that implies + . This option may be used + more than once to add multiple network interfaces to the + container. + + + + + + + Create a virtual Ethernet link (veth) between host and container. The host + side of the Ethernet link will be available as a network interface named after the container's name (as + specified with ), prefixed with ve-. The container side of the + Ethernet link will be named host0. The option implies + . + + Note that + systemd-networkd.service8 + includes by default a network file /usr/lib/systemd/network/80-container-ve.network + matching the host-side interfaces created this way, which contains settings to enable automatic address + provisioning on the created virtual link via DHCP, as well as automatic IP routing onto the host's external + network interfaces. It also contains /usr/lib/systemd/network/80-container-host0.network + matching the container-side interface created this way, containing settings to enable client side address + assignment via DHCP. In case systemd-networkd is running on both the host and inside the + container, automatic IP communication from the container to the host is thus available, with further + connectivity to the external network. + + + + + + + Adds an additional virtual Ethernet link + between host and container. Takes a colon-separated pair of + host interface name and container interface name. The latter + may be omitted in which case the container and host sides will + be assigned the same name. This switch is independent of + , and — in contrast — may be + used multiple times, and allows configuration of the network + interface names. Note that + has no effect on interfaces created with + . + + + + + + Adds the host side of the Ethernet link created with to the + specified Ethernet bridge interface. Expects a valid network interface name of a bridge device as + argument. Note that implies . If this option + is used, the host side of the Ethernet link will use the vb- prefix instead of + ve-. + + + + + + Creates a virtual Ethernet link (veth) to the container and adds it to an + automatically managed Ethernet bridge interface. The bridge interface is named after the passed argument, + prefixed with vz-. The bridge interface is automatically created when the first container + configured for its name is started, and is automatically removed when the last container configured for its + name exits. Hence, each bridge interface configured this way exists only as long as there's at least one + container referencing it running. This option is very similar to , besides + this automatic creation/removal of the bridge device. + + This setting makes it easy to place multiple related containers on a common, virtual Ethernet-based + broadcast domain, here called a "zone". Each container may only be part of one zone, but each zone may contain + any number of containers. Each zone is referenced by its name. Names may be chosen freely (as long as they form + valid network interface names when prefixed with vz-), and it is sufficient to pass the same + name to the switch of the various concurrently running containers to join + them in one zone. + + Note that + systemd-networkd.service8 + includes by default a network file /usr/lib/systemd/network/80-container-vz.network + matching the bridge interfaces created this way, which contains settings to enable automatic address + provisioning on the created virtual network via DHCP, as well as automatic IP routing onto the host's external + network interfaces. Using is hence in most cases fully automatic and + sufficient to connect multiple local containers in a joined broadcast domain to the host, with further + connectivity to the external network. + + + + + + + + If private networking is enabled, maps an IP + port on the host onto an IP port on the container. Takes a + protocol specifier (either tcp or + udp), separated by a colon from a host port + number in the range 1 to 65535, separated by a colon from a + container port number in the range from 1 to 65535. The + protocol specifier and its separating colon may be omitted, in + which case tcp is assumed. The container + port number and its colon may be omitted, in which case the + same port as the host port is implied. This option is only + supported if private networking is used, such as with + , + . + + + + + + + Sets the SELinux security context to be used + to label processes in the container. + + + + + + + + Sets the SELinux security context to be used + to label files in the virtual API file systems in the + container. + + + + + + + List one or more additional capabilities to + grant the container. Takes a comma-separated list of + capability names, see + capabilities7 + for more information. Note that the following capabilities + will be granted in any way: CAP_CHOWN, CAP_DAC_OVERRIDE, + CAP_DAC_READ_SEARCH, CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER, + CAP_KILL, CAP_LEASE, CAP_LINUX_IMMUTABLE, + CAP_NET_BIND_SERVICE, CAP_NET_BROADCAST, CAP_NET_RAW, + CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP, CAP_SETUID, + CAP_SYS_ADMIN, CAP_SYS_CHROOT, CAP_SYS_NICE, CAP_SYS_PTRACE, + CAP_SYS_TTY_CONFIG, CAP_SYS_RESOURCE, CAP_SYS_BOOT, + CAP_AUDIT_WRITE, CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN is + retained if is specified. + If the special value all is passed, all + capabilities are retained. + + + + + + Specify one or more additional capabilities to + drop for the container. This allows running the container with + fewer capabilities than the default (see + above). + + + + + + 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 + is used (on systemd-compatible init systems SIGRTMIN+3 + triggers an orderly shutdown). For a list of valid signals, see + signal7. + + + + + + Control whether the container's journal shall + be made visible to the host system. If enabled, allows viewing + the container's journal files from the host (but not vice + versa). Takes one of no, + host, try-host, + guest, try-guest, + auto. If no, the journal + is not linked. If host, the journal files + are stored on the host file system (beneath + /var/log/journal/machine-id) + and the subdirectory is bind-mounted into the container at the + same location. If guest, the journal files + are stored on the guest file system (beneath + /var/log/journal/machine-id) + and the subdirectory is symlinked into the host at the same + location. try-host and + try-guest do the same but do not fail if + the host does not have persistent journalling enabled. If + auto (the default), and the right + subdirectory of /var/log/journal exists, + it will be bind mounted into the container. If the + subdirectory does not exist, no linking is performed. + Effectively, booting a container once with + guest or host will link + the journal persistently if further on the default of + auto is used. + + + + + + Equivalent to + . + + + + + + Mount the root file system read-only for the + container. + + + + + + + Bind mount a file or directory from the host + into the container. Takes one of: a path argument — in which + case the specified path will be mounted from the host to the + same path in the container —, or a colon-separated pair of + paths — in which case the first specified path is the source + in the host, and the second path is the destination in the + container —, or a colon-separated triple of source path, + destination path and mount options. Mount options are + comma-separated and currently, only "rbind" and "norbind" + are allowed. Defaults to "rbind". Backslash escapes are interpreted, so + \: may be used to embed colons in either path. + This option may be specified multiple times for + creating multiple independent bind mount points. The + option creates read-only bind + mounts. + + + + + + Mount a tmpfs file system into the container. + Takes a single absolute path argument that specifies where to + mount the tmpfs instance to (in which case the directory + access mode will be chosen as 0755, owned by root/root), or + optionally a colon-separated pair of path and mount option + string that is used for mounting (in which case the kernel + default for access mode and owner will be chosen, unless + otherwise specified). This option is particularly useful for + mounting directories such as /var as + tmpfs, to allow state-less systems, in particular when + combined with . + Backslash escapes are interpreted in the path, so + \: may be used to embed colons in the path. + + + + + + + + Combine multiple directory trees into one + overlay file system and mount it into the container. Takes a + list of colon-separated paths to the directory trees to + combine and the destination mount point. + + Backslash escapes are interpreted in the paths, so + \: may be used to embed colons in the paths. + + + If three or more paths are specified, then the last + specified path is the destination mount point in the + container, all paths specified before refer to directory trees + on the host and are combined in the specified order into one + overlay file system. The left-most path is hence the lowest + directory tree, the second-to-last path the highest directory + tree in the stacking order. If + is used instead of , a read-only + overlay file system is created. If a writable overlay file + system is created, all changes made to it are written to the + highest directory tree in the stacking order, i.e. the + second-to-last specified. + + If only two paths are specified, then the second + specified path is used both as the top-level directory tree in + the stacking order as seen from the host, as well as the mount + point for the overlay file system in the container. At least + two paths have to be specified. + + For details about overlay file systems, see overlayfs.txt. Note + that the semantics of overlay file systems are substantially + different from normal file systems, in particular regarding + reported device and inode information. Device and inode + information may change for a file while it is being written + to, and processes might see out-of-date versions of files at + times. Note that this switch automatically derives the + workdir= mount option for the overlay file + system from the top-level directory tree, making it a sibling + of it. It is hence essential that the top-level directory tree + is not a mount point itself (since the working directory must + be on the same file system as the top-most directory + tree). Also note that the lowerdir= mount + option receives the paths to stack in the opposite order of + this switch. + + + + + + + Specifies an environment variable assignment + to pass to the init process in the container, in the format + NAME=VALUE. This may be used to override + the default variables or to set additional variables. This + parameter may be used more than once. + + + + + + Allows the container to share certain system + facilities with the host. More specifically, this turns off + PID namespacing, UTS namespacing and IPC namespacing, and thus + allows the guest to see and interact more easily with + processes outside of the container. Note that using this + option makes it impossible to start up a full Operating System + in the container, as an init system cannot operate in this + mode. It is only useful to run specific programs or + applications this way, without involving an init system in the + container. This option implies . + This option may not be combined with + . + + + + + + Controls whether the container is registered + with + systemd-machined8. + Takes a boolean argument, which defaults to yes. + This option should be enabled when the container runs a full + Operating System (more specifically: an init system), and is + useful to ensure that the container is accessible via + machinectl1 + and shown by tools such as + ps1. + If the container does not run an init system, it is + recommended to set this option to no. Note + that implies + . + + + + + + Instead of creating a transient scope unit to + run the container in, simply register the service or scope + unit systemd-nspawn has been invoked in + with + systemd-machined8. + This has no effect if is used. + This switch should be used if + systemd-nspawn is invoked from within a + service unit, and the service unit's sole purpose is to run a + single systemd-nspawn container. This + option is not available if run from a user + session. + + + + + + Control the architecture ("personality") + reported by + uname2 + in the container. Currently, only x86 and + x86-64 are supported. This is useful when + running a 32-bit container on a 64-bit host. If this setting + is not used, the personality reported in the container is the + same as the one reported on the host. + + + + + + + Turns off any status output by the tool + itself. When this switch is used, the only output from nspawn + will be the console output of the container OS + itself. + + + + + MODE + + Boots the container in volatile mode. When no + mode parameter is passed or when mode is specified as + , full volatile mode is enabled. This + means the root directory is mounted as a mostly unpopulated + tmpfs instance, and + /usr from the OS tree is mounted into it + in read-only mode (the system thus starts up with read-only OS + resources, but pristine state and configuration, any changes + to the either are lost on shutdown). When the mode parameter + is specified as , the OS tree is + mounted read-only, but /var is mounted as + a tmpfs instance into it (the system thus + starts up with read-only OS resources and configuration, but + pristine state, and any changes to the latter are lost on + shutdown). When the mode parameter is specified as + (the default), the whole OS tree is made + available writable. + + Note that setting this to or + will only work correctly with + operating systems in the container that can boot up with only + /usr mounted, and are able to populate + /var automatically, as + needed. + + + + MODE + + Controls whether + systemd-nspawn shall search for and use + additional per-container settings from + .nspawn files. Takes a boolean or the + special values or + . + + If enabled (the default), a settings file named after the + machine (as specified with the + setting, or derived from the directory or image file name) + with the suffix .nspawn is searched in + /etc/systemd/nspawn/ and + /run/systemd/nspawn/. If it is found + there, its settings are read and used. If it is not found + there, it is subsequently searched in the same directory as the + image file or in the immediate parent of the root directory of + the container. In this case, if the file is found, its settings + will be also read and used, but potentially unsafe settings + are ignored. Note that in both these cases, settings on the + command line take precedence over the corresponding settings + from loaded .nspawn files, if both are + specified. Unsafe settings are considered all settings that + elevate the container's privileges or grant access to + additional resources such as files or directories of the + host. For details about the format and contents of + .nspawn files, consult + systemd.nspawn5. + + If this option is set to , the + file is searched, read and used the same way, however, the order of + precedence is reversed: settings read from the + .nspawn file will take precedence over + the corresponding command line options, if both are + specified. + + If this option is set to , the + file is searched, read and used the same way, but regardless + of being found in /etc/systemd/nspawn/, + /run/systemd/nspawn/ or next to the image + file or container root directory, all settings will take + effect, however, command line arguments still take precedence + over corresponding settings. + + If disabled, no .nspawn file is read + and no settings except the ones on the command line are in + effect. + + + + + + + + + + Examples + + + Build and boot a minimal BLAG distribution in a container + + # dnf -y --releasever=210k --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=blag --enablerepo=updates install systemd passwd dnf blag-release vim-minimal +# systemd-nspawn -bD /srv/mycontainer + + This installs a minimal BLAG distribution into the + directory /srv/mycontainer/ + and then boots an OS in a namespace container in it. + + + + Spawn a shell in a container of a minimal gNewSense unstable distribution + + # debootstrap --arch=amd64 unstable ~/gnewsense-tree/ +# systemd-nspawn -D ~/gnewsense-tree/ + + This installs a minimal gNewSense unstable distribution into + the directory ~/gnewsense-tree/ and then + spawns a shell in a namespace container in it. + + + + Boot a minimal Parabola GNU/Linux-libre distribution in a container + + # pacstrap -c -d ~/parabola-tree/ base +# systemd-nspawn -bD ~/parabola-tree/ + + This installs a minimal Parabola GNU/Linux-libre distribution into the + directory ~/parabola-tree/ and then boots an OS + in a namespace container in it. + + + + Boot into an ephemeral <literal>btrfs</literal> snapshot of the host system + + # systemd-nspawn -D / -xb + + This runs a copy of the host system in a + btrfs snapshot which is removed immediately + when the container exits. All file system changes made during + runtime will be lost on shutdown, hence. + + + + Run a container with SELinux sandbox security contexts + + # chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container +# systemd-nspawn -L system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -Z system_u:system_r:svirt_lxc_net_t:s0:c0,c1 -D /srv/container /bin/sh + + + + + Exit status + + The exit code of the program executed in the container is + returned. + + + + See Also + + systemd1, + systemd.nspawn5, + chroot1, + dnf8, + debootstrap8, + pacman8, + systemd.slice5, + machinectl1, + btrfs8 + + + + diff --git a/src/systemd-remount-fs/systemd-remount-fs.service.xml b/src/systemd-remount-fs/systemd-remount-fs.service.xml new file mode 100644 index 0000000000..176f2b2d20 --- /dev/null +++ b/src/systemd-remount-fs/systemd-remount-fs.service.xml @@ -0,0 +1,88 @@ + + + + + + + + systemd-remount-fs.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-remount-fs.service + 8 + + + + systemd-remount-fs.service + systemd-remount-fs + Remount root and kernel file systems + + + + systemd-remount-fs.service + /usr/lib/systemd/systemd-remount-fs + + + + Description + + systemd-remount-fs.service is an + early boot service that applies mount options listed in + fstab5 + to the root file system, the /usr file system, + and the kernel API file systems. This is required so that the + mount options of these file systems — which are pre-mounted by + the kernel, the initial RAM disk, container environments or system + manager code — are updated to those listed in + /etc/fstab. This service ignores normal file + systems and only changes the root file system (i.e. + /), /usr and the virtual + kernel API file systems such as /proc, + /sys or /dev. This + service executes no operation if /etc/fstab + does not exist or lists no entries for the mentioned file + systems. + + For a longer discussion of kernel API file systems see + API + File Systems. + + + + See Also + + systemd1, + fstab5, + mount8 + + + + diff --git a/src/systemd-socket-proxyd/systemd-socket-proxyd.xml b/src/systemd-socket-proxyd/systemd-socket-proxyd.xml new file mode 100644 index 0000000000..ae4217b910 --- /dev/null +++ b/src/systemd-socket-proxyd/systemd-socket-proxyd.xml @@ -0,0 +1,190 @@ + + + + + + + + systemd-socket-proxyd + systemd + + + Developer + David + Strauss + david@davidstrauss.net + + + + + systemd-socket-proxyd + 8 + + + systemd-socket-proxyd + Bidirectionally proxy local sockets to another (possibly remote) socket. + + + + systemd-socket-proxyd + OPTIONS + HOST:PORT + + + systemd-socket-proxyd + OPTIONS + UNIX-DOMAIN-SOCKET-PATH + + + + + Description + + systemd-socket-proxyd is a generic + socket-activated network socket forwarder proxy daemon for IPv4, + IPv6 and UNIX stream sockets. It may be used to bi-directionally + forward traffic from a local listening socket to a local or remote + destination socket. + + One use of this tool is to provide socket activation support + for services that do not natively support socket activation. On + behalf of the service to activate, the proxy inherits the socket + from systemd, accepts each client connection, opens a connection + to a configured server for each client, and then bidirectionally + forwards data between the two. + This utility's behavior is similar to + socat1. + The main differences for systemd-socket-proxyd + are support for socket activation with + Accept=false and an event-driven + design that scales better with the number of + connections. + + + Options + The following options are understood: + + + + + + + Exit status + On success, 0 is returned, a non-zero failure + code otherwise. + + + Examples + + Simple Example + Use two services with a dependency and no namespace + isolation. + + proxy-to-nginx.socket + + + + proxy-to-nginx.service + + + + nginx.conf + + + + + + Enabling the proxy + + + + + Namespace Example + Similar as above, but runs the socket proxy and the main + service in the same private namespace, assuming that + nginx.service has + PrivateTmp= and + PrivateNetwork= set, too. + + proxy-to-nginx.socket + + + + proxy-to-nginx.service + + + + nginx.conf + + + + Enabling the proxy + + + + + + See Also + + systemd1, + systemd.socket5, + systemd.service5, + systemctl1, + socat1, + nginx1, + curl1 + + + diff --git a/src/systemd-system-update-generator/systemd-system-update-generator.xml b/src/systemd-system-update-generator/systemd-system-update-generator.xml new file mode 100644 index 0000000000..e7fc95c742 --- /dev/null +++ b/src/systemd-system-update-generator/systemd-system-update-generator.xml @@ -0,0 +1,76 @@ + + + + + + + + systemd-system-update-generator + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-system-update-generator + 8 + + + + systemd-system-update-generator + Generator for redirecting boot to offline update mode + + + + /usr/lib/systemd/system-generators/systemd-system-update-generator + + + + Description + + systemd-system-update-generator is a + generator that automatically redirects the boot process to + system-update.target if + /system-update exists. This is required to + implement the logic explained in the System + Updates Specification. + + + systemd-system-update-generator implements + systemd.generator7. + + + + See Also + + systemd1, + systemd.special7 + + + + diff --git a/src/systemd-timesyncd/systemd-timesyncd.service.xml b/src/systemd-timesyncd/systemd-timesyncd.service.xml new file mode 100644 index 0000000000..6ec384313b --- /dev/null +++ b/src/systemd-timesyncd/systemd-timesyncd.service.xml @@ -0,0 +1,108 @@ + + + + + + + + + systemd-timesyncd.service + systemd + + + + Developer + Kay + Sievers + kay@vrfy.org + + + + + + systemd-timesyncd.service + 8 + + + + systemd-timesyncd.service + systemd-timesyncd + Network Time Synchronization + + + + systemd-timesyncd.service + /usr/lib/systemd/systemd-timesyncd + + + + Description + + systemd-timesyncd is a system service + that may be used to synchronize the local system clock with a + remote Network Time Protocol server. It also saves the local time + to disk every time the clock has been synchronized and uses this + to possibly advance the system realtime clock on subsequent + reboots to ensure it monotonically advances even if the system + lacks a battery-buffered RTC chip. + + The NTP servers contacted are determined from the global + settings in + timesyncd.conf5, + the per-link static settings in .network + files, and the per-link dynamic settings received over DHCP. See + systemd.network5 + for more details. + + timedatectl1's + set-ntp command may be used to enable and + start, or disable and stop this service. + + + + Files + + + + /var/lib/systemd/clock + + + This file contains the timestamp of the last successful + synchronization. + + + + + + + See Also + + systemd1, + timesyncd.conf5, + systemd.network5, + systemd-networkd.service8, + timedatectl1, + localtime5, + hwclock8 + + + + diff --git a/src/systemd-timesyncd/timesyncd.conf.xml b/src/systemd-timesyncd/timesyncd.conf.xml new file mode 100644 index 0000000000..8c86fd0074 --- /dev/null +++ b/src/systemd-timesyncd/timesyncd.conf.xml @@ -0,0 +1,112 @@ + + + + + + + + timesyncd.conf + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + timesyncd.conf + 5 + + + + timesyncd.conf + timesyncd.conf.d + Network Time Synchronization configuration files + + + + /etc/systemd/timesyncd.conf + /etc/systemd/timesyncd.conf.d/*.conf + /run/systemd/timesyncd.conf.d/*.conf + /usr/lib/systemd/timesyncd.conf.d/*.conf + + + + Description + + These configuration files control NTP network time + synchronization. + + + + + + + Options + + The following settings are configured in the [Time] section: + + + + + NTP= + A space-separated list of NTP server host + names or IP addresses. During runtime this list is combined + with any per-interface NTP servers acquired from + systemd-networkd.service8. + systemd-timesyncd will contact all configured system or + per-interface servers in turn until one is found that + responds. This setting defaults to an empty + list. + + + + FallbackNTP= + A space-separated list of NTP server host + names or IP addresses to be used as the fallback NTP servers. + Any per-interface NTP servers obtained from + systemd-networkd.service8 + take precedence over this setting, as do any servers set via + NTP= above. This setting is hence only used + if no other NTP server information is known. If this option is + not given, a compiled-in list of NTP servers is used + instead. + + + + + + + See Also + + systemd1, + systemd-timesyncd.service8, + systemd-networkd.service8 + + + + diff --git a/src/systemd-tty-ask-password-agent/systemd-ask-password-console.service.xml b/src/systemd-tty-ask-password-agent/systemd-ask-password-console.service.xml new file mode 100644 index 0000000000..479e5f2e5b --- /dev/null +++ b/src/systemd-tty-ask-password-agent/systemd-ask-password-console.service.xml @@ -0,0 +1,93 @@ + + + + + + + + systemd-ask-password-console.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-ask-password-console.service + 8 + + + + systemd-ask-password-console.service + systemd-ask-password-console.path + systemd-ask-password-wall.service + systemd-ask-password-wall.path + Query the user for system passwords on the + console and via wall + + + + systemd-ask-password-console.service + systemd-ask-password-console.path + systemd-ask-password-wall.service + systemd-ask-password-wall.path + + + + Description + + systemd-ask-password-console.service is + a system service that queries the user for system passwords (such + as hard disk encryption keys and SSL certificate passphrases) on + the console. It is intended to be used during boot to ensure + proper handling of passwords necessary for boot. + systemd-ask-password-wall.service is a system + service that informs all logged in users for system passwords via + wall1. + It is intended to be used after boot to ensure that users are + properly notified. + + See the + developer documentation for more information about the + system password logic. + + Note that these services invoke + systemd-tty-ask-password-agent1 + with either the --watch --console or + --watch --wall command line parameters. + + + + See Also + + systemd1, + systemd-tty-ask-password-agent1, + wall1 + + + + diff --git a/src/systemd-tty-ask-password-agent/systemd-tty-ask-password-agent.xml b/src/systemd-tty-ask-password-agent/systemd-tty-ask-password-agent.xml new file mode 100644 index 0000000000..2876fab644 --- /dev/null +++ b/src/systemd-tty-ask-password-agent/systemd-tty-ask-password-agent.xml @@ -0,0 +1,149 @@ + + + + + + + + + systemd-tty-ask-password-agent + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-tty-ask-password-agent + 1 + + + + systemd-tty-ask-password-agent + List or process pending systemd password requests + + + + + systemd-tty-ask-password-agent OPTIONS VARIABLE=VALUE + + + + + Description + + systemd-tty-ask-password-agent is a + password agent that handles password requests of the system, for + example for hard disk encryption passwords or SSL certificate + passwords that need to be queried at boot-time or during + runtime. + + systemd-tty-ask-password-agent implements + the Password + Agents Specification. + + + + + Options + + The following options are understood: + + + + + + Lists all currently pending system password requests. + + + + + + Process all currently pending system password + requests by querying the user on the calling + TTY. + + + + + + Continuously process password + requests. + + + + + + Forward password requests to + wall1 + instead of querying the user on the calling + TTY. + + + + + + Ask question with + plymouth8 + instead of querying the user on the calling + TTY. + + + + + + Ask question on + /dev/console instead of querying the user + on the calling TTY. + + + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure + code otherwise. + + + + See Also + + systemd1, + systemctl1, + systemd-ask-password-console.service8, + wall1, + plymouth8 + + + + -- cgit v1.2.3-54-g00ecf