From 5e1f646c67c954fe7d55a747e3ffdd07e20cb46a Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Thu, 15 Sep 2016 01:52:25 -0400 Subject: ./tools/notsd-move --- src/manpages/daemon.xml | 763 +++++++++++++++++++++++++++++++++++++ src/manpages/file-hierarchy.xml | 815 ++++++++++++++++++++++++++++++++++++++++ src/manpages/hostname.xml | 98 +++++ src/manpages/locale.conf.xml | 152 ++++++++ src/manpages/localtime.xml | 103 +++++ src/manpages/machine-id.xml | 146 +++++++ src/manpages/machine-info.xml | 185 +++++++++ src/manpages/os-release.xml | 378 +++++++++++++++++++ 8 files changed, 2640 insertions(+) create mode 100644 src/manpages/daemon.xml create mode 100644 src/manpages/file-hierarchy.xml create mode 100644 src/manpages/hostname.xml create mode 100644 src/manpages/locale.conf.xml create mode 100644 src/manpages/localtime.xml create mode 100644 src/manpages/machine-id.xml create mode 100644 src/manpages/machine-info.xml create mode 100644 src/manpages/os-release.xml (limited to 'src/manpages') diff --git a/src/manpages/daemon.xml b/src/manpages/daemon.xml new file mode 100644 index 0000000000..a649749683 --- /dev/null +++ b/src/manpages/daemon.xml @@ -0,0 +1,763 @@ + + + + + + + + + daemon + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + daemon + 7 + + + + daemon + Writing and packaging system daemons + + + + Description + + A daemon is a service process that runs in the background + and supervises the system or provides functionality to other + processes. Traditionally, daemons are implemented following a + scheme originating in SysV Unix. Modern daemons should follow a + simpler yet more powerful scheme (here called "new-style" + daemons), as implemented by + systemd1. + This manual page covers both schemes, and in particular includes + recommendations for daemons that shall be included in the systemd + init system. + + + SysV Daemons + + When a traditional SysV daemon starts, it should execute + the following steps as part of the initialization. Note that + these steps are unnecessary for new-style daemons (see below), + and should only be implemented if compatibility with SysV is + essential. + + + Close all open file descriptors except + standard input, output, and error (i.e. the first three file + descriptors 0, 1, 2). This ensures that no accidentally passed + file descriptor stays around in the daemon process. On Linux, + this is best implemented by iterating through + /proc/self/fd, with a fallback of + iterating from file descriptor 3 to the value returned by + getrlimit() for + RLIMIT_NOFILE. + + Reset all signal handlers to their default. + This is best done by iterating through the available signals + up to the limit of _NSIG and resetting + them to SIG_DFL. + + Reset the signal mask + using + sigprocmask(). + + Sanitize the environment block, removing or + resetting environment variables that might negatively impact + daemon runtime. + + Call fork(), to create a + background process. + + In the child, call + setsid() to detach from any terminal and + create an independent session. + + In the child, call fork() + again, to ensure that the daemon can never re-acquire a + terminal again. + + Call exit() in the first + child, so that only the second child (the actual daemon + process) stays around. This ensures that the daemon process is + re-parented to init/PID 1, as all daemons should + be. + + In the daemon process, connect + /dev/null to standard input, output, and + error. + + In the daemon process, reset the umask to 0, + so that the file modes passed to open(), + mkdir() and suchlike directly control the + access mode of the created files and + directories. + + In the daemon process, change the current + directory to the root directory (/), in order to avoid that + the daemon involuntarily blocks mount points from being + unmounted. + + In the daemon process, write the daemon PID + (as returned by getpid()) to a PID file, + for example /run/foobar.pid (for a + hypothetical daemon "foobar") to ensure that the daemon cannot + be started more than once. This must be implemented in + race-free fashion so that the PID file is only updated when it + is verified at the same time that the PID previously stored in + the PID file no longer exists or belongs to a foreign + process. + + In the daemon process, drop privileges, if + possible and applicable. + + From the daemon process, notify the original + process started that initialization is complete. This can be + implemented via an unnamed pipe or similar communication + channel that is created before the first + fork() and hence available in both the + original and the daemon process. + + Call exit() in the + original process. The process that invoked the daemon must be + able to rely on that this exit() happens + after initialization is complete and all external + communication channels are established and + accessible. + + + The BSD daemon() function should not + be used, as it implements only a subset of these steps. + + A daemon that needs to provide compatibility with SysV + systems should implement the scheme pointed out above. However, + it is recommended to make this behavior optional and + configurable via a command line argument to ease debugging as + well as to simplify integration into systems using + systemd. + + + + New-Style Daemons + + Modern services for GNU/Linux should be implemented as + new-style daemons. This makes it easier to supervise and control + them at runtime and simplifies their implementation. + + For developing a new-style daemon, none of the + initialization steps recommended for SysV daemons need to be + implemented. New-style init systems such as systemd make all of + them redundant. Moreover, since some of these steps interfere + with process monitoring, file descriptor passing and other + functionality of the init system, it is recommended not to + execute them when run as new-style service. + + Note that new-style init systems guarantee execution of daemon processes in a clean process context: it is + guaranteed that the environment block is sanitized, that the signal handlers and mask is reset and that no + left-over file descriptors are passed. Daemons will be executed in their own session, with standard input + connected to /dev/null and standard output/error connected to the + systemd-journald.service8 + logging service, unless otherwise configured. The umask is reset. + + + It is recommended for new-style daemons to implement the + following: + + + If SIGTERM is received, + shut down the daemon and exit cleanly. + + If SIGHUP is received, + reload the configuration files, if this + applies. + + Provide a correct exit code from the main + daemon process, as this is used by the init system to detect + service errors and problems. It is recommended to follow the + exit code scheme as defined in the LSB + recommendations for SysV init + scripts. + + If possible and applicable, expose the + daemon's control interface via the D-Bus IPC system and grab a + bus name as last step of initialization. + + For integration in systemd, provide a + .service unit file that carries + information about starting, stopping and otherwise maintaining + the daemon. See + systemd.service5 + for details. + + As much as possible, rely on the init system's + functionality to limit the access of the daemon to files, + services and other resources, i.e. in the case of systemd, + rely on systemd's resource limit control instead of + implementing your own, rely on systemd's privilege dropping + code instead of implementing it in the daemon, and similar. + See + systemd.exec5 + for the available controls. + + If D-Bus is used, make your daemon + bus-activatable by supplying a D-Bus service activation + configuration file. This has multiple advantages: your daemon + may be started lazily on-demand; it may be started in parallel + to other daemons requiring it — which maximizes + parallelization and boot-up speed; your daemon can be + restarted on failure without losing any bus requests, as the + bus queues requests for activatable services. See below for + details. + + If your daemon provides services to other + local processes or remote clients via a socket, it should be + made socket-activatable following the scheme pointed out + below. Like D-Bus activation, this enables on-demand starting + of services as well as it allows improved parallelization of + service start-up. Also, for state-less protocols (such as + syslog, DNS), a daemon implementing socket-based activation + can be restarted without losing a single request. See below + for details. + + If applicable, a daemon should notify the init + system about startup completion or status updates via the + sd_notify3 + interface. + + Instead of using the + syslog() call to log directly to the + system syslog service, a new-style daemon may choose to simply + log to standard error via fprintf(), + which is then forwarded to syslog by the init system. If log + levels are necessary, these can be encoded by prefixing + individual log lines with strings like + <4> (for log level 4 "WARNING" in the + syslog priority scheme), following a similar style as the + Linux kernel's printk() level system. For + details, see + sd-daemon3 + and + systemd.exec5. + + + + These recommendations are similar but not identical to the + Apple + MacOS X Daemon Requirements. + + + + + Activation + + New-style init systems provide multiple additional + mechanisms to activate services, as detailed below. It is common + that services are configured to be activated via more than one + mechanism at the same time. An example for systemd: + bluetoothd.service might get activated either + when Bluetooth hardware is plugged in, or when an application + accesses its programming interfaces via D-Bus. Or, a print server + daemon might get activated when traffic arrives at an IPP port, or + when a printer is plugged in, or when a file is queued in the + printer spool directory. Even for services that are intended to be + started on system bootup unconditionally, it is a good idea to + implement some of the various activation schemes outlined below, + in order to maximize parallelization. If a daemon implements a + D-Bus service or listening socket, implementing the full bus and + socket activation scheme allows starting of the daemon with its + clients in parallel (which speeds up boot-up), since all its + communication channels are established already, and no request is + lost because client requests will be queued by the bus system (in + case of D-Bus) or the kernel (in case of sockets) until the + activation is completed. + + + Activation on Boot + + Old-style daemons are usually activated exclusively on + boot (and manually by the administrator) via SysV init scripts, + as detailed in the LSB + Linux Standard Base Core Specification. This method of + activation is supported ubiquitously on GNU/Linux init systems, both + old-style and new-style systems. Among other issues, SysV init + scripts have the disadvantage of involving shell scripts in the + boot process. New-style init systems generally employ updated + versions of activation, both during boot-up and during runtime + and using more minimal service description files. + + In systemd, if the developer or administrator wants to + make sure that a service or other unit is activated + automatically on boot, it is recommended to place a symlink to + the unit file in the .wants/ directory of + either multi-user.target or + graphical.target, which are normally used + as boot targets at system startup. See + systemd.unit5 + for details about the .wants/ directories, + and + systemd.special7 + for details about the two boot targets. + + + + + Socket-Based Activation + + In order to maximize the possible parallelization and + robustness and simplify configuration and development, it is + recommended for all new-style daemons that communicate via + listening sockets to employ socket-based activation. In a + socket-based activation scheme, the creation and binding of the + listening socket as primary communication channel of daemons to + local (and sometimes remote) clients is moved out of the daemon + code and into the init system. Based on per-daemon + configuration, the init system installs the sockets and then + hands them off to the spawned process as soon as the respective + daemon is to be started. Optionally, activation of the service + can be delayed until the first inbound traffic arrives at the + socket to implement on-demand activation of daemons. However, + the primary advantage of this scheme is that all providers and + all consumers of the sockets can be started in parallel as soon + as all sockets are established. In addition to that, daemons can + be restarted with losing only a minimal number of client + transactions, or even any client request at all (the latter is + particularly true for state-less protocols, such as DNS or + syslog), because the socket stays bound and accessible during + the restart, and all requests are queued while the daemon cannot + process them. + + New-style daemons which support socket activation must be + able to receive their sockets from the init system instead of + creating and binding them themselves. For details about the + programming interfaces for this scheme provided by systemd, see + sd_listen_fds3 + and + sd-daemon3. + For details about porting existing daemons to socket-based + activation, see below. With minimal effort, it is possible to + implement socket-based activation in addition to traditional + internal socket creation in the same codebase in order to + support both new-style and old-style init systems from the same + daemon binary. + + systemd implements socket-based activation via + .socket units, which are described in + systemd.socket5. + When configuring socket units for socket-based activation, it is + essential that all listening sockets are pulled in by the + special target unit sockets.target. It is + recommended to place a + WantedBy=sockets.target directive in the + [Install] section to automatically add such a + dependency on installation of a socket unit. Unless + DefaultDependencies=no is set, the necessary + ordering dependencies are implicitly created for all socket + units. For more information about + sockets.target, see + systemd.special7. + It is not necessary or recommended to place any additional + dependencies on socket units (for example from + multi-user.target or suchlike) when one is + installed in sockets.target. + + + + Bus-Based Activation + + When the D-Bus IPC system is used for communication with + clients, new-style daemons should employ bus activation so that + they are automatically activated when a client application + accesses their IPC interfaces. This is configured in D-Bus + service files (not to be confused with systemd service unit + files!). To ensure that D-Bus uses systemd to start-up and + maintain the daemon, use the SystemdService= + directive in these service files to configure the matching + systemd service for a D-Bus service. e.g.: For a D-Bus service + whose D-Bus activation file is named + org.freedesktop.RealtimeKit.service, make + sure to set + SystemdService=rtkit-daemon.service in that + file to bind it to the systemd service + rtkit-daemon.service. This is needed to + make sure that the daemon is started in a race-free fashion when + activated via multiple mechanisms simultaneously. + + + + Device-Based Activation + + Often, daemons that manage a particular type of hardware + should be activated only when the hardware of the respective + kind is plugged in or otherwise becomes available. In a + new-style init system, it is possible to bind activation to + hardware plug/unplug events. In systemd, kernel devices + appearing in the sysfs/udev device tree can be exposed as units + if they are tagged with the string systemd. + Like any other kind of unit, they may then pull in other units + when activated (i.e. plugged in) and thus implement device-based + activation. systemd dependencies may be encoded in the udev + database via the SYSTEMD_WANTS= property. See + systemd.device5 + for details. Often, it is nicer to pull in services from devices + only indirectly via dedicated targets. Example: Instead of + pulling in bluetoothd.service from all the + various bluetooth dongles and other hardware available, pull in + bluetooth.target from them and + bluetoothd.service from that target. This + provides for nicer abstraction and gives administrators the + option to enable bluetoothd.service via + controlling a bluetooth.target.wants/ + symlink uniformly with a command like enable + of + systemctl1 + instead of manipulating the udev ruleset. + + + + Path-Based Activation + + Often, runtime of daemons processing spool files or + directories (such as a printing system) can be delayed until + these file system objects change state, or become non-empty. + New-style init systems provide a way to bind service activation + to file system changes. systemd implements this scheme via + path-based activation configured in .path + units, as outlined in + systemd.path5. + + + + Timer-Based Activation + + Some daemons that implement clean-up jobs that are + intended to be executed in regular intervals benefit from + timer-based activation. In systemd, this is implemented via + .timer units, as described in + systemd.timer5. + + + + Other Forms of Activation + + Other forms of activation have been suggested and + implemented in some systems. However, there are often simpler or + better alternatives, or they can be put together of combinations + of the schemes above. Example: Sometimes, it appears useful to + start daemons or .socket units when a + specific IP address is configured on a network interface, + because network sockets shall be bound to the address. However, + an alternative to implement this is by utilizing the Linux + IP_FREEBIND socket option, as accessible + via FreeBind=yes in systemd socket files (see + systemd.socket5 + for details). This option, when enabled, allows sockets to be + bound to a non-local, not configured IP address, and hence + allows bindings to a particular IP address before it actually + becomes available, making such an explicit dependency to the + configured address redundant. Another often suggested trigger + for service activation is low system load. However, here too, a + more convincing approach might be to make proper use of features + of the operating system, in particular, the CPU or I/O scheduler + of Linux. Instead of scheduling jobs from userspace based on + monitoring the OS scheduler, it is advisable to leave the + scheduling of processes to the OS scheduler itself. systemd + provides fine-grained access to the CPU and I/O schedulers. If a + process executed by the init system shall not negatively impact + the amount of CPU or I/O bandwidth available to other processes, + it should be configured with + CPUSchedulingPolicy=idle and/or + IOSchedulingClass=idle. Optionally, this may + be combined with timer-based activation to schedule background + jobs during runtime and with minimal impact on the system, and + remove it from the boot phase itself. + + + + + Integration with Systemd + + + Writing Systemd Unit Files + + When writing systemd unit files, it is recommended to + consider the following suggestions: + + + If possible, do not use the + Type=forking setting in service files. But + if you do, make sure to set the PID file path using + PIDFile=. See + systemd.service5 + for details. + + If your daemon registers a D-Bus name on the + bus, make sure to use Type=dbus in the + service file if possible. + + Make sure to set a good human-readable + description string with + Description=. + + Do not disable + DefaultDependencies=, unless you really + know what you do and your unit is involved in early boot or + late system shutdown. + + Normally, little if any dependencies should + need to be defined explicitly. However, if you do configure + explicit dependencies, only refer to unit names listed on + systemd.special7 + or names introduced by your own package to keep the unit file + operating system-independent. + + Make sure to include an + [Install] section including installation + information for the unit file. See + systemd.unit5 + for details. To activate your service on boot, make sure to + add a WantedBy=multi-user.target or + WantedBy=graphical.target directive. To + activate your socket on boot, make sure to add + WantedBy=sockets.target. Usually, you also + want to make sure that when your service is installed, your + socket is installed too, hence add + Also=foo.socket in your service file + foo.service, for a hypothetical program + foo. + + + + + + Installing Systemd Service Files + + At the build installation time (e.g. make + install during package build), packages are + recommended to install their systemd unit files in the directory + returned by pkg-config systemd + --variable=systemdsystemunitdir (for system services) + or pkg-config systemd + --variable=systemduserunitdir (for user services). + This will make the services available in the system on explicit + request but not activate them automatically during boot. + Optionally, during package installation (e.g. rpm + -i by the administrator), symlinks should be created + in the systemd configuration directories via the + enable command of the + systemctl1 + tool to activate them automatically on boot. + + Packages using + autoconf1 + are recommended to use a configure script + excerpt like the following to determine the + unit installation path during source + configuration: + + PKG_PROG_PKG_CONFIG +AC_ARG_WITH([systemdsystemunitdir], + [AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files])],, + [with_systemdsystemunitdir=auto]) +AS_IF([test "x$with_systemdsystemunitdir" = "xyes" -o "x$with_systemdsystemunitdir" = "xauto"], [ + def_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd) + + AS_IF([test "x$def_systemdsystemunitdir" = "x"], + [AS_IF([test "x$with_systemdsystemunitdir" = "xyes"], + [AC_MSG_ERROR([systemd support requested but pkg-config unable to query systemd package])]) + with_systemdsystemunitdir=no], + [with_systemdsystemunitdir="$def_systemdsystemunitdir"])]) +AS_IF([test "x$with_systemdsystemunitdir" != "xno"], + [AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])]) +AM_CONDITIONAL([HAVE_SYSTEMD], [test "x$with_systemdsystemunitdir" != "xno"]) + + This snippet allows automatic + installation of the unit files on systemd + machines, and optionally allows their + installation even on machines lacking + systemd. (Modification of this snippet for the + user unit directory is left as an exercise for the + reader.) + + Additionally, to ensure that + make distcheck continues to + work, it is recommended to add the following + to the top-level Makefile.am + file in + automake1-based + projects: + + DISTCHECK_CONFIGURE_FLAGS = \ + --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir) + + Finally, unit files should be installed in the system with an automake excerpt like the following: + + if HAVE_SYSTEMD +systemdsystemunit_DATA = \ + foobar.socket \ + foobar.service +endif + + In the + rpm8 + .spec file, use snippets like the following + to enable/disable the service during + installation/deinstallation. This makes use of the RPM macros + shipped along systemd. Consult the packaging guidelines of your + distribution for details and the equivalent for other package + managers. + + At the top of the file: + + BuildRequires: systemd +%{?systemd_requires} + + And as scriptlets, further down: + + %post +%systemd_post foobar.service foobar.socket + +%preun +%systemd_preun foobar.service foobar.socket + +%postun +%systemd_postun + + If the service shall be restarted during upgrades, replace + the %postun scriptlet above with the + following: + + %postun +%systemd_postun_with_restart foobar.service + + Note that %systemd_post and + %systemd_preun expect the names of all units + that are installed/removed as arguments, separated by spaces. + %systemd_postun expects no arguments. + %systemd_postun_with_restart expects the + units to restart as arguments. + + To facilitate upgrades from a package version that shipped + only SysV init scripts to a package version that ships both a + SysV init script and a native systemd service file, use a + fragment like the following: + + %triggerun -- foobar < 0.47.11-1 +if /sbin/chkconfig --level 5 foobar ; then + /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&1 || : +fi + + Where 0.47.11-1 is the first package version that includes + the native unit file. This fragment will ensure that the first + time the unit file is installed, it will be enabled if and only + if the SysV init script is enabled, thus making sure that the + enable status is not changed. Note that + chkconfig is a command specific to Fedora + which can be used to check whether a SysV init script is + enabled. Other operating systems will have to use different + commands here. + + + + + Porting Existing Daemons + + Since new-style init systems such as systemd are compatible + with traditional SysV init systems, it is not strictly necessary + to port existing daemons to the new style. However, doing so + offers additional functionality to the daemons as well as + simplifying integration into new-style init systems. + + To port an existing SysV compatible daemon, the following + steps are recommended: + + + If not already implemented, add an optional + command line switch to the daemon to disable daemonization. This + is useful not only for using the daemon in new-style init + systems, but also to ease debugging. + + If the daemon offers interfaces to other + software running on the local system via local + AF_UNIX sockets, consider implementing + socket-based activation (see above). Usually, a minimal patch is + sufficient to implement this: Extend the socket creation in the + daemon code so that + sd_listen_fds3 + is checked for already passed sockets first. If sockets are + passed (i.e. when sd_listen_fds() returns a + positive value), skip the socket creation step and use the + passed sockets. Secondly, ensure that the file system socket + nodes for local AF_UNIX sockets used in the + socket-based activation are not removed when the daemon shuts + down, if sockets have been passed. Third, if the daemon normally + closes all remaining open file descriptors as part of its + initialization, the sockets passed from the init system must be + spared. Since new-style init systems guarantee that no left-over + file descriptors are passed to executed processes, it might be a + good choice to simply skip the closing of all remaining open + file descriptors if sockets are passed. + + Write and install a systemd unit file for the + service (and the sockets if socket-based activation is used, as + well as a path unit file, if the daemon processes a spool + directory), see above for details. + + If the daemon exposes interfaces via D-Bus, + write and install a D-Bus activation file for the service, see + above for details. + + + + + Placing Daemon Data + + It is recommended to follow the general guidelines for + placing package files, as discussed in + file-hierarchy7. + + + + See Also + + systemd1, + sd-daemon3, + sd_listen_fds3, + sd_notify3, + daemon3, + systemd.service5, + file-hierarchy7 + + + + diff --git a/src/manpages/file-hierarchy.xml b/src/manpages/file-hierarchy.xml new file mode 100644 index 0000000000..538a592f8d --- /dev/null +++ b/src/manpages/file-hierarchy.xml @@ -0,0 +1,815 @@ + + + + + + + + + file-hierarchy + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + file-hierarchy + 7 + + + + file-hierarchy + File system hierarchy overview + + + + Description + + Operating systems using the + systemd1 + system and service manager are organized based on a file system + hierarchy inspired by UNIX, more specifically the hierarchy + described in the File + System Hierarchy specification and + hier7. + This manual page describes a more minimal, modernized subset of + these specifications that defines more strictly the suggestions + and restrictions systemd makes on the file system + hierarchy. + + Many of the paths described here can be queried + with the + systemd-path1 + tool. + + + + General Structure + + + + / + The file system root. Usually writable, but + this is not required. Possibly a temporary file system + (tmpfs). Not shared with other hosts + (unless read-only). + + + + /boot + The boot partition used for bringing up the + system. On EFI systems, this is possibly the EFI System + Partition, also see + systemd-gpt-auto-generator8. + This directory is usually strictly local to the host, and + should be considered read-only, except when a new kernel or + boot loader is installed. This directory only exists on + systems that run on physical or emulated hardware that + requires boot loaders. + + + + /etc + System-specific configuration. This directory + may or may not be read-only. Frequently, this directory is + pre-populated with vendor-supplied configuration files, but + applications should not make assumptions about this directory + being fully populated or populated at all, and should fall + back to defaults if configuration is + missing. + + + + /home + The location for normal user's home + directories. Possibly shared with other systems, and never + read-only. This directory should only be used for normal + users, never for system users. This directory and possibly the + directories contained within it might only become available or + writable in late boot or even only after user authentication. + This directory might be placed on limited-functionality + network file systems, hence applications should not assume the + full set of file API is available on this directory. + Applications should generally not reference this directory + directly, but via the per-user $HOME + environment variable, or via the home directory field of the + user database. + + + + /root + The home directory of the root user. The root + user's home directory is located outside of + /home in order to make sure the root user + may log in even without /home being + available and mounted. + + + + /srv + The place to store general server payload, + managed by the administrator. No restrictions are made how + this directory is organized internally. Generally writable, + and possibly shared among systems. This directory might become + available or writable only very late during + boot. + + + + /tmp + The place for small temporary files. This + directory is usually mounted as a tmpfs + instance, and should hence not be used for larger files. (Use + /var/tmp for larger files.) Since the + directory is accessible to other users of the system, it is + essential that this directory is only written to with the + mkstemp3, + mkdtemp3 + and related calls. This directory is usually flushed at + boot-up. Also, files that are not accessed within a certain + time are usually automatically deleted. If applications find + the environment variable $TMPDIR set, they + should prefer using the directory specified in it over + directly referencing /tmp (see + environ7 + and + IEEE + Std 1003.1 for details). + + + + + + + Runtime Data + + + + /run + A tmpfs file system for + system packages to place runtime data in. This directory is + flushed on boot, and generally writable for privileged + programs only. Always writable. + + + + /run/log + Runtime system logs. System components may + place private logs in this directory. Always writable, even + when /var/log might not be accessible + yet. + + + + /run/user + Contains per-user runtime directories, each + usually individually mounted tmpfs + instances. Always writable, flushed at each reboot and when + the user logs out. User code should not reference this + directory directly, but via the + $XDG_RUNTIME_DIR environment variable, as + documented in the XDG + Base Directory Specification. + + + + + + Vendor-supplied Operating System Resources + + + + + /usr + Vendor-supplied operating system resources. + Usually read-only, but this is not required. Possibly shared + between multiple hosts. This directory should not be modified + by the administrator, except when installing or removing + vendor-supplied packages. + + + + /usr/bin + Binaries and executables for user commands + that shall appear in the $PATH search path. + It is recommended not to place binaries in this directory that + are not useful for invocation from a shell (such as daemon + binaries); these should be placed in a subdirectory of + /usr/lib instead. + + + + /usr/include + C and C++ API header files of system + libraries. + + + + /usr/lib + Static, private vendor data that is compatible + with all architectures (though not necessarily + architecture-independent). Note that this includes internal + executables or other binaries that are not regularly invoked + from a shell. Such binaries may be for any architecture + supported by the system. Do not place public libraries in this + directory, use $libdir (see below), + instead. + + + + /usr/lib/arch-id + Location for placing dynamic libraries into, also + called $libdir. The architecture identifier + to use is defined on Multiarch + Architecture Specifiers (Tuples) list. Legacy + locations of $libdir are + /usr/lib, + /usr/lib64. This directory should not be + used for package-specific data, unless this data is + architecture-dependent, too. To query + $libdir for the primary architecture of the + system, invoke: + # systemd-path system-library-arch + + + + + /usr/share + Resources shared between multiple packages, + such as documentation, man pages, time zone information, fonts + and other resources. Usually, the precise location and format + of files stored below this directory is subject to + specifications that ensure interoperability. + + + + /usr/share/doc + Documentation for the operating system or + system packages. + + + + /usr/share/factory/etc + Repository for vendor-supplied default + configuration files. This directory should be populated with + pristine vendor versions of all configuration files that may + be placed in /etc. This is useful to + compare the local configuration of a system with vendor + defaults and to populate the local configuration with + defaults. + + + + /usr/share/factory/var + + Similar to + /usr/share/factory/etc, but for vendor + versions of files in the variable, persistent data directory + /var. + + + + + + + Persistent Variable System Data + + + + /var + Persistent, variable system data. Must be + writable. This directory might be pre-populated with + vendor-supplied data, but applications should be able to + reconstruct necessary files and directories in this + subhierarchy should they be missing, as the system might start + up without this directory being populated. Persistency is + recommended, but optional, to support ephemeral systems. This + directory might become available or writable only very late + during boot. Components that are required to operate during + early boot hence shall not unconditionally rely on this + directory. + + + + /var/cache + Persistent system cache data. System + components may place non-essential data in this directory. + Flushing this directory should have no effect on operation of + programs, except for increased runtimes necessary to rebuild + these caches. + + + + /var/lib + Persistent system data. System components may + place private data in this directory. + + + + /var/log + Persistent system logs. System components may + place private logs in this directory, though it is recommended + to do most logging via the + syslog3 + and + sd_journal_print3 + calls. + + + + /var/spool + Persistent system spool data, such as printer + or mail queues. + + + + /var/tmp + The place for larger and persistent temporary + files. In contrast to /tmp, this directory + is usually mounted from a persistent physical file system and + can thus accept larger files. (Use /tmp + for smaller files.) This directory is generally not flushed at + boot-up, but time-based cleanup of files that have not been + accessed for a certain time is applied. The same security + restrictions as with /tmp apply, and + hence only + mkstemp3, + mkdtemp3 + or similar calls should be used to make use of this directory. + If applications find the environment variable + $TMPDIR set, they should prefer using the + directory specified in it over directly referencing + /var/tmp (see + environ7 + for details). + + + + + + + Virtual Kernel and API File Systems + + + + /dev + The root directory for device nodes. Usually, + this directory is mounted as a devtmpfs + instance, but might be of a different type in + sandboxed/containerized setups. This directory is managed + jointly by the kernel and + systemd-udevd8, + and should not be written to by other components. A number of + special purpose virtual file systems might be mounted below + this directory. + + + + /dev/shm + Place for POSIX shared memory segments, as + created via + shm_open3. + This directory is flushed on boot, and is a + tmpfs file system. Since all users have + write access to this directory, special care should be taken + to avoid name clashes and vulnerabilities. For normal users, + shared memory segments in this directory are usually deleted + when the user logs out. Usually, it is a better idea to use + memory mapped files in /run (for system + programs) or $XDG_RUNTIME_DIR (for user + programs) instead of POSIX shared memory segments, since these + directories are not world-writable and hence not vulnerable to + security-sensitive name clashes. + + + + /proc + A virtual kernel file system exposing the + process list and other functionality. This file system is + mostly an API to interface with the kernel and not a place + where normal files may be stored. For details, see + proc5. + A number of special purpose virtual file systems might be + mounted below this directory. + + + + /proc/sys + A hierarchy below /proc + that exposes a number of kernel tunables. The primary way to + configure the settings in this API file tree is via + sysctl.d5 + files. In sandboxed/containerized setups, this directory is + generally mounted read-only. + + + + /sys + A virtual kernel file system exposing + discovered devices and other functionality. This file system + is mostly an API to interface with the kernel and not a place + where normal files may be stored. In sandboxed/containerized + setups, this directory is generally mounted read-only. A number + of special purpose virtual file systems might be mounted below + this directory. + + + + + + + Compatibility Symlinks + + + + /bin + /sbin + /usr/sbin + + These compatibility symlinks point to + /usr/bin, ensuring that scripts and + binaries referencing these legacy paths correctly find their + binaries. + + + + /lib + + This compatibility symlink points to + /usr/lib, ensuring that programs + referencing this legacy path correctly find their + resources. + + + + /lib64 + + On some architecture ABIs, this compatibility + symlink points to $libdir, ensuring that + binaries referencing this legacy path correctly find their + dynamic loader. This symlink only exists on architectures + whose ABI places the dynamic loader in this + path. + + + + /var/run + + This compatibility symlink points to + /run, ensuring that programs referencing + this legacy path correctly find their runtime + data. + + + + + + + Home Directory + + User applications may want to place files and directories in + the user's home directory. They should follow the following basic + structure. Note that some of these directories are also + standardized (though more weakly) by the XDG + Base Directory Specification. Additional locations for + high-level user resources are defined by xdg-user-dirs. + + + + ~/.cache + + Persistent user cache data. User programs may + place non-essential data in this directory. Flushing this + directory should have no effect on operation of programs, + except for increased runtimes necessary to rebuild these + caches. If an application finds + $XDG_CACHE_HOME set, it should use the + directory specified in it instead of this + directory. + + + + ~/.config + + Application configuration and state. When a + new user is created, this directory will be empty or not exist + at all. Applications should fall back to defaults should their + configuration or state in this directory be missing. If an + application finds $XDG_CONFIG_HOME set, it + should use the directory specified in it instead of this + directory. + + + + ~/.local/bin + + Executables that shall appear in the user's + $PATH search path. It is recommended not to + place executables in this directory that are not useful for + invocation from a shell; these should be placed in a + subdirectory of ~/.local/lib instead. + Care should be taken when placing architecture-dependent + binaries in this place, which might be problematic if the home + directory is shared between multiple hosts with different + architectures. + + + + ~/.local/lib + + Static, private vendor data that is compatible + with all architectures. + + + + ~/.local/lib/arch-id + + Location for placing public dynamic libraries. + The architecture identifier to use is defined on Multiarch + Architecture Specifiers (Tuples) + list. + + + + ~/.local/share + + Resources shared between multiple packages, + such as fonts or artwork. Usually, the precise location and + format of files stored below this directory is subject to + specifications that ensure interoperability. If an application + finds $XDG_DATA_HOME set, it should use the + directory specified in it instead of this + directory. + + + + + + + + Unprivileged Write Access + + Unprivileged processes generally lack write access to most + of the hierarchy. + + The exceptions for normal users are + /tmp, + /var/tmp, + /dev/shm, as well as the home directory + $HOME (usually found below + /home) and the runtime directory + $XDG_RUNTIME_DIR (found below + /run/user) of the user, which are all + writable. + + For unprivileged system processes, only + /tmp, + /var/tmp and + /dev/shm are writable. If an + unprivileged system process needs a private writable directory in + /var or /run, it is + recommended to either create it before dropping privileges in the + daemon code, to create it via + tmpfiles.d5 + fragments during boot, or via the + RuntimeDirectory= directive of service units + (see + systemd.unit5 + for details). + + + + Node Types + + Unix file systems support different types of file nodes, + including regular files, directories, symlinks, character and + block device nodes, sockets and FIFOs. + + It is strongly recommended that /dev is + the only location below which device nodes shall be placed. + Similarly, /run shall be the only location to + place sockets and FIFOs. Regular files, directories and symlinks + may be used in all directories. + + + + System Packages + + Developers of system packages should follow strict rules + when placing their own files in the file system. The following + table lists recommended locations for specific types of files + supplied by the vendor. + + + System Package Vendor Files Locations + + + + + + Directory + Purpose + + + + + /usr/bin + Package executables that shall appear in the $PATH executable search path, compiled for any of the supported architectures compatible with the operating system. It is not recommended to place internal binaries or binaries that are not commonly invoked from the shell in this directory, such as daemon binaries. As this directory is shared with most other packages of the system, special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files. + + + /usr/lib/arch-id + Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes. + + + /usr/lib/package + Private static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data. + + + /usr/lib/arch-id/package + Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures. Note that this generally does not include private executables since binaries of a specific architecture may be freely invoked from any other supported system architecture. + + + /usr/include/package + Public C/C++ APIs of public shared libraries of the package. + + + +
+ + Additional static vendor files may be installed in the + /usr/share hierarchy to the locations + defined by the various relevant specifications. + + During runtime, and for local configuration and state, + additional directories are defined: + + + System Package Variable Files Locations + + + + + + Directory + Purpose + + + + + /etc/package + System-specific configuration for the package. It is recommended to default to safe fallbacks if this configuration is missing, if this is possible. Alternatively, a tmpfiles.d5 fragment may be used to copy or symlink the necessary files and directories from /usr/share/factory during boot, via the L or C directives. + + + /run/package + Runtime data for the package. Packages must be able to create the necessary subdirectories in this tree on their own, since the directory is flushed automatically on boot. Alternatively, a tmpfiles.d5 fragment may be used to create the necessary directories during boot. Alternatively, the RuntimeDirectory= directive of service units may be used (see systemd.unit5 for details.) + + + /run/log/package + Runtime log data for the package. As above, the package needs to make sure to create this directory if necessary, as it will be flushed on every boot. + + + /var/cache/package + Persistent cache data of the package. If this directory is flushed, the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary. + + + /var/lib/package + Persistent private data of the package. This is the primary place to put persistent data that does not fall into the other categories listed. Packages should be able to create the necessary subdirectories in this tree on their own, since the directory might be missing on boot. Alternatively, a tmpfiles.d5 fragment may be used to create the necessary directories during boot. + + + /var/log/package + Persistent log data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing. + + + /var/spool/package + Persistent spool/queue data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing. + + + +
+ + + + User Packages + + Programs running in user context should follow strict rules + when placing their own files in the user's home directory. The + following table lists recommended locations in the home directory + for specific types of files supplied by the vendor if the + application is installed in the home directory. (Note, however, + that user applications installed system-wide should follow the + rules outlined above regarding placing vendor files.) + + + User Package Vendor File Locations + + + + + + Directory + Purpose + + + + + ~/.local/bin + Package executables that shall appear in the $PATH executable search path. It is not recommended to place internal executables or executables that are not commonly invoked from the shell in this directory, such as daemon executables. As this directory is shared with most other packages of the user, special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files. + + + ~/.local/lib/arch-id + Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes. + + + ~/.local/lib/package + Private, static vendor resources of the package, compatible with any architecture, or any other kind of read-only vendor data. + + + ~/.local/lib/arch-id/package + Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures. + + + +
+ + Additional static vendor files may be installed in the + ~/.local/share hierarchy to the locations + defined by the various relevant specifications. + + During runtime, and for local configuration and state, + additional directories are defined: + + + User Package Variable File Locations + + + + + + Directory + Purpose + + + + + ~/.config/package + User-specific configuration and state for the package. It is required to default to safe fallbacks if this configuration is missing. + + + $XDG_RUNTIME_DIR/package + User runtime data for the package. + + + ~/.cache/package + Persistent cache data of the package. If this directory is flushed, the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary. + + + +
+ + + + See Also + + systemd1, + hier7, + systemd-path1, + systemd-gpt-auto-generator8, + sysctl.d5, + tmpfiles.d5, + pkg-config1, + systemd.unit5 + + + + diff --git a/src/manpages/hostname.xml b/src/manpages/hostname.xml new file mode 100644 index 0000000000..8a4c0d5ac0 --- /dev/null +++ b/src/manpages/hostname.xml @@ -0,0 +1,98 @@ + + + + + + + + hostname + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + hostname + 5 + + + + hostname + Local hostname configuration file + + + + /etc/hostname + + + + Description + + The /etc/hostname file configures the + name of the local system that is set during boot using the + sethostname2 + system call. It should contain a single newline-terminated + hostname string. Comments (lines starting with a `#') are ignored. + The hostname may be a free-form string up to 64 characters in length; + however, it is recommended that it consists only of 7-bit ASCII lower-case + characters and no spaces or dots, and limits itself to the format allowed + for DNS domain name labels, even though this is not a strict + requirement. + + You may use + hostnamectl1 + to change the value of this file during runtime from the command + line. Use + systemd-firstboot1 + to initialize it on mounted (but not booted) system images. + + + + History + + The simple configuration file format of + /etc/hostname originates from Debian + GNU/Linux. + + + + See Also + + systemd1, + sethostname2, + hostname1, + hostname7, + machine-id5, + machine-info5, + hostnamectl1, + systemd-hostnamed.service8, + systemd-firstboot1 + + + + diff --git a/src/manpages/locale.conf.xml b/src/manpages/locale.conf.xml new file mode 100644 index 0000000000..2fe731113a --- /dev/null +++ b/src/manpages/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/manpages/localtime.xml b/src/manpages/localtime.xml new file mode 100644 index 0000000000..2827da6e93 --- /dev/null +++ b/src/manpages/localtime.xml @@ -0,0 +1,103 @@ + + + + + + + + localtime + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + Developer + Shawn + Landden + shawnlandden@gmail.com + + + + + + localtime + 5 + + + + localtime + Local timezone configuration file + + + + /etc/localtime -> ../usr/share/zoneinfo/… + + + + Description + + The /etc/localtime file configures the + system-wide timezone of the local system that is used by + applications for presentation to the user. It should be an + absolute or relative symbolic link pointing to + /usr/share/zoneinfo/, followed by a timezone + identifier such as Europe/Berlin or + Etc/UTC. The resulting link should lead to the + corresponding binary + tzfile5 + timezone data for the configured timezone. + + Because the timezone identifier is extracted from the + symlink target name of /etc/localtime, this + file may not be a normal file or hardlink. + + The timezone may be overridden for individual programs by + using the $TZ environment variable. See + environ7. + + You may use + timedatectl1 + to change the settings of this file from the command line during + runtime. Use + systemd-firstboot1 + to initialize the time zone on mounted (but not booted) system + images. + + + + See Also + + systemd1, + tzset3, + localtime3, + timedatectl1, + systemd-timedated.service8, + systemd-firstboot1 + + + + diff --git a/src/manpages/machine-id.xml b/src/manpages/machine-id.xml new file mode 100644 index 0000000000..d318ec54ec --- /dev/null +++ b/src/manpages/machine-id.xml @@ -0,0 +1,146 @@ + + + + + + + + machine-id + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + machine-id + 5 + + + + machine-id + Local machine ID configuration file + + + + /etc/machine-id + + + + Description + + The /etc/machine-id file contains the + unique machine ID of the local system that is set during + installation. The machine ID is a single newline-terminated, + hexadecimal, 32-character, lowercase machine ID string. When + decoded from hexadecimal, this corresponds with a 16-byte/128-bit + string. + + The machine ID is usually generated from a random source + during system installation and stays constant for all subsequent + boots. Optionally, for stateless systems, it is generated during + runtime at early boot if it is found to be empty. + + The machine ID does not change based on user configuration + or when hardware is replaced. + + This machine ID adheres to the same format and logic as the + D-Bus machine ID. + + Programs may use this ID to identify the host with a + globally unique ID in the network, which does not change even if + the local network configuration changes. Due to this and its + greater length, it is a more useful replacement for the + gethostid3 + call that POSIX specifies. + + The + systemd-machine-id-setup1 + tool may be used by installer tools to initialize the machine ID + at install time. Use + systemd-firstboot1 + to initialize it on mounted (but not booted) system images. + + The machine-id may also be set, for example when network + booting, by setting the systemd.machine_id= + kernel command line parameter or passing the option + to systemd. A machine-id may not + be set to all zeros. + + + + Relation to OSF UUIDs + + Note that the machine ID historically is not an OSF UUID as + defined by RFC + 4122, nor a Microsoft GUID; however, starting with systemd + v30, newly generated machine IDs do qualify as v4 UUIDs. + + In order to maintain compatibility with existing + installations, an application requiring a UUID should decode the + machine ID, and then apply the following operations to turn it + into a valid OSF v4 UUID. With id being an + unsigned character array: + + /* Set UUID version to 4 --- truly random generation */ +id[6] = (id[6] & 0x0F) | 0x40; +/* Set the UUID variant to DCE */ +id[8] = (id[8] & 0x3F) | 0x80; + + (This code is inspired by + generate_random_uuid() of + drivers/char/random.c from the Linux kernel + sources.) + + + + + History + + The simple configuration file format of + /etc/machine-id originates in the + /var/lib/dbus/machine-id file introduced by + D-Bus. In fact, this latter file might be a symlink to + /etc/machine-id. + + + + See Also + + systemd1, + systemd-machine-id-setup1, + gethostid3, + hostname5, + machine-info5, + os-release5, + sd-id1283, + sd_id128_get_machine3, + systemd-firstboot1 + + + + diff --git a/src/manpages/machine-info.xml b/src/manpages/machine-info.xml new file mode 100644 index 0000000000..351133670b --- /dev/null +++ b/src/manpages/machine-info.xml @@ -0,0 +1,185 @@ + + + + + + + + machine-info + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + machine-info + 5 + + + + machine-info + Local machine information file + + + + /etc/machine-info + + + + Description + + The /etc/machine-info file contains + machine metadata. + + The basic file format of machine-info + 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. + + /etc/machine-info contains metadata + about the machine that is set by the user or administrator. + + Depending on the operating system other configuration files + might be checked for machine information as well, however only as + fallback. + + You may use + hostnamectl1 + to change the settings of this file from the command line. + + + + Options + + The following machine metadata parameters may be set using + /etc/machine-info: + + + + + PRETTY_HOSTNAME= + + A pretty human-readable UTF-8 machine + identifier string. This should contain a name like + Lennart's Laptop which is useful to present + to the user and does not suffer by the syntax limitations of + internet domain names. If possible, the internet hostname as + configured in /etc/hostname should be + kept similar to this one. Example: if this value is + Lennart's Computer an Internet hostname of + lennarts-computer might be a good choice. + If this parameter is not set, an application should fall back + to the Internet host name for presentation + purposes. + + + + ICON_NAME= + + An icon identifying this machine according to + the XDG + Icon Naming Specification. If this parameter is not + set, an application should fall back to + computer or a similar icon + name. + + + + CHASSIS= + + The chassis type. Currently, the following + chassis types are defined: + desktop, + laptop, + server, + tablet, + handset, + watch, and + embedded, + as well as the special chassis types + vm and + container for + virtualized systems that lack an immediate physical chassis. + Note that many systems allow detection of the chassis type + automatically (based on firmware information or suchlike). + This setting (if set) shall take precedence over automatically + detected information and is useful to override misdetected + configuration or to manually configure the chassis type where + automatic detection is not available. + + + + DEPLOYMENT= + + Describes the system deployment environment. + One of the following is suggested: + development, + integration, + staging, + production. + + + + + LOCATION= + + Describes the system location if applicable + and known. Takes a human-friendly, free-form string. This may + be as generic as Berlin, Germany or as + specific as Left Rack, 2nd Shelf. + + + + + + + Example + + PRETTY_HOSTNAME="Lennart's Tablet" +ICON_NAME=computer-tablet +CHASSIS=tablet +DEPLOYMENT=production + + + + See Also + + systemd1, + os-release5, + hostname5, + machine-id5, + hostnamectl1, + systemd-hostnamed.service8 + + + + diff --git a/src/manpages/os-release.xml b/src/manpages/os-release.xml new file mode 100644 index 0000000000..2811f434c5 --- /dev/null +++ b/src/manpages/os-release.xml @@ -0,0 +1,378 @@ + + + + + + + + os-release + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + os-release + 5 + + + + os-release + Operating system identification + + + + /etc/os-release + /usr/lib/os-release + + + + Description + + The /etc/os-release and + /usr/lib/os-release files contain operating + system identification data. + + The basic file format of os-release 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 (this means variable expansion is + explicitly not supported), allowing applications to read the file + without implementing a shell compatible execution engine. Variable + assignment values must be enclosed in double or single quotes if + they include spaces, semicolons or other special characters + outside of A–Z, a–z, 0–9. Shell special characters ("$", quotes, + backslash, backtick) must be escaped with backslashes, following + shell style. All strings should be in UTF-8 format, and + non-printable characters should not be used. It is not supported + to concatenate multiple individually quoted strings. Lines + beginning with "#" shall be ignored as comments. + + The file /etc/os-release takes + precedence over /usr/lib/os-release. + Applications should check for the former, and exclusively use its + data if it exists, and only fall back to + /usr/lib/os-release if it is missing. + Applications should not read data from both files at the same + time. /usr/lib/os-release is the recommended + place to store OS release information as part of vendor trees. + /etc/os-release should be a relative symlink + to /usr/lib/os-release, to provide + compatibility with applications only looking at + /etc. A relative symlink instead of an + absolute symlink is necessary to avoid breaking the link in a + chroot or initrd environment such as dracut. + + os-release contains data that is + defined by the operating system vendor and should generally not be + changed by the administrator. + + As this file only encodes names and identifiers it should + not be localized. + + The /etc/os-release and + /usr/lib/os-release files might be symlinks + to other files, but it is important that the file is available + from earliest boot on, and hence must be located on the root file + system. + + For a longer rationale for os-release + please refer to the Announcement of /etc/os-release. + + + + Options + + The following OS identifications parameters may be set using + os-release: + + + + + NAME= + + A string identifying the operating system, + without a version component, and suitable for presentation to + the user. If not set, defaults to + NAME=GNU/Linux. Example: + NAME=BLAG or NAME="gNewSense + GNU/Linux". + + + + VERSION= + + A string identifying the operating system + version, excluding any OS name information, possibly including + a release code name, and suitable for presentation to the + user. This field is optional. Example: + VERSION=210k or VERSION="210k + (Spartakus)". + + + + ID= + + A lower-case string (no spaces or other + characters outside of 0–9, a–z, ".", "_" and "-") identifying + the operating system, excluding any version information and + suitable for processing by scripts or usage in generated + filenames. If not set, defaults to + ID=gnu-linux. Example: + ID=blag or + ID=gnewsense. + + + + ID_LIKE= + + A space-separated list of operating system + identifiers in the same syntax as the ID= + setting. It should list identifiers of operating systems that + are closely related to the local operating system in regards + to packaging and programming interfaces, for example listing + one or more OS identifiers the local OS is a derivative from. + An OS should generally only list other OS identifiers it + itself is a derivative of, and not any OSes that are derived + from it, though symmetric relationships are possible. Build + scripts and similar should check this variable if they need to + identify the local operating system and the value of + ID= is not recognized. Operating systems + should be listed in order of how closely the local operating + system relates to the listed ones, starting with the closest. + This field is optional. Example: for an operating system with + ID=blag, an assignment of + ID_LIKE="rhel fedora" would be appropriate. + For an operating system with ID=gnewsense, an + assignment of ID_LIKE=debian is + appropriate. + + + + VERSION_CODENAME= + + + A lower-case string (no spaces or other characters outside of + 0–9, a–z, ".", "_" and "-") identifying the operating system + release code name, excluding any OS name information or + release version, and suitable for processing by scripts or + usage in generated filenames. This field is optional and may + not be implemented on all systems. + Examples: + VERSION_CODENAME=buster, + VERSION_CODENAME=xenial + + + + + VERSION_ID= + + A lower-case string (mostly numeric, no spaces + or other characters outside of 0–9, a–z, ".", "_" and "-") + identifying the operating system version, excluding any OS + name information or release code name, and suitable for + processing by scripts or usage in generated filenames. This + field is optional. Example: VERSION_ID=210k + or VERSION_ID=7.0. + + + + PRETTY_NAME= + + A pretty operating system name in a format + suitable for presentation to the user. May or may not contain + a release code name or OS version of some kind, as suitable. + If not set, defaults to + PRETTY_NAME="GNU/Linux". Example: + PRETTY_NAME="BLAG 210k + (Spartakus)". + + + + ANSI_COLOR= + + A suggested presentation color when showing + the OS name on the console. This should be specified as string + suitable for inclusion in the ESC [ m ANSI/ECMA-48 escape code + for setting graphical rendition. This field is optional. + Example: ANSI_COLOR="0;31" for red, or + ANSI_COLOR="1;34" for light + blue. + + + + CPE_NAME= + + A CPE name for the operating system, in URI + binding syntax, following the + Common + Platform Enumeration Specification as proposed by the + NIST. This field is optional. Example: + CPE_NAME="cpe:/o:blagblagblag:blag:210k" + + + + + HOME_URL= + SUPPORT_URL= + BUG_REPORT_URL= + PRIVACY_POLICY_URL= + + Links to resources on the Internet related the + operating system. HOME_URL= should refer to + the homepage of the operating system, or alternatively some + homepage of the specific version of the operating system. + SUPPORT_URL= should refer to the main + support page for the operating system, if there is any. This + is primarily intended for operating systems which vendors + provide support for. BUG_REPORT_URL= should + refer to the main bug reporting page for the operating system, + if there is any. This is primarily intended for operating + systems that rely on community QA. + PRIVACY_POLICY_URL= should refer to the + main privacy policy page for the operation system, if there is + any. These settings are optional, and providing only some of + these settings is common. These URLs are intended to be + exposed in "About this system" UIs behind links with captions + such as "About this Operating System", "Obtain Support", + "Report a Bug", or "Privacy Policy". The values should be in + RFC3986 + format, and should be http: or + https: URLs, and possibly + mailto: or tel:. Only + one URL shall be listed in each setting. If multiple resources + need to be referenced, it is recommended to provide an online + landing page linking all available resources. Examples: + HOME_URL="https://www.blagblagblag.org/" and + BUG_REPORT_URL="https://blag.fsf.org/" + + + + BUILD_ID= + + A string uniquely identifying the system image + used as the origin for a distribution (it is not updated with + system updates). The field can be identical between different + VERSION_IDs as BUILD_ID is an only a unique identifier to a + specific version. Distributions that release each update as a + new version would only need to use VERSION_ID as each build is + already distinct based on the VERSION_ID. This field is + optional. Example: BUILD_ID="2013-03-20.3" + or BUILD_ID=201303203. + + + + + + VARIANT= + + + A string identifying a specific variant or edition of the + operating system suitable for presentation to the user. This + field may be used to inform the user that the configuration of + this system is subject to a specific divergent set of rules or + default configuration settings. This field is optional and may + not be implemented on all systems. + Examples: + VARIANT="Server Edition", + VARIANT="Smart Refrigerator Edition" + Note: this field is for display purposes only. The + VARIANT_ID field should be used for making + programmatic decisions. + + + + + VARIANT_ID= + + + A lower-case string (no spaces or other characters outside of + 0–9, a–z, ".", "_" and "-"), identifying a specific variant or + edition of the operating system. This may be interpreted by + other packages in order to determine a divergent default + configuration. This field is optional and may not be + implemented on all systems. + Examples: + VARIANT_ID=server, + VARIANT_ID=embedded + + + + + + If you are reading this file from C code or a shell script + to determine the OS or a specific version of it, use the + ID and VERSION_ID fields, + possibly with ID_LIKE as fallback for + ID. When looking for an OS identification + string for presentation to the user use the + PRETTY_NAME field. + + Note that operating system vendors may choose not to provide + version information, for example to accommodate for rolling + releases. In this case, VERSION and + VERSION_ID may be unset. Applications should + not rely on these fields to be set. + + Operating system vendors may extend the file + format and introduce new fields. It is highly + recommended to prefix new fields with an OS specific + name in order to avoid name clashes. Applications + reading this file must ignore unknown fields. Example: + DEBIAN_BTS="debbugs://bugs.gnewsense.org/" + + + + Example + + NAME=Parabola +VERSION="rolling-release" +ID=parabola +ID_LIKE=arch +VERSION_ID=rolling-release +PRETTY_NAME="Parabola GNU/Linux-libre" +ANSI_COLOR="1;35" +CPE_NAME="cpe:/o:parabola:parabola:rolling-release" +HOME_URL="https://www.parabola.nu/" +BUG_REPORT_URL="https://labs.parabola.nu/" + + + + See Also + + systemd1, + lsb_release1, + hostname5, + machine-id5, + machine-info5 + + + + -- cgit v1.2.3-54-g00ecf