shaba/systemd-stable
1
1
Fork 0
mirror of https://github.com/systemd/systemd-stable.git synced 2024-12-22 13:33:56 +03:00
Code

man: add a new page with a general description of common syntax

Browse Source 
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 2018-04-16 17:09:58 +02:00
parent 4298e26176
commit 0f943ae4ea
10 changed files with 142 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
man/journal-remote.conf.xml
View File

@ -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" />

5
man/journal-upload.conf.xml
View File

@ -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" />

8
man/journald.conf.xml
View File

@ -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>

8
man/logind.conf.xml
View File

@ -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" />

1
man/rules/meson.build
View File

@ -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', [], ''],

5
man/systemd-sleep.conf.xml
View File

@ -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" />

4
man/systemd-system.conf.xml
View File

@ -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" />

107
man/systemd.syntax.xml Normal file
View File

@ -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>

33
man/systemd.unit.xml
View File

@ -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

6
man/timesyncd.conf.xml
View File

@ -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" />