Skip to content

Commit c9a58e9

Browse files
Tachi107Tachi107
committed
docs: refresh with make -C man download-docs
1 parent 915e764 commit c9a58e9

5 files changed

Lines changed: 245 additions & 141 deletions

File tree

‎man/custom-html.xsl‎

Lines changed: 29 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,5 @@
11
<?xml version='1.0'?> <!--*-nxml-*-->
2-
3-
<!--
4-
SPDX-License-Identifier: LGPL-2.1+
5-
6-
This file is part of systemd.
7-
8-
Copyright 2011 Lennart Poettering
9-
10-
systemd is free software; you can redistribute it and/or modify it
11-
under the terms of the GNU Lesser General Public License as published by
12-
the Free Software Foundation; either version 2.1 of the License, or
13-
(at your option) any later version.
14-
15-
systemd is distributed in the hope that it will be useful, but
16-
WITHOUT ANY WARRANTY; without even the implied warranty of
17-
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18-
Lesser General Public License for more details.
19-
20-
You should have received a copy of the GNU Lesser General Public License
21-
along with systemd; If not, see <http://www.gnu.org/licenses/>.
22-
-->
2+
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
233

244
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
255

@@ -39,7 +19,8 @@
3919
<xsl:template match="citerefentry[not(@project)]">
4020
<a>
4121
<xsl:attribute name="href">
42-
<xsl:value-of select="refentrytitle"/><xsl:text>.html#</xsl:text>
22+
<xsl:value-of select="refentrytitle"/>
23+
<xsl:text>.html#</xsl:text>
4324
<xsl:value-of select="refentrytitle/@target"/>
4425
</xsl:attribute>
4526
<xsl:call-template name="inline.charseq"/>
@@ -49,7 +30,7 @@
4930
<xsl:template match="citerefentry[@project='man-pages'] | citerefentry[manvolnum='2'] | citerefentry[manvolnum='4']">
5031
<a>
5132
<xsl:attribute name="href">
52-
<xsl:text>http://man7.org/linux/man-pages/man</xsl:text>
33+
<xsl:text>https://man7.org/linux/man-pages/man</xsl:text>
5334
<xsl:value-of select="manvolnum"/>
5435
<xsl:text>/</xsl:text>
5536
<xsl:value-of select="refentrytitle"/>
@@ -112,6 +93,21 @@
11293
</a>
11394
</xsl:template>
11495

96+
<xsl:template match="citerefentry[@project='debian']">
97+
<a>
98+
<xsl:attribute name="href">
99+
<xsl:text>https://manpages.debian.org/unstable/</xsl:text>
100+
<xsl:value-of select="refentrytitle"/>
101+
<xsl:text>/</xsl:text>
102+
<xsl:value-of select="refentrytitle"/>
103+
<xsl:text>.</xsl:text>
104+
<xsl:value-of select="manvolnum"/>
105+
<xsl:text>.en.html</xsl:text>
106+
</xsl:attribute>
107+
<xsl:call-template name="inline.charseq"/>
108+
</a>
109+
</xsl:template>
110+
115111
<xsl:template match="citerefentry[@project='freebsd']">
116112
<a>
117113
<xsl:attribute name="href">
@@ -128,7 +124,7 @@
128124
<xsl:template match="citerefentry[@project='dbus']">
129125
<a>
130126
<xsl:attribute name="href">
131-
<xsl:text>http://dbus.freedesktop.org/doc/</xsl:text>
127+
<xsl:text>https://dbus.freedesktop.org/doc/</xsl:text>
132128
<xsl:value-of select="refentrytitle"/>
133129
<xsl:text>.</xsl:text>
134130
<xsl:value-of select="manvolnum"/>
@@ -138,6 +134,15 @@
138134
</a>
139135
</xsl:template>
140136

137+
<xsl:template match="citerefentry[@project='url']">
138+
<a>
139+
<xsl:attribute name="href">
140+
<xsl:value-of select="refentrytitle/@url"/>
141+
</xsl:attribute>
142+
<xsl:call-template name="inline.charseq"/>
143+
</a>
144+
</xsl:template>
145+
141146
<!--
142147
- helper template to do conflict resolution between various headings with the same inferred ID attribute/tag from the headerlink template
143148
- this conflict resolution is necessary to prevent malformed HTML output (multiple ID attributes with the same value)

‎man/custom-man.xsl‎

Lines changed: 1 addition & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,7 @@
11
<?xml version='1.0'?> <!--*-nxml-*-->
22

33
<!--
4-
SPDX-License-Identifier: LGPL-2.1+
5-
6-
This file is part of systemd.
7-
8-
Copyright 2013 Zbigniew Jędrzejewski-Szmek
9-
10-
systemd is free software; you can redistribute it and/or modify it
11-
under the terms of the GNU Lesser General Public License as published by
12-
the Free Software Foundation; either version 2.1 of the License, or
13-
(at your option) any later version.
14-
15-
systemd is distributed in the hope that it will be useful, but
16-
WITHOUT ANY WARRANTY; without even the implied warranty of
17-
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18-
Lesser General Public License for more details.
19-
20-
You should have received a copy of the GNU Lesser General Public License
21-
along with systemd; If not, see <http://www.gnu.org/licenses/>.
4+
SPDX-License-Identifier: LGPL-2.1-or-later
225
-->
236

247
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

‎man/standard-options.xml‎

Lines changed: 47 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,7 @@
1-
<?xml version="1.0"?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2-
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3-
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4-
5-
<!--
6-
SPDX-License-Identifier: LGPL-2.1+
7-
8-
This file is part of systemd.
9-
10-
Copyright 2014 Zbigniew Jędrzejewski-Szmek
11-
12-
systemd is free software; you can redistribute it and/or modify it
13-
under the terms of the GNU Lesser General Public License as published by
14-
the Free Software Foundation; either version 2.1 of the License, or
15-
(at your option) any later version.
16-
17-
systemd is distributed in the hope that it will be useful, but
18-
WITHOUT ANY WARRANTY; without even the implied warranty of
19-
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20-
Lesser General Public License for more details.
21-
22-
You should have received a copy of the GNU Lesser General Public License
23-
along with systemd; If not, see <http://www.gnu.org/licenses/>.
24-
-->
1+
<?xml version="1.0"?>
2+
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3+
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4+
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
255

266
<variablelist>
277
<varlistentry id='help'>
@@ -55,6 +35,15 @@
5535
<listitem><para>Do not query the user for authentication for privileged operations.</para></listitem>
5636
</varlistentry>
5737

38+
<varlistentry id='legend'>
39+
<term><option>--legend=</option><replaceable>BOOL</replaceable></term>
40+
41+
<listitem>
42+
<para>Enable or disable printing of the legend, i.e. column headers and the footer with hints. The
43+
legend is printed by default, unless disabled with <option>--quiet</option> or similar.</para>
44+
</listitem>
45+
</varlistentry>
46+
5847
<varlistentry id='no-legend'>
5948
<term><option>--no-legend</option></term>
6049

@@ -63,4 +52,38 @@
6352
footer with hints.</para>
6453
</listitem>
6554
</varlistentry>
55+
56+
<varlistentry id='cat-config'>
57+
<term><option>--cat-config</option></term>
58+
59+
<listitem>
60+
<para>Copy the contents of config files to standard output.
61+
Before each file, the filename is printed as a comment.</para>
62+
</listitem>
63+
</varlistentry>
64+
65+
<varlistentry id='json'>
66+
<term><option>--json=</option><replaceable>MODE</replaceable></term>
67+
68+
<listitem><para>Shows output formatted as JSON. Expects one of <literal>short</literal> (for the
69+
shortest possible output without any redundant whitespace or line breaks), <literal>pretty</literal>
70+
(for a pretty version of the same, with indentation and line breaks) or <literal>off</literal> (to turn
71+
off JSON output, the default).</para></listitem>
72+
</varlistentry>
73+
74+
<varlistentry id='signal'>
75+
<term><option>-s</option></term>
76+
<term><option>--signal=</option></term>
77+
78+
<listitem>
79+
<para>When used with <command>kill</command>, choose which signal to send to selected processes. Must
80+
be one of the well-known signal specifiers such as <constant>SIGTERM</constant>,
81+
<constant>SIGINT</constant> or <constant>SIGSTOP</constant>. If omitted, defaults to
82+
<option>SIGTERM</option>.</para>
83+
84+
<para>The special value <literal>help</literal> will list the known values and the program will exit
85+
immediately, and the special value <literal>list</literal> will list known values along with the
86+
numerical signal numbers and the program will exit immediately.</para>
87+
</listitem>
88+
</varlistentry>
6689
</variablelist>

‎man/systemd-sysusers.xml‎

Lines changed: 91 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,14 @@
11
<?xml version='1.0'?> <!--*-nxml-*-->
2-
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2+
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
33
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4-
5-
<!--
6-
SPDX-License-Identifier: LGPL-2.1+
7-
8-
This file is part of systemd.
9-
10-
Copyright 2014 Lennart Poettering
11-
12-
systemd is free software; you can redistribute it and/or modify it
13-
under the terms of the GNU Lesser General Public License as published by
14-
the Free Software Foundation; either version 2.1 of the License, or
15-
(at your option) any later version.
16-
17-
systemd is distributed in the hope that it will be useful, but
18-
WITHOUT ANY WARRANTY; without even the implied warranty of
19-
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20-
Lesser General Public License for more details.
21-
22-
You should have received a copy of the GNU Lesser General Public License
23-
along with systemd; If not, see <http://www.gnu.org/licenses/>.
24-
-->
4+
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
255

266
<refentry id="systemd-sysusers"
277
xmlns:xi="http://www.w3.org/2001/XInclude">
288

299
<refentryinfo>
3010
<title>systemd-sysusers</title>
3111
<productname>systemd</productname>
32-
33-
<authorgroup>
34-
<author>
35-
<contrib>Developer</contrib>
36-
<firstname>Lennart</firstname>
37-
<surname>Poettering</surname>
38-
<email>lennart@poettering.net</email>
39-
</author>
40-
</authorgroup>
4112
</refentryinfo>
4213

4314
<refmeta>
@@ -97,9 +68,22 @@
9768
paths. </para></listitem>
9869
</varlistentry>
9970

71+
<varlistentry>
72+
<term><option>--image=<replaceable>image</replaceable></option></term>
73+
74+
<listitem><para>Takes a path to a disk image file or block device node. If specified all operations
75+
are applied to file system in the indicated disk image. This is similar to <option>--root=</option>
76+
but operates on file systems stored in disk images or block devices. The disk image should either
77+
contain just a file system or a set of file systems within a GPT partition table, following the
78+
<ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions
79+
Specification</ulink>. For further information on supported disk images, see
80+
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
81+
switch of the same name.</para></listitem>
82+
</varlistentry>
83+
10084
<varlistentry>
10185
<term><option>--replace=<replaceable>PATH</replaceable></option></term>
102-
<listitem><para>When this option is given, one ore more positional arguments
86+
<listitem><para>When this option is given, one or more positional arguments
10387
must be specified. All configuration files found in the directories listed in
10488
<citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
10589
will be read, and the configuration given on the command line will be
@@ -124,23 +108,93 @@
124108
placing <filename>/etc/sysusers.d/radvd.conf</filename> or even
125109
<filename>/etc/sysusers.d/00-overrides.conf</filename>.</para>
126110

127-
<para>Note that this is the expanded from, and when used in a package, this
111+
<para>Note that this is the expanded form, and when used in a package, this
128112
would be written using a macro with "radvd" and a file containing the
129113
configuration line as arguments.</para>
130114
</example>
131115
</listitem>
132116
</varlistentry>
133117

118+
<varlistentry>
119+
<term><option>--dry-run</option></term>
120+
<listitem><para>Process the configuration and figure out what entries would be created, but don't
121+
actually write anything.</para></listitem>
122+
</varlistentry>
123+
134124
<varlistentry>
135125
<term><option>--inline</option></term>
136126
<listitem><para>Treat each positional argument as a separate configuration
137127
line instead of a file name.</para></listitem>
138128
</varlistentry>
139129

130+
<xi:include href="standard-options.xml" xpointer="cat-config" />
131+
<xi:include href="standard-options.xml" xpointer="no-pager" />
140132
<xi:include href="standard-options.xml" xpointer="help" />
141133
<xi:include href="standard-options.xml" xpointer="version" />
142134
</variablelist>
135+
</refsect1>
136+
137+
<refsect1>
138+
<title>Credentials</title>
139+
140+
<para><command>systemd-sysusers</command> supports the service credentials logic as implemented by
141+
<varname>LoadCredential=</varname>/<varname>SetCredential=</varname> (see
142+
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
143+
details). The following credentials are used when passed in:</para>
144+
145+
<variablelist>
146+
<varlistentry>
147+
<term><literal>passwd.hashed-password.<replaceable>user</replaceable></literal></term>
148+
<listitem><para>A UNIX hashed password string to use for the specified user, when creating an entry
149+
for it. This is particularly useful for the <literal>root</literal> user as it allows provisioning
150+
the default root password to use via a unit file drop-in or from a container manager passing in this
151+
credential. Note that setting this credential has no effect if the specified user account already
152+
exists. This credential is hence primarily useful in first boot scenarios or systems that are fully
153+
stateless and come up with an empty <filename>/etc/</filename> on every boot.</para></listitem>
154+
</varlistentry>
155+
156+
<varlistentry>
157+
<term><literal>passwd.plaintext-password.<replaceable>user</replaceable></literal></term>
158+
159+
<listitem><para>Similar to <literal>passwd.hashed-password.<replaceable>user</replaceable></literal>
160+
but expect a literal, plaintext password, which is then automatically hashed before used for the user
161+
account. If both the hashed and the plaintext credential are specified for the same user the
162+
former takes precedence. It's generally recommended to specify the hashed version; however in test
163+
environments with weaker requirements on security it might be easier to pass passwords in plaintext
164+
instead.</para></listitem>
165+
</varlistentry>
166+
167+
<varlistentry>
168+
<term><literal>passwd.shell.<replaceable>user</replaceable></literal></term>
169+
170+
<listitem><para>Specifies the shell binary to use for the specified account when creating it.</para></listitem>
171+
</varlistentry>
172+
173+
<varlistentry>
174+
<term><literal>sysusers.extra</literal></term>
175+
176+
<listitem><para>The contents of this credential may contain additional lines to operate on. The
177+
credential contents should follow the same format as any other <filename>sysusers.d/</filename>
178+
drop-in. If this credential is passed it is processed after all of the drop-in files read from the
179+
file system.</para></listitem>
180+
</varlistentry>
181+
</variablelist>
182+
183+
<para>Note that by default the <filename>systemd-sysusers.service</filename> unit file is set up to
184+
inherit the <literal>passwd.hashed-password.root</literal>,
185+
<literal>passwd.plaintext-password.root</literal>, <literal>passwd.shell.root</literal> and
186+
<literal>sysusers.extra</literal> credentials from the service manager. Thus, when invoking a container
187+
with an unpopulated <filename>/etc/</filename> for the first time it is possible to configure the root
188+
user's password to be <literal>systemd</literal> like this:</para>
189+
190+
<para><programlisting># systemd-nspawn --image=… --set-credential=passwd.hashed-password.root:'$y$j9T$yAuRJu1o5HioZAGDYPU5d.$F64ni6J2y2nNQve90M/p0ZP0ECP/qqzipNyaY9fjGpC' …</programlisting></para>
191+
192+
<para>Note again that the data specified in this credential is consulted only when creating an account
193+
for the first time, it may not be used for changing the password or shell of an account that already
194+
exists.</para>
143195

196+
<para>Use <citerefentry project='man-pages'><refentrytitle>mkpasswd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
197+
for generating UNIX password hashes from the command line.</para>
144198
</refsect1>
145199

146200
<refsect1>
@@ -154,7 +208,10 @@
154208
<title>See Also</title>
155209
<para>
156210
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
157-
<citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
211+
<citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
212+
<ulink url="https://systemd.io/UIDS-GIDS">Users, Groups, UIDs and GIDs on systemd systems</ulink>,
213+
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
214+
<citerefentry project='man-pages'><refentrytitle>mkpasswd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
158215
</para>
159216
</refsect1>
160217

0 commit comments

Comments
 (0)