X Tutup
Skip to content

Commit 49dbfa7

Browse files
poetteringpoettering
committed
units: introduce new Documentation= field and make use of it everywhere
This should help making the boot process a bit easier to explore and understand for the administrator. The simple idea is that "systemctl status" now shows a link to documentation alongside the other status and decriptionary information of a service. This patch adds the necessary fields to all our shipped units if we have proper documentation for them.
1 parent a223b32 commit 49dbfa7

File tree

91 files changed

+312
-107
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

91 files changed

+312
-107
lines changed

‎man/systemd.special.xml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,14 +49,17 @@
4949

5050
<refsynopsisdiv>
5151
<para><filename>basic.target</filename>,
52+
<filename>bluetooth.target</filename>,
5253
<filename>ctrl-alt-del.target</filename>,
54+
<filename>cryptsetup.target</filename>,
5355
<filename>dbus.service</filename>,
5456
<filename>dbus.socket</filename>,
5557
<filename>default.target</filename>,
5658
<filename>display-manager.service</filename>,
5759
<filename>emergency.target</filename>,
5860
<filename>exit.service</filename>,
5961
<filename>final.service</filename>,
62+
<filename>getty.target</filename>,
6063
<filename>graphical.target</filename>,
6164
<filename>hibernate.target</filename>,
6265
<filename>http-daemon.target</filename>,
@@ -69,7 +72,9 @@
6972
<filename>multi-user.target</filename>,
7073
<filename>network.target</filename>,
7174
<filename>nss-lookup.target</filename>,
75+
<filename>nss-user-lookup.target</filename>,
7276
<filename>poweroff.target</filename>,
77+
<filename>printer.target</filename>,
7378
<filename>reboot.target</filename>,
7479
<filename>remote-fs.target</filename>,
7580
<filename>remote-fs-pre.target</filename>,
@@ -82,7 +87,9 @@
8287
<filename>shutdown.target</filename>,
8388
<filename>sigpwr.target</filename>,
8489
<filename>sleep.target</filename>,
90+
<filename>smartcard.target</filename>,
8591
<filename>sockets.target</filename>,
92+
<filename>sound.target</filename>,
8693
<filename>suspend.target</filename>,
8794
<filename>swap.target</filename>,
8895
<filename>sysinit.target</filename>,
@@ -127,6 +134,16 @@
127134
this unit.</para>
128135
</listitem>
129136
</varlistentry>
137+
<varlistentry>
138+
<term><filename>bluetooth.target</filename></term>
139+
<listitem>
140+
<para>This target is started
141+
automatically as soon as a
142+
bluetooth controller is
143+
plugged in or becomes
144+
available at boot.</para>
145+
</listitem>
146+
</varlistentry>
130147
<varlistentry>
131148
<term><filename>ctrl-alt-del.target</filename></term>
132149
<listitem>
@@ -139,6 +156,15 @@
139156
<filename>reboot.target</filename>.</para>
140157
</listitem>
141158
</varlistentry>
159+
<varlistentry>
160+
<term><filename>cryptsetup.target</filename></term>
161+
<listitem>
162+
<para>A target that pulls in
163+
setup services for all
164+
encrypted block
165+
devices.</para>
166+
</listitem>
167+
</varlistentry>
142168
<varlistentry>
143169
<term><filename>dbus.service</filename></term>
144170
<listitem>
@@ -226,6 +252,15 @@
226252
</para>
227253
</listitem>
228254
</varlistentry>
255+
<varlistentry>
256+
<term><filename>getty.target</filename></term>
257+
<listitem>
258+
<para>A special target unit
259+
that pulls in all local TTY
260+
<filename>getty</filename> instances.
261+
</para>
262+
</listitem>
263+
</varlistentry>
229264
<varlistentry>
230265
<term><filename>graphical.target</filename></term>
231266
<listitem>
@@ -442,6 +477,16 @@
442477
unit, for compatibility with SysV.</para>
443478
</listitem>
444479
</varlistentry>
480+
<varlistentry>
481+
<term><filename>printer.target</filename></term>
482+
<listitem>
483+
<para>This target is started
484+
automatically as soon as a
485+
printer is plugged in or
486+
becomes available at
487+
boot.</para>
488+
</listitem>
489+
</varlistentry>
445490
<varlistentry>
446491
<term><filename>reboot.target</filename></term>
447492
<listitem>
@@ -615,6 +660,16 @@
615660
logic.</para>
616661
</listitem>
617662
</varlistentry>
663+
<varlistentry>
664+
<term><filename>smartcard.target</filename></term>
665+
<listitem>
666+
<para>This target is started
667+
automatically as soon as a
668+
smartcard controller is
669+
plugged in or becomes
670+
available at boot.</para>
671+
</listitem>
672+
</varlistentry>
618673
<varlistentry>
619674
<term><filename>sockets.target</filename></term>
620675
<listitem>
@@ -629,6 +684,16 @@
629684
during installation.</para>
630685
</listitem>
631686
</varlistentry>
687+
<varlistentry>
688+
<term><filename>sound.target</filename></term>
689+
<listitem>
690+
<para>This target is started
691+
automatically as soon as a
692+
sound card is plugged in or
693+
becomes available at
694+
boot.</para>
695+
</listitem>
696+
</varlistentry>
632697
<varlistentry>
633698
<term><filename>suspend.target</filename></term>
634699
<listitem>

‎man/systemd.unit.xml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -294,6 +294,23 @@
294294
name.</para></listitem>
295295
</varlistentry>
296296

297+
<varlistentry>
298+
<term><varname>Documentation=</varname></term>
299+
<listitem><para>A space separated list
300+
of URIs referencing documentation for
301+
this unit or its
302+
configuration. Accepted are only URIs
303+
of the types
304+
<literal>http://</literal>,
305+
<literal>https://</literal>,
306+
<literal>file:</literal>,
307+
<literal>info:</literal>,
308+
<literal>man:</literal>. For more
309+
information about the syntax of these
310+
URIs see
311+
<citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem>
312+
</varlistentry>
313+
297314
<varlistentry>
298315
<term><varname>Requires=</varname></term>
299316

‎src/core/dbus-unit.c‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -808,6 +808,7 @@ const BusProperty bus_unit_properties[] = {
808808
{ "PropagateReloadTo", bus_unit_append_dependencies, "as", offsetof(Unit, dependencies[UNIT_PROPAGATE_RELOAD_TO]), true },
809809
{ "PropagateReloadFrom", bus_unit_append_dependencies, "as", offsetof(Unit, dependencies[UNIT_PROPAGATE_RELOAD_FROM]), true },
810810
{ "RequiresMountsFor", bus_property_append_strv, "as", offsetof(Unit, requires_mounts_for), true },
811+
{ "Documentation", bus_property_append_strv, "as", offsetof(Unit, documentation), true },
811812
{ "Description", bus_unit_append_description, "s", 0 },
812813
{ "LoadState", bus_unit_append_load_state, "s", offsetof(Unit, load_state) },
813814
{ "ActiveState", bus_unit_append_active_state, "s", 0 },

‎src/core/dbus-unit.h‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@
8787
" <property name=\"PropagateReloadFrom\" type=\"as\" access=\"read\"/>\n" \
8888
" <property name=\"RequiresMountsFor\" type=\"as\" access=\"read\"/>\n" \
8989
" <property name=\"Description\" type=\"s\" access=\"read\"/>\n" \
90+
" <property name=\"Documentation\" type=\"as\" access=\"read\"/>\n" \
9091
" <property name=\"LoadState\" type=\"s\" access=\"read\"/>\n" \
9192
" <property name=\"ActiveState\" type=\"s\" access=\"read\"/>\n" \
9293
" <property name=\"SubState\" type=\"s\" access=\"read\"/>\n" \

‎src/core/load-fragment-gperf.gperf.m4‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@ $1.ControlGroupPersistent, config_parse_tristate, 0,
9292
)m4_dnl
9393
Unit.Names, config_parse_unit_names, 0, 0
9494
Unit.Description, config_parse_unit_string_printf, 0, offsetof(Unit, description)
95+
Unit.Documentation, config_parse_documentation, 0, offsetof(Unit, documentation)
9596
Unit.Requires, config_parse_unit_deps, UNIT_REQUIRES, 0
9697
Unit.RequiresOverridable, config_parse_unit_deps, UNIT_REQUIRES_OVERRIDABLE, 0
9798
Unit.Requisite, config_parse_unit_deps, UNIT_REQUISITE, 0

‎src/core/load-fragment.c‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2063,6 +2063,43 @@ int config_parse_unit_requires_mounts_for(
20632063
return r;
20642064
}
20652065

2066+
int config_parse_documentation(
2067+
const char *filename,
2068+
unsigned line,
2069+
const char *section,
2070+
const char *lvalue,
2071+
int ltype,
2072+
const char *rvalue,
2073+
void *data,
2074+
void *userdata) {
2075+
2076+
Unit *u = userdata;
2077+
int r;
2078+
char **a, **b;
2079+
2080+
assert(filename);
2081+
assert(lvalue);
2082+
assert(rvalue);
2083+
assert(u);
2084+
2085+
r = config_parse_unit_strv_printf(filename, line, section, lvalue, ltype, rvalue, data, userdata);
2086+
if (r < 0)
2087+
return r;
2088+
2089+
for (a = b = u->documentation; a && *a; a++) {
2090+
2091+
if (is_valid_documentation_url(*a))
2092+
*(b++) = *a;
2093+
else {
2094+
log_error("[%s:%u] Invalid URL, ignoring: %s", filename, line, *a);
2095+
free(*a);
2096+
}
2097+
}
2098+
*b = NULL;
2099+
2100+
return r;
2101+
}
2102+
20662103
#define FOLLOW_MAX 8
20672104

20682105
static int open_follow(char **filename, FILE **_f, Set *names, char **_final) {

‎src/core/load-fragment.h‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ int config_parse_unit_names(const char *filename, unsigned line, const char *sec
3636
int config_parse_unit_string_printf(const char *filename, unsigned line, const char *section, const char *lvalue, int ltype, const char *rvalue, void *data, void *userdata);
3737
int config_parse_unit_strv_printf(const char *filename, unsigned line, const char *section, const char *lvalue, int ltype, const char *rvalue, void *data, void *userdata);
3838
int config_parse_unit_path_printf(const char *filename, unsigned line, const char *section, const char *lvalue, int ltype, const char *rvalue, void *data, void *userdata);
39+
int config_parse_documentation(const char *filename, unsigned line, const char *section, const char *lvalue, int ltype, const char *rvalue, void *data, void *userdata);
3940
int config_parse_socket_listen(const char *filename, unsigned line, const char *section, const char *lvalue, int ltype, const char *rvalue, void *data, void *userdata);
4041
int config_parse_socket_bind(const char *filename, unsigned line, const char *section, const char *lvalue, int ltype, const char *rvalue, void *data, void *userdata);
4142
int config_parse_exec_nice(const char *filename, unsigned line, const char *section, const char *lvalue, int ltype, const char *rvalue, void *data, void *userdata);

‎src/core/unit.c‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -397,6 +397,7 @@ void unit_free(Unit *u) {
397397
cgroup_attribute_free_list(u->cgroup_attributes);
398398

399399
free(u->description);
400+
strv_free(u->documentation);
400401
free(u->fragment_path);
401402
free(u->instance);
402403

@@ -624,7 +625,7 @@ const char *unit_description(Unit *u) {
624625
}
625626

626627
void unit_dump(Unit *u, FILE *f, const char *prefix) {
627-
char *t;
628+
char *t, **j;
628629
UnitDependency d;
629630
Iterator i;
630631
char *p2;
@@ -672,6 +673,9 @@ void unit_dump(Unit *u, FILE *f, const char *prefix) {
672673
SET_FOREACH(t, u->names, i)
673674
fprintf(f, "%s\tName: %s\n", prefix, t);
674675

676+
STRV_FOREACH(j, u->documentation)
677+
fprintf(f, "%s\tDocumentation: %s\n", prefix, *j);
678+
675679
if ((following = unit_following(u)))
676680
fprintf(f, "%s\tFollowing: %s\n", prefix, following->id);
677681

@@ -698,8 +702,6 @@ void unit_dump(Unit *u, FILE *f, const char *prefix) {
698702
}
699703

700704
if (!strv_isempty(u->requires_mounts_for)) {
701-
char **j;
702-
703705
fprintf(f,
704706
"%s\tRequiresMountsFor:", prefix);
705707

‎src/core/unit.h‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,7 @@ struct Unit {
157157
char **requires_mounts_for;
158158

159159
char *description;
160+
char **documentation;
160161

161162
char *fragment_path; /* if loaded from a config file this is the primary path to it */
162163
usec_t fragment_mtime;

‎src/shared/util.c‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5610,3 +5610,24 @@ int can_sleep(const char *type) {
56105610
free(p);
56115611
return found;
56125612
}
5613+
5614+
bool is_valid_documentation_url(const char *url) {
5615+
assert(url);
5616+
5617+
if (startswith(url, "http://") && url[7])
5618+
return true;
5619+
5620+
if (startswith(url, "https://") && url[8])
5621+
return true;
5622+
5623+
if (startswith(url, "file:") && url[5])
5624+
return true;
5625+
5626+
if (startswith(url, "info:") && url[5])
5627+
return true;
5628+
5629+
if (startswith(url, "man:") && url[4])
5630+
return true;
5631+
5632+
return false;
5633+
}

0 commit comments

Comments
 (0)
X Tutup