diff options
Diffstat (limited to 'src/manpages')
| -rw-r--r-- | src/manpages/daemon.xml | 763 | ||||
| -rw-r--r-- | src/manpages/file-hierarchy.xml | 815 | ||||
| -rw-r--r-- | src/manpages/hostname.xml | 98 | ||||
| -rw-r--r-- | src/manpages/localtime.xml | 103 | ||||
| -rw-r--r-- | src/manpages/machine-id.xml | 146 | ||||
| -rw-r--r-- | src/manpages/machine-info.xml | 185 | ||||
| -rw-r--r-- | src/manpages/os-release.xml | 362 |
7 files changed, 2472 insertions, 0 deletions
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 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="daemon"> + + <refentryinfo> + <title>daemon</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>daemon</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>daemon</refname> + <refpurpose>Writing and packaging system daemons</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>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 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + This manual page covers both schemes, and in particular includes + recommendations for daemons that shall be included in the systemd + init system.</para> + + <refsect2> + <title>SysV Daemons</title> + + <para>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.</para> + + <orderedlist> + <listitem><para>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 + <filename>/proc/self/fd</filename>, with a fallback of + iterating from file descriptor 3 to the value returned by + <function>getrlimit()</function> for + <constant>RLIMIT_NOFILE</constant>. </para></listitem> + + <listitem><para>Reset all signal handlers to their default. + This is best done by iterating through the available signals + up to the limit of <constant>_NSIG</constant> and resetting + them to <constant>SIG_DFL</constant>.</para></listitem> + + <listitem><para>Reset the signal mask + using + <function>sigprocmask()</function>.</para></listitem> + + <listitem><para>Sanitize the environment block, removing or + resetting environment variables that might negatively impact + daemon runtime.</para></listitem> + + <listitem><para>Call <function>fork()</function>, to create a + background process.</para></listitem> + + <listitem><para>In the child, call + <function>setsid()</function> to detach from any terminal and + create an independent session.</para></listitem> + + <listitem><para>In the child, call <function>fork()</function> + again, to ensure that the daemon can never re-acquire a + terminal again.</para></listitem> + + <listitem><para>Call <function>exit()</function> 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.</para></listitem> + + <listitem><para>In the daemon process, connect + <filename>/dev/null</filename> to standard input, output, and + error.</para></listitem> + + <listitem><para>In the daemon process, reset the umask to 0, + so that the file modes passed to <function>open()</function>, + <function>mkdir()</function> and suchlike directly control the + access mode of the created files and + directories.</para></listitem> + + <listitem><para>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.</para></listitem> + + <listitem><para>In the daemon process, write the daemon PID + (as returned by <function>getpid()</function>) to a PID file, + for example <filename>/run/foobar.pid</filename> (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.</para></listitem> + + <listitem><para>In the daemon process, drop privileges, if + possible and applicable.</para></listitem> + + <listitem><para>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 + <function>fork()</function> and hence available in both the + original and the daemon process.</para></listitem> + + <listitem><para>Call <function>exit()</function> in the + original process. The process that invoked the daemon must be + able to rely on that this <function>exit()</function> happens + after initialization is complete and all external + communication channels are established and + accessible.</para></listitem> + </orderedlist> + + <para>The BSD <function>daemon()</function> function should not + be used, as it implements only a subset of these steps.</para> + + <para>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.</para> + </refsect2> + + <refsect2> + <title>New-Style Daemons</title> + + <para>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.</para> + + <para>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.</para> + + <para>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 <filename>/dev/null</filename> and standard output/error connected to the + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + logging service, unless otherwise configured. The umask is reset. + </para> + + <para>It is recommended for new-style daemons to implement the + following:</para> + + <orderedlist> + <listitem><para>If <constant>SIGTERM</constant> is received, + shut down the daemon and exit cleanly.</para></listitem> + + <listitem><para>If <constant>SIGHUP</constant> is received, + reload the configuration files, if this + applies.</para></listitem> + + <listitem><para>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 <ulink + url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB + recommendations for SysV init + scripts</ulink>.</para></listitem> + + <listitem><para>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.</para></listitem> + + <listitem><para>For integration in systemd, provide a + <filename>.service</filename> unit file that carries + information about starting, stopping and otherwise maintaining + the daemon. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + + <listitem><para>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 + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the available controls.</para></listitem> + + <listitem><para>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.</para></listitem> + + <listitem><para>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.</para></listitem> + + <listitem><para>If applicable, a daemon should notify the init + system about startup completion or status updates via the + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + interface.</para></listitem> + + <listitem><para>Instead of using the + <function>syslog()</function> call to log directly to the + system syslog service, a new-style daemon may choose to simply + log to standard error via <function>fprintf()</function>, + 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 + <literal><4></literal> (for log level 4 "WARNING" in the + syslog priority scheme), following a similar style as the + Linux kernel's <function>printk()</function> level system. For + details, see + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + </orderedlist> + + <para>These recommendations are similar but not identical to the + <ulink + url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html">Apple + MacOS X Daemon Requirements</ulink>.</para> + </refsect2> + + </refsect1> + <refsect1> + <title>Activation</title> + + <para>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: + <filename>bluetoothd.service</filename> 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.</para> + + <refsect2> + <title>Activation on Boot</title> + + <para>Old-style daemons are usually activated exclusively on + boot (and manually by the administrator) via SysV init scripts, + as detailed in the <ulink + url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB + Linux Standard Base Core Specification</ulink>. 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.</para> + + <para>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 <filename>.wants/</filename> directory of + either <filename>multi-user.target</filename> or + <filename>graphical.target</filename>, which are normally used + as boot targets at system startup. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details about the <filename>.wants/</filename> directories, + and + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about the two boot targets.</para> + + </refsect2> + + <refsect2> + <title>Socket-Based Activation</title> + + <para>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.</para> + + <para>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 + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + 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.</para> + + <para>systemd implements socket-based activation via + <filename>.socket</filename> units, which are described in + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + When configuring socket units for socket-based activation, it is + essential that all listening sockets are pulled in by the + special target unit <filename>sockets.target</filename>. It is + recommended to place a + <varname>WantedBy=sockets.target</varname> directive in the + <literal>[Install]</literal> section to automatically add such a + dependency on installation of a socket unit. Unless + <varname>DefaultDependencies=no</varname> is set, the necessary + ordering dependencies are implicitly created for all socket + units. For more information about + <filename>sockets.target</filename>, see + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + It is not necessary or recommended to place any additional + dependencies on socket units (for example from + <filename>multi-user.target</filename> or suchlike) when one is + installed in <filename>sockets.target</filename>.</para> + </refsect2> + + <refsect2> + <title>Bus-Based Activation</title> + + <para>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 <varname>SystemdService=</varname> + 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 + <filename>org.freedesktop.RealtimeKit.service</filename>, make + sure to set + <varname>SystemdService=rtkit-daemon.service</varname> in that + file to bind it to the systemd service + <filename>rtkit-daemon.service</filename>. This is needed to + make sure that the daemon is started in a race-free fashion when + activated via multiple mechanisms simultaneously.</para> + </refsect2> + + <refsect2> + <title>Device-Based Activation</title> + + <para>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 <literal>systemd</literal>. + 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 <varname>SYSTEMD_WANTS=</varname> property. See + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. Often, it is nicer to pull in services from devices + only indirectly via dedicated targets. Example: Instead of + pulling in <filename>bluetoothd.service</filename> from all the + various bluetooth dongles and other hardware available, pull in + bluetooth.target from them and + <filename>bluetoothd.service</filename> from that target. This + provides for nicer abstraction and gives administrators the + option to enable <filename>bluetoothd.service</filename> via + controlling a <filename>bluetooth.target.wants/</filename> + symlink uniformly with a command like <command>enable</command> + of + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + instead of manipulating the udev ruleset.</para> + </refsect2> + + <refsect2> + <title>Path-Based Activation</title> + + <para>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 <filename>.path</filename> + units, as outlined in + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect2> + + <refsect2> + <title>Timer-Based Activation</title> + + <para>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 + <filename>.timer</filename> units, as described in + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect2> + + <refsect2> + <title>Other Forms of Activation</title> + + <para>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 <filename>.socket</filename> 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 + <constant>IP_FREEBIND</constant> socket option, as accessible + via <varname>FreeBind=yes</varname> in systemd socket files (see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + 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 + <varname>CPUSchedulingPolicy=idle</varname> and/or + <varname>IOSchedulingClass=idle</varname>. 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.</para> + </refsect2> + + </refsect1> + <refsect1> + <title>Integration with Systemd</title> + + <refsect2> + <title>Writing Systemd Unit Files</title> + + <para>When writing systemd unit files, it is recommended to + consider the following suggestions:</para> + + <orderedlist> + <listitem><para>If possible, do not use the + <varname>Type=forking</varname> setting in service files. But + if you do, make sure to set the PID file path using + <varname>PIDFile=</varname>. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + + <listitem><para>If your daemon registers a D-Bus name on the + bus, make sure to use <varname>Type=dbus</varname> in the + service file if possible.</para></listitem> + + <listitem><para>Make sure to set a good human-readable + description string with + <varname>Description=</varname>.</para></listitem> + + <listitem><para>Do not disable + <varname>DefaultDependencies=</varname>, unless you really + know what you do and your unit is involved in early boot or + late system shutdown.</para></listitem> + + <listitem><para>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 + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + or names introduced by your own package to keep the unit file + operating system-independent.</para></listitem> + + <listitem><para>Make sure to include an + <literal>[Install]</literal> section including installation + information for the unit file. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. To activate your service on boot, make sure to + add a <varname>WantedBy=multi-user.target</varname> or + <varname>WantedBy=graphical.target</varname> directive. To + activate your socket on boot, make sure to add + <varname>WantedBy=sockets.target</varname>. Usually, you also + want to make sure that when your service is installed, your + socket is installed too, hence add + <varname>Also=foo.socket</varname> in your service file + <filename>foo.service</filename>, for a hypothetical program + <filename>foo</filename>.</para></listitem> + + </orderedlist> + </refsect2> + + <refsect2> + <title>Installing Systemd Service Files</title> + + <para>At the build installation time (e.g. <command>make + install</command> during package build), packages are + recommended to install their systemd unit files in the directory + returned by <command>pkg-config systemd + --variable=systemdsystemunitdir</command> (for system services) + or <command>pkg-config systemd + --variable=systemduserunitdir</command> (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. <command>rpm + -i</command> by the administrator), symlinks should be created + in the systemd configuration directories via the + <command>enable</command> command of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool to activate them automatically on boot.</para> + + <para>Packages using + <citerefentry project='die-net'><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry> + are recommended to use a configure script + excerpt like the following to determine the + unit installation path during source + configuration:</para> + + <programlisting>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"])</programlisting> + + <para>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.)</para> + + <para>Additionally, to ensure that + <command>make distcheck</command> continues to + work, it is recommended to add the following + to the top-level <filename>Makefile.am</filename> + file in + <citerefentry project='die-net'><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based + projects:</para> + + <programlisting>DISTCHECK_CONFIGURE_FLAGS = \ + --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting> + + <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para> + + <programlisting>if HAVE_SYSTEMD +systemdsystemunit_DATA = \ + foobar.socket \ + foobar.service +endif</programlisting> + + <para>In the + <citerefentry project='die-net'><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry> + <filename>.spec</filename> 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.</para> + + <para>At the top of the file:</para> + + <programlisting>BuildRequires: systemd +%{?systemd_requires}</programlisting> + + <para>And as scriptlets, further down:</para> + + <programlisting>%post +%systemd_post foobar.service foobar.socket + +%preun +%systemd_preun foobar.service foobar.socket + +%postun +%systemd_postun</programlisting> + + <para>If the service shall be restarted during upgrades, replace + the <literal>%postun</literal> scriptlet above with the + following:</para> + + <programlisting>%postun +%systemd_postun_with_restart foobar.service</programlisting> + + <para>Note that <literal>%systemd_post</literal> and + <literal>%systemd_preun</literal> expect the names of all units + that are installed/removed as arguments, separated by spaces. + <literal>%systemd_postun</literal> expects no arguments. + <literal>%systemd_postun_with_restart</literal> expects the + units to restart as arguments.</para> + + <para>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:</para> + + <programlisting>%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</programlisting> + + <para>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 + <command>chkconfig</command> 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.</para> + </refsect2> + </refsect1> + + <refsect1> + <title>Porting Existing Daemons</title> + + <para>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.</para> + + <para>To port an existing SysV compatible daemon, the following + steps are recommended:</para> + + <orderedlist> + <listitem><para>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.</para></listitem> + + <listitem><para>If the daemon offers interfaces to other + software running on the local system via local + <constant>AF_UNIX</constant> 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 + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + is checked for already passed sockets first. If sockets are + passed (i.e. when <function>sd_listen_fds()</function> returns a + positive value), skip the socket creation step and use the + passed sockets. Secondly, ensure that the file system socket + nodes for local <constant>AF_UNIX</constant> 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.</para></listitem> + + <listitem><para>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.</para></listitem> + + <listitem><para>If the daemon exposes interfaces via D-Bus, + write and install a D-Bus activation file for the service, see + above for details.</para></listitem> + </orderedlist> + </refsect1> + + <refsect1> + <title>Placing Daemon Data</title> + + <para>It is recommended to follow the general guidelines for + placing package files, as discussed in + <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="file-hierarchy"> + + <refentryinfo> + <title>file-hierarchy</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>file-hierarchy</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>file-hierarchy</refname> + <refpurpose>File system hierarchy overview</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>Operating systems using the + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + system and service manager are organized based on a file system + hierarchy inspired by UNIX, more specifically the hierarchy + described in the <ulink + url="http://refspecs.linuxfoundation.org/FHS_2.3/fhs-2.3.html">File + System Hierarchy</ulink> specification and + <citerefentry project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + 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.</para> + + <para>Many of the paths described here can be queried + with the + <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool.</para> + </refsect1> + + <refsect1> + <title>General Structure</title> + + <variablelist> + <varlistentry> + <term><filename>/</filename></term> + <listitem><para>The file system root. Usually writable, but + this is not required. Possibly a temporary file system + (<literal>tmpfs</literal>). Not shared with other hosts + (unless read-only). </para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/boot</filename></term> + <listitem><para>The boot partition used for bringing up the + system. On EFI systems, this is possibly the EFI System + Partition, also see + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + 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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/etc</filename></term> + <listitem><para>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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/home</filename></term> + <listitem><para>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 <varname>$HOME</varname> + environment variable, or via the home directory field of the + user database.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/root</filename></term> + <listitem><para>The home directory of the root user. The root + user's home directory is located outside of + <filename>/home</filename> in order to make sure the root user + may log in even without <filename>/home</filename> being + available and mounted.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/srv</filename></term> + <listitem><para>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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/tmp</filename></term> + <listitem><para>The place for small temporary files. This + directory is usually mounted as a <literal>tmpfs</literal> + instance, and should hence not be used for larger files. (Use + <filename>/var/tmp</filename> 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 + <citerefentry project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry> + 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 <varname>$TMPDIR</varname> set, they + should prefer using the directory specified in it over + directly referencing <filename>/tmp</filename> (see + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and + <ulink url="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">IEEE + Std 1003.1</ulink> for details).</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Runtime Data</title> + + <variablelist> + <varlistentry> + <term><filename>/run</filename></term> + <listitem><para>A <literal>tmpfs</literal> 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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/run/log</filename></term> + <listitem><para>Runtime system logs. System components may + place private logs in this directory. Always writable, even + when <filename>/var/log</filename> might not be accessible + yet.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/run/user</filename></term> + <listitem><para>Contains per-user runtime directories, each + usually individually mounted <literal>tmpfs</literal> + instances. Always writable, flushed at each reboot and when + the user logs out. User code should not reference this + directory directly, but via the + <varname>$XDG_RUNTIME_DIR</varname> environment variable, as + documented in the <ulink + url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG + Base Directory Specification</ulink>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Vendor-supplied Operating System Resources</title> + + <variablelist> + + <varlistentry> + <term><filename>/usr</filename></term> + <listitem><para>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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/bin</filename></term> + <listitem><para>Binaries and executables for user commands + that shall appear in the <varname>$PATH</varname> 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 + <filename>/usr/lib</filename> instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/include</filename></term> + <listitem><para>C and C++ API header files of system + libraries.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/lib</filename></term> + <listitem><para>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 <varname>$libdir</varname> (see below), + instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/lib/<replaceable>arch-id</replaceable></filename></term> + <listitem><para>Location for placing dynamic libraries into, also + called <varname>$libdir</varname>. The architecture identifier + to use is defined on <ulink + url="https://wiki.debian.org/Multiarch/Tuples">Multiarch + Architecture Specifiers (Tuples)</ulink> list. Legacy + locations of <varname>$libdir</varname> are + <filename>/usr/lib</filename>, + <filename>/usr/lib64</filename>. This directory should not be + used for package-specific data, unless this data is + architecture-dependent, too. To query + <varname>$libdir</varname> for the primary architecture of the + system, invoke: + <programlisting># systemd-path system-library-arch</programlisting></para></listitem> + + </varlistentry> + + <varlistentry> + <term><filename>/usr/share</filename></term> + <listitem><para>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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/share/doc</filename></term> + <listitem><para>Documentation for the operating system or + system packages.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/share/factory/etc</filename></term> + <listitem><para>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 <filename>/etc</filename>. This is useful to + compare the local configuration of a system with vendor + defaults and to populate the local configuration with + defaults.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/share/factory/var</filename></term> + + <listitem><para>Similar to + <filename>/usr/share/factory/etc</filename>, but for vendor + versions of files in the variable, persistent data directory + <filename>/var</filename>.</para></listitem> + + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Persistent Variable System Data</title> + + <variablelist> + <varlistentry> + <term><filename>/var</filename></term> + <listitem><para>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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/cache</filename></term> + <listitem><para>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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/lib</filename></term> + <listitem><para>Persistent system data. System components may + place private data in this directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/log</filename></term> + <listitem><para>Persistent system logs. System components may + place private logs in this directory, though it is recommended + to do most logging via the + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> + calls.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/spool</filename></term> + <listitem><para>Persistent system spool data, such as printer + or mail queues.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/tmp</filename></term> + <listitem><para>The place for larger and persistent temporary + files. In contrast to <filename>/tmp</filename>, this directory + is usually mounted from a persistent physical file system and + can thus accept larger files. (Use <filename>/tmp</filename> + 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 <filename>/tmp</filename> apply, and + hence only + <citerefentry project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or similar calls should be used to make use of this directory. + If applications find the environment variable + <varname>$TMPDIR</varname> set, they should prefer using the + directory specified in it over directly referencing + <filename>/var/tmp</filename> (see + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). </para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Virtual Kernel and API File Systems</title> + + <variablelist> + <varlistentry> + <term><filename>/dev</filename></term> + <listitem><para>The root directory for device nodes. Usually, + this directory is mounted as a <literal>devtmpfs</literal> + instance, but might be of a different type in + sandboxed/containerized setups. This directory is managed + jointly by the kernel and + <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + and should not be written to by other components. A number of + special purpose virtual file systems might be mounted below + this directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/dev/shm</filename></term> + <listitem><para>Place for POSIX shared memory segments, as + created via + <citerefentry project='die-net'><refentrytitle>shm_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This directory is flushed on boot, and is a + <literal>tmpfs</literal> 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 <filename>/run</filename> (for system + programs) or <varname>$XDG_RUNTIME_DIR</varname> (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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/proc</filename></term> + <listitem><para>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 + <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + A number of special purpose virtual file systems might be + mounted below this directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/proc/sys</filename></term> + <listitem><para>A hierarchy below <filename>/proc</filename> + that exposes a number of kernel tunables. The primary way to + configure the settings in this API file tree is via + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + files. In sandboxed/containerized setups, this directory is + generally mounted read-only.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/sys</filename></term> + <listitem><para>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.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Compatibility Symlinks</title> + + <variablelist> + <varlistentry> + <term><filename>/bin</filename></term> + <term><filename>/sbin</filename></term> + <term><filename>/usr/sbin</filename></term> + + <listitem><para>These compatibility symlinks point to + <filename>/usr/bin</filename>, ensuring that scripts and + binaries referencing these legacy paths correctly find their + binaries.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/lib</filename></term> + + <listitem><para>This compatibility symlink points to + <filename>/usr/lib</filename>, ensuring that programs + referencing this legacy path correctly find their + resources.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/lib64</filename></term> + + <listitem><para>On some architecture ABIs, this compatibility + symlink points to <varname>$libdir</varname>, 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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/run</filename></term> + + <listitem><para>This compatibility symlink points to + <filename>/run</filename>, ensuring that programs referencing + this legacy path correctly find their runtime + data.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Home Directory</title> + + <para>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 <ulink + url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG + Base Directory Specification</ulink>. Additional locations for + high-level user resources are defined by <ulink + url="http://www.freedesktop.org/wiki/Software/xdg-user-dirs/">xdg-user-dirs</ulink>.</para> + + <variablelist> + <varlistentry> + <term><filename>~/.cache</filename></term> + + <listitem><para>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 + <varname>$XDG_CACHE_HOME</varname> set, it should use the + directory specified in it instead of this + directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>~/.config</filename></term> + + <listitem><para>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 <varname>$XDG_CONFIG_HOME</varname> set, it + should use the directory specified in it instead of this + directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>~/.local/bin</filename></term> + + <listitem><para>Executables that shall appear in the user's + <varname>$PATH</varname> 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 <filename>~/.local/lib</filename> 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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>~/.local/lib</filename></term> + + <listitem><para>Static, private vendor data that is compatible + with all architectures.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>~/.local/lib/<replaceable>arch-id</replaceable></filename></term> + + <listitem><para>Location for placing public dynamic libraries. + The architecture identifier to use is defined on <ulink + url="https://wiki.debian.org/Multiarch/Tuples">Multiarch + Architecture Specifiers (Tuples)</ulink> + list.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>~/.local/share</filename></term> + + <listitem><para>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 <varname>$XDG_DATA_HOME</varname> set, it should use the + directory specified in it instead of this + directory.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + + <refsect1> + <title>Unprivileged Write Access</title> + + <para>Unprivileged processes generally lack write access to most + of the hierarchy.</para> + + <para>The exceptions for normal users are + <filename>/tmp</filename>, + <filename>/var/tmp</filename>, + <filename>/dev/shm</filename>, as well as the home directory + <varname>$HOME</varname> (usually found below + <filename>/home</filename>) and the runtime directory + <varname>$XDG_RUNTIME_DIR</varname> (found below + <filename>/run/user</filename>) of the user, which are all + writable.</para> + + <para>For unprivileged system processes, only + <filename>/tmp</filename>, + <filename>/var/tmp</filename> and + <filename>/dev/shm</filename> are writable. If an + unprivileged system process needs a private writable directory in + <filename>/var</filename> or <filename>/run</filename>, it is + recommended to either create it before dropping privileges in the + daemon code, to create it via + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + fragments during boot, or via the + <varname>RuntimeDirectory=</varname> directive of service units + (see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details).</para> + </refsect1> + + <refsect1> + <title>Node Types</title> + + <para>Unix file systems support different types of file nodes, + including regular files, directories, symlinks, character and + block device nodes, sockets and FIFOs.</para> + + <para>It is strongly recommended that <filename>/dev</filename> is + the only location below which device nodes shall be placed. + Similarly, <filename>/run</filename> shall be the only location to + place sockets and FIFOs. Regular files, directories and symlinks + may be used in all directories.</para> + </refsect1> + + <refsect1> + <title>System Packages</title> + + <para>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.</para> + + <table> + <title>System Package Vendor Files Locations</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="directory" /> + <colspec colname="purpose" /> + <thead> + <row> + <entry>Directory</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>/usr/bin</filename></entry> + <entry>Package executables that shall appear in the <varname>$PATH</varname> 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.</entry> + </row> + <row> + <entry><filename>/usr/lib/<replaceable>arch-id</replaceable></filename></entry> + <entry>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.</entry> + </row> + <row> + <entry><filename>/usr/lib/<replaceable>package</replaceable></filename></entry> + <entry>Private static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data.</entry> + </row> + <row> + <entry><filename>/usr/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable></filename></entry> + <entry>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.</entry> + </row> + <row> + <entry><filename>/usr/include/<replaceable>package</replaceable></filename></entry> + <entry>Public C/C++ APIs of public shared libraries of the package.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Additional static vendor files may be installed in the + <filename>/usr/share</filename> hierarchy to the locations + defined by the various relevant specifications.</para> + + <para>During runtime, and for local configuration and state, + additional directories are defined:</para> + + <table> + <title>System Package Variable Files Locations</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="directory" /> + <colspec colname="purpose" /> + <thead> + <row> + <entry>Directory</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>/etc/<replaceable>package</replaceable></filename></entry> + <entry>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 <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to copy or symlink the necessary files and directories from <filename>/usr/share/factory</filename> during boot, via the <literal>L</literal> or <literal>C</literal> directives.</entry> + </row> + <row> + <entry><filename>/run/<replaceable>package</replaceable></filename></entry> + <entry>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 <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to create the necessary directories during boot. Alternatively, the <varname>RuntimeDirectory=</varname> directive of service units may be used (see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.)</entry> + </row> + <row> + <entry><filename>/run/log/<replaceable>package</replaceable></filename></entry> + <entry>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.</entry> + </row> + <row> + <entry><filename>/var/cache/<replaceable>package</replaceable></filename></entry> + <entry>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.</entry> + </row> + <row> + <entry><filename>/var/lib/<replaceable>package</replaceable></filename></entry> + <entry>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 <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to create the necessary directories during boot.</entry> + </row> + <row> + <entry><filename>/var/log/<replaceable>package</replaceable></filename></entry> + <entry>Persistent log data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing.</entry> + </row> + <row> + <entry><filename>/var/spool/<replaceable>package</replaceable></filename></entry> + <entry>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.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + <title>User Packages</title> + + <para>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.)</para> + + <table> + <title>User Package Vendor File Locations</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="directory" /> + <colspec colname="purpose" /> + <thead> + <row> + <entry>Directory</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>~/.local/bin</filename></entry> + <entry>Package executables that shall appear in the <varname>$PATH</varname> 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.</entry> + </row> + <row> + <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable></filename></entry> + <entry>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.</entry> + </row> + <row> + <entry><filename>~/.local/lib/<replaceable>package</replaceable></filename></entry> + <entry>Private, static vendor resources of the package, compatible with any architecture, or any other kind of read-only vendor data.</entry> + </row> + <row> + <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable></filename></entry> + <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Additional static vendor files may be installed in the + <filename>~/.local/share</filename> hierarchy to the locations + defined by the various relevant specifications.</para> + + <para>During runtime, and for local configuration and state, + additional directories are defined:</para> + + <table> + <title>User Package Variable File Locations</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="directory" /> + <colspec colname="purpose" /> + <thead> + <row> + <entry>Directory</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>~/.config/<replaceable>package</replaceable></filename></entry> + <entry>User-specific configuration and state for the package. It is required to default to safe fallbacks if this configuration is missing.</entry> + </row> + <row> + <entry><filename><varname>$XDG_RUNTIME_DIR</varname>/<replaceable>package</replaceable></filename></entry> + <entry>User runtime data for the package.</entry> + </row> + <row> + <entry><filename>~/.cache/<replaceable>package</replaceable></filename></entry> + <entry>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.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="hostname"> + <refentryinfo> + <title>hostname</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>hostname</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>hostname</refname> + <refpurpose>Local hostname configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/hostname</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/hostname</filename> file configures the + name of the local system that is set during boot using the + <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry> + 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.</para> + + <para>You may use + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to change the value of this file during runtime from the command + line. Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize it on mounted (but not booted) system images.</para> + </refsect1> + + <refsect1> + <title>History</title> + + <para>The simple configuration file format of + <filename>/etc/hostname</filename> originates from Debian + GNU/Linux.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + Copyright 2012 Shawn Landden + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="localtime"> + <refentryinfo> + <title>localtime</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + <author> + <contrib>Developer</contrib> + <firstname>Shawn</firstname> + <surname>Landden</surname> + <email>shawnlandden@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>localtime</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>localtime</refname> + <refpurpose>Local timezone configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/localtime</filename> -> <filename>../usr/share/zoneinfo/…</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/localtime</filename> 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 + <filename>/usr/share/zoneinfo/</filename>, followed by a timezone + identifier such as <literal>Europe/Berlin</literal> or + <literal>Etc/UTC</literal>. The resulting link should lead to the + corresponding binary + <citerefentry project='man-pages'><refentrytitle>tzfile</refentrytitle><manvolnum>5</manvolnum></citerefentry> + timezone data for the configured timezone.</para> + + <para>Because the timezone identifier is extracted from the + symlink target name of <filename>/etc/localtime</filename>, this + file may not be a normal file or hardlink.</para> + + <para>The timezone may be overridden for individual programs by + using the <varname>$TZ</varname> environment variable. See + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>You may use + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to change the settings of this file from the command line during + runtime. Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize the time zone on mounted (but not booted) system + images.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>tzset</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="machine-id"> + <refentryinfo> + <title>machine-id</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>machine-id</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>machine-id</refname> + <refpurpose>Local machine ID configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/machine-id</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/machine-id</filename> 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.</para> + + <para>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.</para> + + <para>The machine ID does not change based on user configuration + or when hardware is replaced.</para> + + <para>This machine ID adheres to the same format and logic as the + D-Bus machine ID.</para> + + <para>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 + <citerefentry project='man-pages'><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call that POSIX specifies.</para> + + <para>The + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool may be used by installer tools to initialize the machine ID + at install time. Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize it on mounted (but not booted) system images.</para> + + <para>The machine-id may also be set, for example when network + booting, by setting the <varname>systemd.machine_id=</varname> + kernel command line parameter or passing the option + <option>--machine-id=</option> to systemd. A machine-id may not + be set to all zeros.</para> + </refsect1> + + <refsect1> + <title>Relation to OSF UUIDs</title> + + <para>Note that the machine ID historically is not an OSF UUID as + defined by <ulink url="https://tools.ietf.org/html/rfc4122">RFC + 4122</ulink>, nor a Microsoft GUID; however, starting with systemd + v30, newly generated machine IDs do qualify as v4 UUIDs.</para> + + <para>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 <literal>id</literal> being an + unsigned character array:</para> + + <programlisting>/* 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;</programlisting> + + <para>(This code is inspired by + <literal>generate_random_uuid()</literal> of + <filename>drivers/char/random.c</filename> from the Linux kernel + sources.)</para> + + </refsect1> + + <refsect1> + <title>History</title> + + <para>The simple configuration file format of + <filename>/etc/machine-id</filename> originates in the + <filename>/var/lib/dbus/machine-id</filename> file introduced by + D-Bus. In fact, this latter file might be a symlink to + <filename>/etc/machine-id</filename>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="machine-info"> + <refentryinfo> + <title>machine-info</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>machine-info</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>machine-info</refname> + <refpurpose>Local machine information file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/machine-info</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/machine-info</filename> file contains + machine metadata.</para> + + <para>The basic file format of <filename>machine-info</filename> + 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.</para> + + <para><filename>/etc/machine-info</filename> contains metadata + about the machine that is set by the user or administrator.</para> + + <para>Depending on the operating system other configuration files + might be checked for machine information as well, however only as + fallback.</para> + + <para>You may use + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to change the settings of this file from the command line.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following machine metadata parameters may be set using + <filename>/etc/machine-info</filename>:</para> + + <variablelist> + + <varlistentry> + <term><varname>PRETTY_HOSTNAME=</varname></term> + + <listitem><para>A pretty human-readable UTF-8 machine + identifier string. This should contain a name like + <literal>Lennart's Laptop</literal> 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 <filename>/etc/hostname</filename> should be + kept similar to this one. Example: if this value is + <literal>Lennart's Computer</literal> an Internet hostname of + <literal>lennarts-computer</literal> might be a good choice. + If this parameter is not set, an application should fall back + to the Internet host name for presentation + purposes.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ICON_NAME=</varname></term> + + <listitem><para>An icon identifying this machine according to + the <ulink + url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG + Icon Naming Specification</ulink>. If this parameter is not + set, an application should fall back to + <literal>computer</literal> or a similar icon + name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CHASSIS=</varname></term> + + <listitem><para>The chassis type. Currently, the following + chassis types are defined: + <literal>desktop</literal>, + <literal>laptop</literal>, + <literal>server</literal>, + <literal>tablet</literal>, + <literal>handset</literal>, + <literal>watch</literal>, and + <literal>embedded</literal>, + as well as the special chassis types + <literal>vm</literal> and + <literal>container</literal> 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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DEPLOYMENT=</varname></term> + + <listitem><para>Describes the system deployment environment. + One of the following is suggested: + <literal>development</literal>, + <literal>integration</literal>, + <literal>staging</literal>, + <literal>production</literal>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LOCATION=</varname></term> + + <listitem><para>Describes the system location if applicable + and known. Takes a human-friendly, free-form string. This may + be as generic as <literal>Berlin, Germany</literal> or as + specific as <literal>Left Rack, 2nd Shelf</literal>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Example</title> + + <programlisting>PRETTY_HOSTNAME="Lennart's Tablet" +ICON_NAME=computer-tablet +CHASSIS=tablet +DEPLOYMENT=production</programlisting> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/src/manpages/os-release.xml b/src/manpages/os-release.xml new file mode 100644 index 0000000000..a70ba1aa31 --- /dev/null +++ b/src/manpages/os-release.xml @@ -0,0 +1,362 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="os-release"> + <refentryinfo> + <title>os-release</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>os-release</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>os-release</refname> + <refpurpose>Operating system identification</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/os-release</filename></para> + <para><filename>/usr/lib/os-release</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/os-release</filename> and + <filename>/usr/lib/os-release</filename> files contain operating + system identification data.</para> + + <para>The basic file format of <filename>os-release</filename> 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.</para> + + <para>The file <filename>/etc/os-release</filename> takes + precedence over <filename>/usr/lib/os-release</filename>. + Applications should check for the former, and exclusively use its + data if it exists, and only fall back to + <filename>/usr/lib/os-release</filename> if it is missing. + Applications should not read data from both files at the same + time. <filename>/usr/lib/os-release</filename> is the recommended + place to store OS release information as part of vendor trees. + <filename>/etc/os-release</filename> should be a relative symlink + to <filename>/usr/lib/os-release</filename>, to provide + compatibility with applications only looking at + <filename>/etc</filename>. A relative symlink instead of an + absolute symlink is necessary to avoid breaking the link in a + chroot or initrd environment such as dracut.</para> + + <para><filename>os-release</filename> contains data that is + defined by the operating system vendor and should generally not be + changed by the administrator.</para> + + <para>As this file only encodes names and identifiers it should + not be localized.</para> + + <para>The <filename>/etc/os-release</filename> and + <filename>/usr/lib/os-release</filename> 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.</para> + + <para>For a longer rationale for <filename>os-release</filename> + please refer to the <ulink + url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following OS identifications parameters may be set using + <filename>os-release</filename>:</para> + + <variablelist> + + <varlistentry> + <term><varname>NAME=</varname></term> + + <listitem><para>A string identifying the operating system, + without a version component, and suitable for presentation to + the user. If not set, defaults to + <literal>NAME=GNU/Linux</literal>. Example: + <literal>NAME=BLAG</literal> or <literal>NAME="gNewSense + GNU/Linux"</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VERSION=</varname></term> + + <listitem><para>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: + <literal>VERSION=210k</literal> or <literal>VERSION="210k + (Spartakus)"</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ID=</varname></term> + + <listitem><para>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 + <literal>ID=gnu-linux</literal>. Example: + <literal>ID=blag</literal> or + <literal>ID=gnewsense</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ID_LIKE=</varname></term> + + <listitem><para>A space-separated list of operating system + identifiers in the same syntax as the <varname>ID=</varname> + 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 + <varname>ID=</varname> 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 + <literal>ID=blag</literal>, an assignment of + <literal>ID_LIKE="rhel fedora"</literal> would be appropriate. + For an operating system with <literal>ID=gnewsense</literal>, an + assignment of <literal>ID_LIKE=debian</literal> is + appropriate.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VERSION_ID=</varname></term> + + <listitem><para>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: <literal>VERSION_ID=210k</literal> + or <literal>VERSION_ID=7.0</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PRETTY_NAME=</varname></term> + + <listitem><para>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 + <literal>PRETTY_NAME="GNU/Linux"</literal>. Example: + <literal>PRETTY_NAME="BLAG 210k + (Spartakus)"</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ANSI_COLOR=</varname></term> + + <listitem><para>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: <literal>ANSI_COLOR="0;31"</literal> for red, or + <literal>ANSI_COLOR="1;34"</literal> for light + blue.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPE_NAME=</varname></term> + + <listitem><para>A CPE name for the operating system, in URI + binding syntax, following the + <ulink url="http://scap.nist.gov/specifications/cpe/">Common + Platform Enumeration Specification</ulink> as proposed by the + NIST. This field is optional. Example: + <literal>CPE_NAME="cpe:/o:blagblagblag:blag:210k"</literal> + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>HOME_URL=</varname></term> + <term><varname>SUPPORT_URL=</varname></term> + <term><varname>BUG_REPORT_URL=</varname></term> + <term><varname>PRIVACY_POLICY_URL=</varname></term> + + <listitem><para>Links to resources on the Internet related the + operating system. <varname>HOME_URL=</varname> should refer to + the homepage of the operating system, or alternatively some + homepage of the specific version of the operating system. + <varname>SUPPORT_URL=</varname> 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. <varname>BUG_REPORT_URL=</varname> 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. + <varname>PRIVACY_POLICY_URL=</varname> 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 + <ulink url="https://tools.ietf.org/html/rfc3986">RFC3986 + format</ulink>, and should be <literal>http:</literal> or + <literal>https:</literal> URLs, and possibly + <literal>mailto:</literal> or <literal>tel:</literal>. 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: + <literal>HOME_URL="https://www.blagblagblag.org/"</literal> and + <literal>BUG_REPORT_URL="https://blag.fsf.org/"</literal></para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>BUILD_ID=</varname></term> + + <listitem><para>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: <literal>BUILD_ID="2013-03-20.3"</literal> + or <literal>BUILD_ID=201303203</literal>. + + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VARIANT=</varname></term> + + <listitem><para> + 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: + <literal>VARIANT="Server Edition"</literal>, + <literal>VARIANT="Smart Refrigerator Edition"</literal> + Note: this field is for display purposes only. The + <varname>VARIANT_ID</varname> field should be used for making + programmatic decisions. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VARIANT_ID=</varname></term> + + <listitem><para> + 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: + <literal>VARIANT_ID=server</literal>, + <literal>VARIANT_ID=embedded</literal> + </para></listitem> + </varlistentry> + + </variablelist> + + <para>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 + <varname>ID</varname> and <varname>VERSION_ID</varname> fields, + possibly with <varname>ID_LIKE</varname> as fallback for + <varname>ID</varname>. When looking for an OS identification + string for presentation to the user use the + <varname>PRETTY_NAME</varname> field.</para> + + <para>Note that operating system vendors may choose not to provide + version information, for example to accommodate for rolling + releases. In this case, <varname>VERSION</varname> and + <varname>VERSION_ID</varname> may be unset. Applications should + not rely on these fields to be set.</para> + + <para>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: + <literal>DEBIAN_BTS="debbugs://bugs.gnewsense.org/"</literal></para> + </refsect1> + + <refsect1> + <title>Example</title> + + <programlisting>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/"</programlisting> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |