man: add a new page with a general description of common syntax
We have a common parser, but for the user it might be completely unobvious that the same general rules apply to all those files. Let's add a page about the basic syntax so that the more specific pages don't have to repeat those details.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
parent
4298e26176
commit
0f943ae4ea
|
|
@ -48,7 +48,10 @@
|
|||
<title>Description</title>
|
||||
|
||||
<para>These files configure various parameters of
|
||||
<citerefentry><refentrytitle>systemd-journal-remote.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
|
||||
<citerefentry><refentrytitle>systemd-journal-remote.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
|
||||
See
|
||||
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
for a general description of the syntax.</para>
|
||||
</refsect1>
|
||||
|
||||
<xi:include href="standard-conf.xml" xpointer="main-conf" />
|
||||
|
|
|
|||
|
|
@ -48,7 +48,10 @@
|
|||
<title>Description</title>
|
||||
|
||||
<para>These files configure various parameters of
|
||||
<citerefentry><refentrytitle>systemd-journal-upload.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
|
||||
<citerefentry><refentrytitle>systemd-journal-upload.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
|
||||
See
|
||||
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
for a general description of the syntax.</para>
|
||||
</refsect1>
|
||||
|
||||
<xi:include href="standard-conf.xml" xpointer="main-conf" />
|
||||
|
|
|
|||
|
|
@ -47,9 +47,11 @@
|
|||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>These files configure various parameters of the systemd
|
||||
journal service,
|
||||
<citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
|
||||
<para>These files configure various parameters of the systemd journal service,
|
||||
<citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
|
||||
See
|
||||
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
for a general description of the syntax.</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
|
|
|
|||
|
|
@ -50,10 +50,10 @@
|
|||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>These files configure various parameters of the systemd
|
||||
login manager,
|
||||
<citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
|
||||
</para>
|
||||
<para>These files configure various parameters of the systemd login manager,
|
||||
<citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. See
|
||||
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
for a general description of the syntax.</para>
|
||||
</refsect1>
|
||||
|
||||
<xi:include href="standard-conf.xml" xpointer="main-conf" />
|
||||
|
|
|
|||
|
|
@ -699,6 +699,7 @@ manpages = [
|
|||
['systemd.socket', '5', [], ''],
|
||||
['systemd.special', '7', [], ''],
|
||||
['systemd.swap', '5', [], ''],
|
||||
['systemd.syntax', '7', [], ''],
|
||||
['systemd.target', '5', [], ''],
|
||||
['systemd.time', '7', [], ''],
|
||||
['systemd.timer', '5', [], ''],
|
||||
|
|
|
|||
|
|
@ -109,7 +109,10 @@
|
|||
<citerefentry><refentrytitle>systemd-sleep</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||||
when
|
||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||
attempts to suspend or hibernate the machine.</para>
|
||||
attempts to suspend or hibernate the machine.
|
||||
See
|
||||
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
for a general description of the syntax.</para>
|
||||
</refsect1>
|
||||
|
||||
<xi:include href="standard-conf.xml" xpointer="main-conf" />
|
||||
|
|
|
|||
|
|
@ -63,7 +63,9 @@
|
|||
<filename>user.conf</filename> and the files in
|
||||
<filename>user.conf.d</filename> directories. These configuration
|
||||
files contain a few settings controlling basic manager
|
||||
operations.</para>
|
||||
operations. See
|
||||
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
for a general description of the syntax.</para>
|
||||
</refsect1>
|
||||
|
||||
<xi:include href="standard-conf.xml" xpointer="main-conf" />
|
||||
|
|
|
|||
|
|
@ -0,0 +1,107 @@
|
|||
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
|
||||
<!ENTITY % entities SYSTEM "custom-entities.ent" >
|
||||
%entities;
|
||||
]>
|
||||
|
||||
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
|
||||
|
||||
<refentry id="systemd.syntax">
|
||||
|
||||
<refentryinfo>
|
||||
<title>systemd.syntax</title>
|
||||
<productname>systemd</productname>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
<contrib>A. U. Thor</contrib>
|
||||
<firstname>Zbigniew</firstname>
|
||||
<surname>Jędrzejewski-Szmek</surname>
|
||||
<email>zbyszek@in.waw.pl</email>
|
||||
</author>
|
||||
</authorgroup>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>systemd.syntax</refentrytitle>
|
||||
<manvolnum>7</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>systemd.syntax</refname>
|
||||
<refpurpose>General syntax of systemd configuration files</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1>
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>This page describes the basic principles of configuration files used by
|
||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||
and related programs for:
|
||||
<itemizedlist>
|
||||
<listitem><para>systemd unit files, see
|
||||
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry></para></listitem>
|
||||
|
||||
<listitem><para>daemon config files, see
|
||||
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd-user.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>journal-remote.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>journal-upload.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>systemd-sleep.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>The syntax is inspired by
|
||||
<ulink url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG Desktop Entry Specification</ulink>
|
||||
<filename>.desktop</filename> files, which are in turn inspired by Microsoft Windows
|
||||
<filename>.ini</filename> files.
|
||||
</para>
|
||||
|
||||
<para>Each file is a plain text file divided into sections, with configuration entries in the
|
||||
style <replaceable>key</replaceable>=<replaceable>value</replaceable>.
|
||||
Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are
|
||||
ignored, which may be used for commenting.</para>
|
||||
|
||||
<para>Lines ending in a backslash are concatenated with the following line while reading and the
|
||||
backslash is replaced by a space character. This may be used to wrap long lines. The limit on
|
||||
line length is very large (currently 1 MB), but it is recommended to avoid such long lines and
|
||||
use multiple directives, variable substitution, or other mechanism as appropriate for the given
|
||||
file type.</para>
|
||||
|
||||
<example><programlisting>[Section A]
|
||||
KeyOne=value 1
|
||||
KeyTwo=value 2
|
||||
|
||||
# a comment
|
||||
|
||||
[Section B]
|
||||
Setting="something" "some thing" "…"
|
||||
KeyTwo=value 2 \
|
||||
value 2 continued
|
||||
</programlisting></example>
|
||||
|
||||
<para>Various settings are allowed to be specified more than once, in which case the
|
||||
interpretation depends on the setting. Often, multiple settings form a list, and setting to an
|
||||
empty value "resets", which means that previous assignments are ignored. When this is allowed,
|
||||
it is mentioned in the description of the setting. Note that using multiple assignments to the
|
||||
same value makes the file incompatible with parsers for the XDG <filename>.desktop</filename>
|
||||
file format.</para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
|
|
@ -83,18 +83,13 @@
|
|||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>A unit configuration file encodes information about a
|
||||
service, a socket, a device, a mount point, an automount point, a
|
||||
swap file or partition, a start-up target, a watched file system
|
||||
path, a timer controlled and supervised by
|
||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||
a resource management slice or
|
||||
a group of externally created processes. The syntax is inspired by
|
||||
<ulink
|
||||
url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
|
||||
Desktop Entry Specification</ulink> <filename>.desktop</filename>
|
||||
files, which are in turn inspired by Microsoft Windows
|
||||
<filename>.ini</filename> files.</para>
|
||||
<para>A unit file is a plain text ini-style file that encodes information about a service, a
|
||||
socket, a device, a mount point, an automount point, a swap file or partition, a start-up
|
||||
target, a watched file system path, a timer controlled and supervised by
|
||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, a
|
||||
resource management slice or a group of externally created processes. See
|
||||
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
for a general description of the syntax.</para>
|
||||
|
||||
<para>This man page lists the common configuration options of all
|
||||
the unit types. These options need to be configured in the [Unit]
|
||||
|
|
@ -117,15 +112,6 @@
|
|||
<citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
|
||||
</para>
|
||||
|
||||
<para>Various settings are allowed to be specified more than once,
|
||||
in which case the interpretation depends on the setting. Often,
|
||||
multiple settings form a list, and setting to an empty value
|
||||
"resets", which means that previous assignments are ignored. When
|
||||
this is allowed, it is mentioned in the description of the
|
||||
setting. Note that using multiple assignments to the same value
|
||||
makes the unit file incompatible with parsers for the XDG
|
||||
<filename>.desktop</filename> file format.</para>
|
||||
|
||||
<para>Unit files are loaded from a set of paths determined during
|
||||
compilation, described in the next section.</para>
|
||||
|
||||
|
|
@ -154,11 +140,6 @@
|
|||
<literal>w</literal>, <literal>ms</literal>, <literal>us</literal>. For details see
|
||||
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
|
||||
|
||||
<para>Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are
|
||||
ignored. This may be used for commenting. Lines ending in a backslash are concatenated with the
|
||||
following line while reading and the backslash is replaced by a space character. This may be
|
||||
used to wrap long lines.</para>
|
||||
|
||||
<para>Units can be aliased (have an alternative name), by creating a symlink from the new name
|
||||
to the existing name in one of the unit search paths. For example,
|
||||
<filename>systemd-networkd.service</filename> has the alias
|
||||
|
|
|
|||
|
|
@ -47,9 +47,9 @@
|
|||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>These configuration files control NTP network time
|
||||
synchronization.</para>
|
||||
|
||||
<para>These configuration files control NTP network time synchronization. See
|
||||
<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
for a general description of the syntax.</para>
|
||||
</refsect1>
|
||||
|
||||
<xi:include href="standard-conf.xml" xpointer="main-conf" />
|
||||
|
|
|
|||
Loading…
Reference in New Issue