From 0f943ae4ea36148c0e2c4a69735410c8e48648d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 16 Apr 2018 17:09:58 +0200 Subject: [PATCH] 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. --- man/journal-remote.conf.xml | 5 +- man/journal-upload.conf.xml | 5 +- man/journald.conf.xml | 8 ++- man/logind.conf.xml | 8 +-- man/rules/meson.build | 1 + man/systemd-sleep.conf.xml | 5 +- man/systemd-system.conf.xml | 4 +- man/systemd.syntax.xml | 107 ++++++++++++++++++++++++++++++++++++ man/systemd.unit.xml | 33 +++-------- man/timesyncd.conf.xml | 6 +- 10 files changed, 142 insertions(+), 40 deletions(-) create mode 100644 man/systemd.syntax.xml diff --git a/man/journal-remote.conf.xml b/man/journal-remote.conf.xml index b21d38c5b8..24ade09023 100644 --- a/man/journal-remote.conf.xml +++ b/man/journal-remote.conf.xml @@ -48,7 +48,10 @@ Description These files configure various parameters of - systemd-journal-remote.service8. + systemd-journal-remote.service8. + See + systemd.syntax5 + for a general description of the syntax. diff --git a/man/journal-upload.conf.xml b/man/journal-upload.conf.xml index 846031d237..8e241370db 100644 --- a/man/journal-upload.conf.xml +++ b/man/journal-upload.conf.xml @@ -48,7 +48,10 @@ Description These files configure various parameters of - systemd-journal-upload.service8. + systemd-journal-upload.service8. + See + systemd.syntax5 + for a general description of the syntax. diff --git a/man/journald.conf.xml b/man/journald.conf.xml index a4ae1af170..96422a3a2f 100644 --- a/man/journald.conf.xml +++ b/man/journald.conf.xml @@ -47,9 +47,11 @@ Description - These files configure various parameters of the systemd - journal service, - systemd-journald.service8. + These files configure various parameters of the systemd journal service, + systemd-journald.service8. + See + systemd.syntax5 + for a general description of the syntax. diff --git a/man/logind.conf.xml b/man/logind.conf.xml index 6118aa5e3d..9e21c0b218 100644 --- a/man/logind.conf.xml +++ b/man/logind.conf.xml @@ -50,10 +50,10 @@ Description - These files configure various parameters of the systemd - login manager, - systemd-logind.service8. - + These files configure various parameters of the systemd login manager, + systemd-logind.service8. See + systemd.syntax5 + for a general description of the syntax. diff --git a/man/rules/meson.build b/man/rules/meson.build index 173ed8f976..9b57f10cc0 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -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', [], ''], diff --git a/man/systemd-sleep.conf.xml b/man/systemd-sleep.conf.xml index 3652c2066b..84e52d3bd8 100644 --- a/man/systemd-sleep.conf.xml +++ b/man/systemd-sleep.conf.xml @@ -109,7 +109,10 @@ systemd-sleep8 when systemd1 - attempts to suspend or hibernate the machine. + attempts to suspend or hibernate the machine. + See + systemd.syntax5 + for a general description of the syntax. diff --git a/man/systemd-system.conf.xml b/man/systemd-system.conf.xml index b31eb11f8c..36bd4aaee5 100644 --- a/man/systemd-system.conf.xml +++ b/man/systemd-system.conf.xml @@ -63,7 +63,9 @@ user.conf and the files in user.conf.d directories. These configuration files contain a few settings controlling basic manager - operations. + operations. See + systemd.syntax5 + for a general description of the syntax. diff --git a/man/systemd.syntax.xml b/man/systemd.syntax.xml new file mode 100644 index 0000000000..bafe817a9b --- /dev/null +++ b/man/systemd.syntax.xml @@ -0,0 +1,107 @@ + + +%entities; +]> + + + + + + + systemd.syntax + systemd + + + + A. U. Thor + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + systemd.syntax + 7 + + + + systemd.syntax + General syntax of systemd configuration files + + + + Introduction + + This page describes the basic principles of configuration files used by + systemd1 + and related programs for: + + systemd unit files, see + systemd.unit5, + systemd.service5, + systemd.socket5, + systemd.device5, + systemd.mount5, + systemd.automount5, + systemd.swap5, + systemd.target5, + systemd.path5, + systemd.timer5, + systemd.slice5, + systemd.scope5 + + daemon config files, see + systemd-system.conf5, + systemd-user.conf5, + logind.conf5, + journald.conf5, + journal-remote.conf5, + journal-upload.conf5, + systemd-sleep.conf5, + timesyncd.conf5 + + + + + The syntax is inspired by + XDG Desktop Entry Specification + .desktop files, which are in turn inspired by Microsoft Windows + .ini files. + + + Each file is a plain text file divided into sections, with configuration entries in the + style key=value. + Empty lines and lines starting with # or ; are + ignored, which 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. 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. + + [Section A] +KeyOne=value 1 +KeyTwo=value 2 + +# a comment + +[Section B] +Setting="something" "some thing" "…" +KeyTwo=value 2 \ + value 2 continued + + + 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 .desktop + file format. + + + diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 2baf9d17e8..5ea615d998 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -83,18 +83,13 @@ Description - A unit configuration file encodes information about a - service, a socket, a device, a mount point, an automount point, a - swap file or partition, a start-up target, a watched file system - path, a timer controlled and supervised by - systemd1, - a resource management slice or - a group of externally created processes. The syntax is inspired by - XDG - Desktop Entry Specification .desktop - files, which are in turn inspired by Microsoft Windows - .ini files. + 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 + systemd1, a + resource management slice or a group of externally created processes. See + systemd.syntax5 + for a general description of the syntax. 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 @@ systemd.scope5. - Various settings are allowed to be specified more than once, - in which case the interpretation depends on the setting. Often, - multiple settings form a list, and setting to an empty value - "resets", which means that previous assignments are ignored. When - this is allowed, it is mentioned in the description of the - setting. Note that using multiple assignments to the same value - makes the unit file incompatible with parsers for the XDG - .desktop file format. - Unit files are loaded from a set of paths determined during compilation, described in the next section. @@ -154,11 +140,6 @@ w, ms, us. For details see systemd.time7. - Empty lines and lines starting with # or ; are - ignored. This may be used for commenting. Lines ending in a backslash are concatenated with the - following line while reading and the backslash is replaced by a space character. This may be - used to wrap long lines. - 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, systemd-networkd.service has the alias diff --git a/man/timesyncd.conf.xml b/man/timesyncd.conf.xml index c6dbb1ef4e..9292373bd9 100644 --- a/man/timesyncd.conf.xml +++ b/man/timesyncd.conf.xml @@ -47,9 +47,9 @@ Description - These configuration files control NTP network time - synchronization. - + These configuration files control NTP network time synchronization. See + systemd.syntax5 + for a general description of the syntax.