1
0
mirror of https://github.com/systemd/systemd.git synced 2024-12-25 01:34:28 +03:00
Commit Graph

41 Commits

Author SHA1 Message Date
Kai Lueke
88b51ceb56 man: Remove OSConfig project mentioning for systemd-confext
The systemd-confext use case description was mentioning an OSConfig
project which won't say much to users. Also, it's good to call out that
systemd-confext provides a reliable way to manage configuration because
in contrast to other tools it will remove all old configuration files.
2024-05-06 10:54:15 +02:00
Sam Leonard
9bfabe14e5 man: fix incorrect XML in man page 2024-04-15 10:40:11 +02:00
Krzesimir Nowak
5ae2f83b3e man: Document sysext ephemeral-import mode 2024-03-25 08:30:09 +01:00
Krzesimir Nowak
504bdf08b5 man: Document sysext ephemeral mode 2024-03-25 08:19:48 +01:00
Krzesimir Nowak
ca49d4c33d man: Install sysext man pages when ENABLE_SYSEXT is true 2024-03-25 08:14:36 +01:00
cunshunxia
cc59d1014f man: fix a few issues in manpage
fix: #31482

Signed-off-by: cunshunxia <cunshunxia@tencent.com>
2024-03-20 15:24:11 +01:00
Lennart Poettering
fd571c9df0 man: document new importctl/importd functionality
This also replaces the Fedora download example with another one from
Ubuntu, since Fedora's images these days no longer qualify as DDIs, they
have no distinctive partition type UUIDs set for multiple of their
partitions, hence the images cannot be booted. A bit sad. Let's provide
a command that just works in its place.
2024-03-01 22:29:07 +01:00
Thilo Fromm
ea29a87f23 man/systemd-sysext.xml: document mutable extensions
Signed-off-by: Thilo Fromm <thilofromm@microsoft.com>
2024-02-23 19:17:50 +01:00
David Tardon
eea10b26f7 man: use same version in public and system ident. 2023-12-25 15:51:47 +01:00
David Tardon
13a69c120b man: use <simplelist> for 'See also' sections
This is just a slight markup improvement; there should be no difference
in rendering.
2023-12-23 08:28:57 +01:00
Zbigniew Jędrzejewski-Szmek
73e97bb064 man: use <simplelist> for file lists in synopsis
With <para><filename>…</filename></para>, we get a separate "paragraph" for
each line, i.e. entries separated by empty lines. This uses up a lot of space
and was only done because docbook makes it hard to insert a newline. In some
other places, <literallayout> was used, but then we cannot indent the source
text (because the whitespace would end up in the final page). We can get the
desired result with <simplelist>.

With <simplelist> the items are indented in roff output, but not in html
output. In some places this looks better then no indentation, and in others it
would probably be better to have no indent. But this is a minor issue and we
cannot control that.

(I didn't convert all spots. There's a bunch of other man pages which have two
lines, e.g. an executable and service file, and it doesn't matter there so
much.)
2023-12-15 14:27:28 +01:00
Zbigniew Jędrzejewski-Szmek
de6d05d78d man: "Documentation" is not part of the title
<ulinks> contents are used to generate a SEE ALSO section at the
bottom of a man page, so we need to include the title, without additional
words, in the content.
2023-11-06 20:16:34 +01:00
Zbigniew Jędrzejewski-Szmek
bf63dadbc6 man: more hyperlinks and other fixes
Closes https://github.com/systemd/systemd/issues/29814.
2023-11-06 20:16:34 +01:00
Abderrahim Kitouni
ec07c3c80b man: add version info
This tries to add information about when each option was added. It goes
back to version 183.

The version info is included from a separate file to allow generating it,
which would allow more control on the formatting of the final output.
2023-08-29 14:07:24 +01:00
Mathieu Tortuyaux
41712cd1c0 sysext: support EXTENSION_RELOAD_MANAGER metadata
This metadata (EXTENSION_RELOAD_MANAGER) can be set to "1" to reload the manager
when merging/refreshing/unmerging a system extension image. This can be useful in case the sysext
image provides systemd units that need to be loaded.

With `--no-reload`, one can deactivate the EXTENSION_RELOAD_MANAGER metadata interpretation.

Signed-off-by: Mathieu Tortuyaux <mtortuyaux@microsoft.com>
2023-08-21 11:13:54 +02:00
Antonio Alvarez Feijoo
79567763a2 man/systemd-sysext: correct explanation of confexts directories 2023-05-16 18:43:21 +01:00
Luca Boccassi
0607a9f9da systemd-confext: mount confexts as noexec and nosuid
Confexts should not contain code, so mount confexts with noexec.
We cannot mount invidial extensions as noexec, as the overlay ignores
it and bypasses it, we need to use the flag on the whole overlay for
it to be effective.
But given there are legacy scripts still shipped in /etc, allow to
override it with --noexec=false.
2023-04-14 01:21:48 +08:00
Lennart Poettering
4f25844a4b sysext: define a default image dissection policy for confext images 2023-04-12 14:54:44 +02:00
Lennart Poettering
3af48a86d9
Merge pull request #25608 from poettering/dissect-moar
dissect: add dissection policies
2023-04-12 13:46:08 +02:00
maanyagoenka
1f4f166690 confext: documentation and man page updates for confext 2023-04-05 21:50:04 +00:00
Lennart Poettering
9ea811914f man: document image policy syntax and semantics, and the hooks in the various components 2023-04-05 20:55:15 +02:00
Zbigniew Jędrzejewski-Szmek
0d6e0adef5 man/systemd-sysext: minor grammar optimizations 2023-04-03 15:28:44 +02:00
Luca Boccassi
de862276ed sysext: stop storing under /usr/lib[/local]/extensions/
sysexts are meant to extend /usr. All extension images and directories are opened and merged in a
single, read-only overlayfs layer, mounted on /usr.
So far, we had fallback storage directories in /usr/lib/extensions and /usr/local/lib/extensions.
This is problematic for three reasons.

Firstly, technically, for directory-based extensions the kernel will reject
creating such an overlay, as there is a recursion problem. It actively
validates that a lowerdir is not a child of another lowerdir, and fails with
-ELOOP if it is. So having a sysext /usr/lib/extensions/myextdir/ would result
in an overlayfs config lowerdir=/usr/lib/extensions/myextdir/usr/:/usr which is
not allowed, as indicated by Christian the kernel performs this check:

/*
 * Check if this layer root is a descendant of:
 * - another layer of this overlayfs instance
 * - upper/work dir of any overlayfs instance
 */

<...>

/* Walk back ancestors to root (inclusive) looking for traps */
while (!err && parent != next) {
        if (is_lower && ovl_lookup_trap_inode(sb, parent)) {
                err = -ELOOP;
                pr_err("overlapping %s path\n", name);

Secondly, there's a confusing aspect to this recursive storage. If you
have /usr/lib/extensions/myext.raw which contains /usr/lib/extensions/mynested.raw
'systemd-sysext merge' will only pick up the first one, but both will appear in
the merged root under /usr/lib/extensions/. So you have two extension images, both
appear in your merged filesystem, but only one is actually in use.

Finally, there's a conceptual aspect: the idea behind sysexts and hermetic /usr
is that the /usr tree is not modified locally, but owned by the vendor. Dropping
extensions in /usr thus goes contrary to this foundational concept.
2023-03-30 11:25:17 +01:00
Zbigniew Jędrzejewski-Szmek
8b9f092112 man: fix issues reported by the manpage-l10n project
Fixes #25780.

> Man page: crypttab.5
> Issue 1:  Missing fullstop
> Issue 2:  I<cipher=>, I<hash=>, I<size=> → B<cipher=>, B<hash=>, B<size=>
>
> "Force LUKS mode\\&. When this mode is used, the following options are "
> "ignored since they are provided by the LUKS header on the device: "
> "I<cipher=>, I<hash=>, I<size=>"

Seems OK to me. The full stop is there and has been for at least a few years. And we use <option> for the markup, which is appropriate here.

> Man page: crypttab.5
> Issue 1:  Missing fullstop
> Issue 2:  I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-size=>, I<size=> → B<cipher=>, B<hash=>, B<keyfile-offset=>, B<keyfile-size=>, B<size=>
>
> "Use TrueCrypt encryption mode\\&. When this mode is used, the following "
> "options are ignored since they are provided by the TrueCrypt header on the "
> "device or do not apply: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-"
> "size=>, I<size=>"

Same.

> Man page: journalctl.1
> Issue 1:  make be → may be

Fixed.

> Issue 2:  below\\&. → below:

Fixed.

> Man page: journalctl.1
> Issue:    Colon at the end?
>
> "The following commands are understood\\&. If none is specified the default "
> "is to display journal records\\&."
> msgstr ""
> "Die folgenden Befehle werden verstanden\\&. Falls keiner festgelegt ist, ist "
> "die Anzeige von Journal-Datensätzen die Vorgabe\\&."

This is a bit awkward, but I'm not sure how to fix it.

> Man page: kernel-install.8
> Issue:    methods a fallback → methods fallback

It was correct, but I added a comma to make the sense clearer.

> Man page: loader.conf.5
> Issue 1:  secure boot variables → Secure Boot variables
> Issue 2:  one → one for (multiple times)
>
> "Supported secure boot variables are one database for authorized images, one "
> "key exchange key (KEK) and one platform key (PK)\\&. For more information, "
> "refer to the \\m[blue]B<UEFI specification>\\m[]\\&\\s-2\\u[2]\\d\\s+2, "
> "under Secure Boot and Driver Signing\\&. Another resource that describe the "
> "interplay of the different variables is the \\m[blue]B<EDK2 "
> "documentation>\\m[]\\&\\s-2\\u[3]\\d\\s+2\\&."

"one of" would sound strange. "One this and one that" is OK.

> Man page: loader.conf.5
> Issue:    systemd-boot → B<systemd-boot>(7)

Fixed.

> Man page: logind.conf.5
> Issue:    systemd-logind → B<systemd-logind>(8)

We use <filename>systemd-logind</> on subsequent references… I think that's good enough.

> Man page: nss-myhostname.8
> Issue:    B<getent> → B<getent>(1)

Fixed.

> Man page: nss-resolve.8
> Issue:    B<systemd-resolved> → B<systemd-resolved>(8)

The first reference does this, subsequent are shorter.

> Man page: os-release.5
> Issue:    Portable Services → Portable Services Documentation?

Updated.

> Man page: pam_systemd_home.8
> Issue:    auth and account use "reason", while session and password do not?

Reworded.

> Man page: portablectl.1
> Issue:    In systemd-portabled.service(8): Portable Services Documentation

Updated.

> Man page: repart.d.5
> Issue:    The partition → the partition

Fixed.

> Man page: repart.d.5
> Issue:    B<systemd-repart> → B<systemd-repart>(8)

The first reference does this. I also change this one, because it's pretty far down in the text.

> Man page: systemd.1
> Issue:    kernel command line twice?
>
> "Takes a boolean argument\\&. If false disables importing credentials from "
> "the kernel command line, qemu_fw_cfg subsystem or the kernel command line\\&."

Apparently this was fixed already.

> Man page: systemd-boot.7
> Issue:    enrollement → enrollment

Fixed.

> Man page: systemd-cryptenroll.1
> Issue:    multiple cases: any specified → the specified

Reworded.

> Man page: systemd-cryptenroll.1
> Issue:    If this this → If this

Fixed tree-wide.

> Man page: systemd-cryptsetup-generator.8
> Issue:    and the initrd → and in the initrd

"Is honoured by the initrd" is OK, because we often speak about the initrd as a single unit. But in the same paragraph we also used "in the initrd", which makes the other use look sloppy. I changed it to "in the initrd" everywhere in that file.

> Man page: systemd.directives.7
> Issue:    Why are these two quoted (but not others)?
>
> "B<\\*(Aqh\\*(Aq>"
>
> B<\\*(Aqs\\*(Aq>"
>
> "B<\\*(Aqy\\*(Aq>"

This is autogenerated from files… We use slightly different markup in different files, and it's just too hard to make it consistent. We gave up on this.

> Man page: systemd.exec.5
> Issue 1:  B<at>(1p) → B<at>(1)
> Issue 2:  B<crontab>(1p) → B<crontab>(1)

Fixed.

> Man page: systemd.exec.5
> Issue:    B<select()> → B<select>(2)

Fixed.

> Man page: systemd.exec.5
> Issue:   qemu → B<qemu>(1)

The man page doesn't seem to be in any of the canonical places on the web.
I added a link to online docs.

> Man page: systemd.exec.5
> Issue:    variable → variables

Seems to be fixed already.

> Man page: systemd-integritysetup-generator.8
> Issue:    systemd-integritysetup-generator → B<systemd-integritysetup-generator>

I changed <filename> to <command>.

> Man page: systemd-integritysetup-generator.8
> Issue:    superfluous comma at the end

Already fixed.

> Man page: systemd-measure.1
> Issue:    (see B<--pcr-bank=>) below → (see B<--pcr-bank=> below)

Reworded.

> Man page: systemd-measure.1
> Issue:    =PATH> → =>I<PATH>

Fixed.

> Man page: systemd-measure.1.po
> Issue:    B<--bank=DIGEST> → B<--bank=>I<DIGEST>

Fixed.

> Man page: systemd.netdev.5
> Issue:    os the → on the

Appears to have been fixed already.

> Man page: systemd.netdev.5
> Issue:    Onboard → On-board (as in previous string)

Updated.

> Man page: systemd.network.5
> Issue:    B<systemd-networkd> -> B<systemd-networkd>(8)

First reference does this, subsequent do not.

> Man page: systemd.network.5
> Issue:    B<netlabelctl> → B<netlabelctl>(8)

First reference does this, subsequent do not.

> Man page: systemd.network.5
> Issue:    Missing verb (aquired? configured?) in the half sentence starting with "or by a "

I dropped the comma.

> Man page: systemd-nspawn.1
> Issue:    All host users outside of that range → All other host users

Reworded.

> # FIXME no effect → no effect\\&.
> #. type: Plain text
> #: archlinux debian-unstable fedora-rawhide mageia-cauldron opensuse-tumbleweed
> msgid ""
> "Whichever ID mapping option is used, the same mapping will be used for users "
> "and groups IDs\\&. If B<rootidmap> is used, the group owning the bind "
> "mounted directory will have no effect"

A period is added. Not sure if there's some other issue.

> Man page: systemd-oomd.service.8
> Issue:    B<systemd> → B<systemd>(1)

Done.

> Man page: systemd.path.5
> Issue 1:  B<systemd.exec>(1) → B<systemd.exec>(5)
> Issue 2:  This section does not (yet?) exist

Fixed.

> Man page: systemd-pcrphase.service.8
> Issue 1:  indicate phases into TPM2 PCR 11 ??
> Issue 2: Colon at the end of the paragraph?

Fixed.

> Man page: systemd-pcrphase.service.8
> Issue:    final boot phase → final shutdown phase?

Updated.

> Man page: systemd-pcrphase.service.8
> Issue:    for the the → for the

Fixed tree-wide.

> Man page: systemd-portabled.service.8
> Issue:    In systemd-portabled.service(8): Portable Services Documentation

Updated.

> Man page: systemd-pstore.service.8
> Issue:    Here and the following paragraphs: . → \\&. // Upstream: What does this comment mean? // You normally write \\&. for a full dot (full stop etc.); here you write only "." (i.e. a plain dot).
>
> "and we look up \"localhost\", nss-dns will send the following queries to "
> "systemd-resolved listening on 127.0.0.53:53: first \"localhost.foobar.com\", "
> "then \"localhost.barbar.com\", and finally \"localhost\". If (hopefully) the "
> "first two queries fail, systemd-resolved will synthesize an answer for the "
> "third query."

Looks all OK to me.

> Man page: systemd.resource-control.5
> Issue:    Missing closing bracket after link to Control Groups version 1

Fixed.

> Man page: systemd-sysext.8
> Issue:    In systemd-portabled.service(8): Portable Services Documentation

Updated.

> Man page: systemd.timer.5
> Issue 1:  B<systemd.exec>(1) → B<systemd.exec>(5)
> Issue 2:  This section does not (yet?) exist

Fixed.

> Man page: systemd.unit.5
> Issue:    that is → that are

Fixed.

> Man page: systemd-veritysetup-generator.8
> Issue:    systemd-veritysetup-generator → B<systemd-veritysetup-generator>
>
 > "systemd-veritysetup-generator implements B<systemd.generator>(7)\\&."
>
> "systemd-veritysetup-generator understands the following kernel command line "
> "parameters:"

Updated.

> Man page: systemd-volatile-root.service.8
> Issue:    initrdyes → Initrd

Fixed.

> Man page: sysupdate.d.5
> Issue:    : → \\&. (As above in TRANSFER)

Updated.

> Man page: sysupdate.d.5
> Issue:    some → certain

Updated.

> Man page: sysupdate.d.5
> Issue 1:  i\\&.e\\& → I\\&.e\\&

Fixed.

> Issue 2:  the image → the system

"image" seems correct.

> Man page: tmpfiles.d.5
> Issue:    systemd-tmpfiles → B<systemd-tmpfiles>(8)

Updated.
2023-01-11 17:12:54 +01:00
Lennart Poettering
09e917ea4d repart: support erofs
So, i think "erofs" is probably the better, more modern alternative to
"squashfs". Many of the benefits don't matter too much to us I guess,
but there's one thing that stands out: erofs has a UUID in the
superblock, squashfs has not. Having an UUID in the superblock matters
if the file systems are used in an overlayfs stack, as overlayfs uses
the UUIDs to robustly and persistently reference inodes on layers in
case of metadata copy-up.

Since we probably want to allow such uses in overlayfs as emplyoed by
sysext (and the future syscfg) we probably should ramp up our erofs game
early on. Hence let's natively support erofs, test it, and in fact
mention it in the docs before squashfs even.
2022-12-10 11:26:36 +01:00
Zbigniew Jędrzejewski-Szmek
db81144428 tree-wide: BLS and DPS are now on uapi-group website 2022-11-21 12:26:35 +01:00
Antonio Alvarez Feijoo
782e41ab88 sysext: add missing COMMAND to the help output and man synopsis 2022-08-22 15:41:12 +01:00
Kai Lueke
1abe15fe9d man: Correct information on sysext masking
While I had tested that a symlink to /dev/null works to "mask" a sysext
I must have gotten something wrong and thus the instructions in
519c2f0d6b don't work. What works,
at least at the moment, is to instead have an empty directory with the
extension name under /etc/extensions/.
Correct the info in the man page and add a test for it.
2022-08-16 20:43:51 +01:00
Kai Lueke
16c1ca0db4 sysext: introduce ARCHITECTURE field to match host architecture
When an extension image has binaries they should match the host
architecture. Currently there is no way to specify this requirement.
Introduce an ARCHITECTURE field in the extension's release file that
may be set to prevent loading on the wrong host architecture.
Since this new field is introduced late, we don't want to make
specifying it mandatory as it would break existing sysext images.

See https://github.com/systemd/systemd/issues/24061
2022-08-15 10:54:32 +02:00
Kai Lueke
ab4d43c54e sysext: support distribution-independent extensions using ID=_any
A sysext image that merely contains static binaries has no dependency
on the host distribution and should be able to be used anywhere.
Support the special '_any' value for the ID field in the extension to
opt-out of ID and VERSION_ID/SYSEXT_LEVEL matching.

See https://github.com/systemd/systemd/issues/24061
2022-08-15 10:51:01 +02:00
Kai Lueke
519c2f0d6b man: Document mask workaround for sysext images
A read-only /usr may ship a sysext image by default and the user wants
to opt out. Currently it's not clear how to do this.
Document that a /dev/null symlink in /etc/extensions/ works to "mask" a
sysext image in a folder with lower precedence.
2022-07-22 15:09:21 +02:00
Kai Lueke
566e4b3a19 man: Do not recommend to overlay files with sysext even if possible
While overlaying files with a sysext can be useful, it may lead to
unexpected problems depending on when a process got started and which
version of the file it gets.
Call out that overlaying files is possible but don't recommend to make
use of it.
2022-07-22 15:03:12 +02:00
Javkhlanbayar Khongorzul
01ae74c8c7 man: Fix minor typo 2022-05-28 18:38:47 +09:00
Zbigniew Jędrzejewski-Szmek
6a15846d10 man: fix minor grammar issue
The usual: "searched" vs. "searched for".
2021-08-24 14:53:26 +02:00
Zbigniew Jędrzejewski-Szmek
d6029680df man: use title of docs/ pages when referring to them
There is some inconsistency, partially caused by the awkward naming
of the docs/ pages. But let's be consistent and use the "official" title.
If we ever change plural↔singular, we should use the same form everywhere.
2021-07-27 09:43:29 +02:00
Zbigniew Jędrzejewski-Szmek
be0d27ee0c man: fix assorted issues reported by the manpage-l10n project
Fixes #20297.
2021-07-27 09:43:29 +02:00
Lennart Poettering
8d0d1a309e man: share a common explanation for --json= 2021-01-21 18:21:41 +01:00
Lennart Poettering
16a36b5616 sysext: port to table_print_with_pager()
This adds --no-legend as side-effect.
2021-01-21 18:14:21 +01:00
Lennart Poettering
301265ea10 man: document recent systemd-sysext interface changes 2021-01-20 17:50:23 +01:00
Luca Boccassi
60bb6caaae sysext: use parse_extension_release and reject extension if not found 2021-01-19 13:41:42 +01:00
Lennart Poettering
7a87fb6119 man: add man page for systemd-sysext 2021-01-19 13:41:42 +01:00