mirror of
https://github.com/systemd/systemd-stable.git
synced 2024-12-22 13:33:56 +03:00
docs: fix grammar a bit
This commit is contained in:
parent
d8b67e05fb
commit
e347d53ace
@ -44,7 +44,7 @@ on `src/fundamental/` + `src/basic/`, or also on `src/libsystemd/`, or also on
|
|||||||
`src/shared/`.
|
`src/shared/`.
|
||||||
|
|
||||||
You might wonder what kind of code belongs where. In general, the rule is that
|
You might wonder what kind of code belongs where. In general, the rule is that
|
||||||
code should linked as few times as possible, ideally only once. Thus code that
|
code should be linked as few times as possible, ideally only once. Thus code that
|
||||||
is used by "higher-level" components (e.g. our binaries which are linked to
|
is used by "higher-level" components (e.g. our binaries which are linked to
|
||||||
`libsystemd-shared-<nnn>.so`), would go to a subdirectory specific to that
|
`libsystemd-shared-<nnn>.so`), would go to a subdirectory specific to that
|
||||||
component if it is only used there. If the code is to be shared between
|
component if it is only used there. If the code is to be shared between
|
||||||
@ -99,7 +99,7 @@ setting, it is necessary to support all three input methods:
|
|||||||
unit settings being parsed by common helpers, with the definition in the generator file
|
unit settings being parsed by common helpers, with the definition in the generator file
|
||||||
`src/core/load-fragment-gperf.gperf.in`
|
`src/core/load-fragment-gperf.gperf.in`
|
||||||
2. D-Bus messages are defined and parsed in `src/core/dbus-*.c`
|
2. D-Bus messages are defined and parsed in `src/core/dbus-*.c`
|
||||||
3. `systemd-run` and `systemctl set-property` do client-side parsing and translating into
|
3. `systemd-run` and `systemctl set-property` do client-side parsing and translation into
|
||||||
D-Bus messages in `src/shared/bus-unit-util.c`
|
D-Bus messages in `src/shared/bus-unit-util.c`
|
||||||
|
|
||||||
So that they are exercised by the fuzzing CI, new unit settings should also be listed in the
|
So that they are exercised by the fuzzing CI, new unit settings should also be listed in the
|
||||||
|
@ -15,7 +15,7 @@ many attempts should be made to boot it. This document describes how systemd
|
|||||||
implements this scheme.
|
implements this scheme.
|
||||||
|
|
||||||
The many different components involved in the implementation may be used
|
The many different components involved in the implementation may be used
|
||||||
independently and in combination with other software to for example support
|
independently and in combination with other software to, for example, support
|
||||||
other boot loaders or take actions outside of the boot loader.
|
other boot loaders or take actions outside of the boot loader.
|
||||||
|
|
||||||
Here's a brief overview of the complete set of components:
|
Here's a brief overview of the complete set of components:
|
||||||
@ -93,10 +93,10 @@ Here's an example walkthrough of how this all fits together.
|
|||||||
After the rename completed, the entry is booted as usual.
|
After the rename completed, the entry is booted as usual.
|
||||||
|
|
||||||
4. Let's say this attempt to boot fails. On the following boot the boot loader
|
4. Let's say this attempt to boot fails. On the following boot the boot loader
|
||||||
will hence see the `+2-1` tag in the name, and hence rename the entry file to
|
will hence see the `+2-1` tag in the name, and will hence rename the entry file to
|
||||||
`4.14.11-300.fc27.x86_64+1-2.conf`, and boot it.
|
`4.14.11-300.fc27.x86_64+1-2.conf`, and boot it.
|
||||||
|
|
||||||
5. Let's say the boot fails again. On the subsequent boot the loader hence will
|
5. Let's say the boot fails again. On the subsequent boot the loader will hence
|
||||||
see the `+1-2` tag, and rename the file to
|
see the `+1-2` tag, and rename the file to
|
||||||
`4.14.11-300.fc27.x86_64+0-3.conf` and boot it.
|
`4.14.11-300.fc27.x86_64+0-3.conf` and boot it.
|
||||||
|
|
||||||
@ -200,7 +200,7 @@ are a couple of recommendations.
|
|||||||
|
|
||||||
Such unit would be typically wanted (or required) by one of the
|
Such unit would be typically wanted (or required) by one of the
|
||||||
[`bootup`](https://www.freedesktop.org/software/systemd/man/bootup.html) targets,
|
[`bootup`](https://www.freedesktop.org/software/systemd/man/bootup.html) targets,
|
||||||
for example `multi-user.target`. To avoid potential loops due to conflicting
|
for example, `multi-user.target`. To avoid potential loops due to conflicting
|
||||||
[default dependencies](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Default%20Dependencies)
|
[default dependencies](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Default%20Dependencies)
|
||||||
ordering, it is recommended to also add an explicit dependency (e.g.
|
ordering, it is recommended to also add an explicit dependency (e.g.
|
||||||
`After=multi-user.target`) to the unit. This overrides the implicit ordering
|
`After=multi-user.target`) to the unit. This overrides the implicit ordering
|
||||||
|
@ -32,7 +32,7 @@ boot. For that it's essential to:
|
|||||||
is not reset, and carries a valid ID every instance of the system will come
|
is not reset, and carries a valid ID every instance of the system will come
|
||||||
up with the same ID and that will likely lead to problems sooner or later,
|
up with the same ID and that will likely lead to problems sooner or later,
|
||||||
as many network-visible identifiers are commonly derived from the machine
|
as many network-visible identifiers are commonly derived from the machine
|
||||||
ID, for example IPv6 addresses or transient MAC addresses.
|
ID, for example, IPv6 addresses or transient MAC addresses.
|
||||||
|
|
||||||
2. Remove the `/var/lib/systemd/random-seed` file (see
|
2. Remove the `/var/lib/systemd/random-seed` file (see
|
||||||
[`systemd-random-seed(8)`](https://www.freedesktop.org/software/systemd/man/systemd-random-seed.service.html)),
|
[`systemd-random-seed(8)`](https://www.freedesktop.org/software/systemd/man/systemd-random-seed.service.html)),
|
||||||
@ -83,7 +83,7 @@ which can be a freely chosen string to use for identifying the boot menu
|
|||||||
resources of the OS. If not configured explicitly it defaults to the machine
|
resources of the OS. If not configured explicitly it defaults to the machine
|
||||||
ID. The file `/etc/kernel/entry-token` may be used to configure this string
|
ID. The file `/etc/kernel/entry-token` may be used to configure this string
|
||||||
explicitly. Thus, golden image builders should write a suitable identifier into
|
explicitly. Thus, golden image builders should write a suitable identifier into
|
||||||
this file, for example the `IMAGE_ID=` or `ID=` field from
|
this file, for example, the `IMAGE_ID=` or `ID=` field from
|
||||||
[`/etc/os-release`](https://www.freedesktop.org/software/systemd/man/os-release.html)
|
[`/etc/os-release`](https://www.freedesktop.org/software/systemd/man/os-release.html)
|
||||||
(also see below). It is recommended to do this before the `kernel-install`
|
(also see below). It is recommended to do this before the `kernel-install`
|
||||||
functionality is invoked (i.e. before the package manager is used to install
|
functionality is invoked (i.e. before the package manager is used to install
|
||||||
|
@ -208,7 +208,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later
|
|||||||
variables if you are sure that thread-safety doesn't matter in your
|
variables if you are sure that thread-safety doesn't matter in your
|
||||||
case. Alternatively, consider using TLS, which is pretty easy to use with
|
case. Alternatively, consider using TLS, which is pretty easy to use with
|
||||||
gcc's `thread_local` concept. It's also OK to store data that is inherently
|
gcc's `thread_local` concept. It's also OK to store data that is inherently
|
||||||
global in global variables, for example data parsed from command lines, see
|
global in global variables, for example, data parsed from command lines, see
|
||||||
below.
|
below.
|
||||||
|
|
||||||
- Our focus is on the GNU libc (glibc), not any other libcs. If other libcs are
|
- Our focus is on the GNU libc (glibc), not any other libcs. If other libcs are
|
||||||
@ -604,7 +604,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later
|
|||||||
i.e. file system objects that are supposed to be regular files whose paths
|
i.e. file system objects that are supposed to be regular files whose paths
|
||||||
were specified by the user and hence might actually refer to other types of
|
were specified by the user and hence might actually refer to other types of
|
||||||
file system objects. This is a good idea so that we don't end up blocking on
|
file system objects. This is a good idea so that we don't end up blocking on
|
||||||
'strange' file nodes, for example if the user pointed us to a FIFO or device
|
'strange' file nodes, for example, if the user pointed us to a FIFO or device
|
||||||
node which may block when opening. Moreover even for actual regular files
|
node which may block when opening. Moreover even for actual regular files
|
||||||
`O_NONBLOCK` has a benefit: it bypasses any mandatory lock that might be in
|
`O_NONBLOCK` has a benefit: it bypasses any mandatory lock that might be in
|
||||||
effect on the regular file. If in doubt consider turning off `O_NONBLOCK`
|
effect on the regular file. If in doubt consider turning off `O_NONBLOCK`
|
||||||
|
@ -210,7 +210,7 @@ manager, please consider supporting the following interfaces.
|
|||||||
container name the external side `ve-` + the container name.
|
container name the external side `ve-` + the container name.
|
||||||
|
|
||||||
3. It is recommended to configure stable MAC addresses for container `veth`
|
3. It is recommended to configure stable MAC addresses for container `veth`
|
||||||
devices, for example hashed out of the container names. That way it is more
|
devices, for example, hashed out of the container names. That way it is more
|
||||||
likely that DHCP and IPv4LL will acquire stable addresses.
|
likely that DHCP and IPv4LL will acquire stable addresses.
|
||||||
|
|
||||||
## The `/run/host/` Hierarchy
|
## The `/run/host/` Hierarchy
|
||||||
@ -389,7 +389,7 @@ everybody. However, that's a systemd-specific interface and other init systems
|
|||||||
are unlikely to do the same.
|
are unlikely to do the same.
|
||||||
|
|
||||||
Note that it is our intention to make systemd systems work flawlessly and
|
Note that it is our intention to make systemd systems work flawlessly and
|
||||||
out-of-the-box in containers. In fact we are interested to ensure that the same
|
out-of-the-box in containers. In fact, we are interested to ensure that the same
|
||||||
OS image can be booted on a bare system, in a VM and in a container, and behave
|
OS image can be booted on a bare system, in a VM and in a container, and behave
|
||||||
correctly each time. If you notice that some component in systemd does not work
|
correctly each time. If you notice that some component in systemd does not work
|
||||||
in a container as it should, even though the container manager implements
|
in a container as it should, even though the container manager implements
|
||||||
|
@ -162,7 +162,7 @@ When invoked from service context, `systemd-creds` passed without further
|
|||||||
parameters will list passed credentials. The `systemd-creds cat xyz` command
|
parameters will list passed credentials. The `systemd-creds cat xyz` command
|
||||||
may be used to write the contents of credential `xyz` to standard output. If
|
may be used to write the contents of credential `xyz` to standard output. If
|
||||||
these calls are combined with the `--system` switch credentials passed to the
|
these calls are combined with the `--system` switch credentials passed to the
|
||||||
system as a whole are shown, instead of the those passed to the service the
|
system as a whole are shown, instead of those passed to the service the
|
||||||
command is invoked from.
|
command is invoked from.
|
||||||
|
|
||||||
Example use:
|
Example use:
|
||||||
@ -179,17 +179,17 @@ via `systemd-creds cat`.
|
|||||||
|
|
||||||
Credentials are supposed to be useful for carrying sensitive information, such
|
Credentials are supposed to be useful for carrying sensitive information, such
|
||||||
as cryptographic key material. For this kind of data (symmetric) encryption and
|
as cryptographic key material. For this kind of data (symmetric) encryption and
|
||||||
authentication is provided to make storage of the data at rest safer. The data
|
authentication are provided to make storage of the data at rest safer. The data
|
||||||
may be encrypted and authenticated with AES256-GCM. The encryption key can
|
may be encrypted and authenticated with AES256-GCM. The encryption key can
|
||||||
either be one derived from the local TPM2 device, or one stored in
|
either be one derived from the local TPM2 device, or one stored in
|
||||||
`/var/lib/systemd/credential.secret`, or a combination of both. If a TPM2
|
`/var/lib/systemd/credential.secret`, or a combination of both. If a TPM2
|
||||||
device is available and `/var/` resides on persistent storage the default
|
device is available and `/var/` resides on a persistent storage, the default
|
||||||
behaviour is to use the combination of both for encryption, thus ensuring that
|
behaviour is to use the combination of both for encryption, thus ensuring that
|
||||||
credentials protected this way can only be decrypted and validated on the
|
credentials protected this way can only be decrypted and validated on the
|
||||||
local hardware and OS installation. Encrypted credentials stored on disk thus
|
local hardware and OS installation. Encrypted credentials stored on disk thus
|
||||||
cannot be decrypted without access to the TPM2 chip and the aforementioned key
|
cannot be decrypted without access to the TPM2 chip and the aforementioned key
|
||||||
file `/var/lib/systemd/credential.secret`. Moreover, credentials cannot be
|
file `/var/lib/systemd/credential.secret`. Moreover, credentials cannot be
|
||||||
prepared on another machine than the local one.
|
prepared on a machine other than the local one.
|
||||||
|
|
||||||
The `systemd-creds` tool provides the commands `encrypt` and `decrypt` to
|
The `systemd-creds` tool provides the commands `encrypt` and `decrypt` to
|
||||||
encrypt and decrypt/authenticate credentials. Example:
|
encrypt and decrypt/authenticate credentials. Example:
|
||||||
@ -345,7 +345,7 @@ Various services shipped with `systemd` consume credentials for tweaking behavio
|
|||||||
`passwd.plaintext-password.<username>` and `passwd.shell.<username>` to
|
`passwd.plaintext-password.<username>` and `passwd.shell.<username>` to
|
||||||
configure the password (either in UNIX hashed form, or plaintext) or shell of
|
configure the password (either in UNIX hashed form, or plaintext) or shell of
|
||||||
system users created. Replace `<username>` with the system user of your
|
system users created. Replace `<username>` with the system user of your
|
||||||
choice, for example `root`.
|
choice, for example, `root`.
|
||||||
|
|
||||||
* [`systemd-firstboot(1)`](https://www.freedesktop.org/software/systemd/man/systemd-firstboot.html)
|
* [`systemd-firstboot(1)`](https://www.freedesktop.org/software/systemd/man/systemd-firstboot.html)
|
||||||
will look for the credentials `firstboot.locale`, `firstboot.locale-messages`,
|
will look for the credentials `firstboot.locale`, `firstboot.locale-messages`,
|
||||||
|
@ -85,7 +85,7 @@ instead install your own.
|
|||||||
|
|
||||||
## Contributing Upstream
|
## Contributing Upstream
|
||||||
|
|
||||||
We generally do no longer accept distribution-specific patches to
|
We generally no longer accept distribution-specific patches to
|
||||||
systemd upstream. If you have to make changes to systemd's source code
|
systemd upstream. If you have to make changes to systemd's source code
|
||||||
to make it work on your distribution, unless your code is generic
|
to make it work on your distribution, unless your code is generic
|
||||||
enough to be generally useful, we are unlikely to merge it. Please
|
enough to be generally useful, we are unlikely to merge it. Please
|
||||||
|
@ -303,7 +303,7 @@ Docker would do it, as these are regular system services they aren't run as PID
|
|||||||
|
|
||||||
If services shipped with this mechanism shall be able to access host resources
|
If services shipped with this mechanism shall be able to access host resources
|
||||||
(such as files or AF_UNIX sockets for IPC), use the normal `BindPaths=` and
|
(such as files or AF_UNIX sockets for IPC), use the normal `BindPaths=` and
|
||||||
`BindReadOnlyPaths=` settings in unit files to mount them in. In fact the
|
`BindReadOnlyPaths=` settings in unit files to mount them in. In fact, the
|
||||||
`default` profile mentioned above makes use of this to ensure
|
`default` profile mentioned above makes use of this to ensure
|
||||||
`/etc/resolv.conf`, the D-Bus system bus socket or write access to the logging
|
`/etc/resolv.conf`, the D-Bus system bus socket or write access to the logging
|
||||||
subsystem are available to the service.
|
subsystem are available to the service.
|
||||||
@ -329,7 +329,7 @@ units shipped with the OS itself as for attached portable services.
|
|||||||
## Immutable images with local data
|
## Immutable images with local data
|
||||||
|
|
||||||
It's a good idea to keep portable service images read-only during normal
|
It's a good idea to keep portable service images read-only during normal
|
||||||
operation. In fact all but the `trusted` profile will default to this kind of
|
operation. In fact, all but the `trusted` profile will default to this kind of
|
||||||
behaviour, by setting the `ProtectSystem=strict` option. In this case writable
|
behaviour, by setting the `ProtectSystem=strict` option. In this case writable
|
||||||
service data may be placed on the host file system. Use `StateDirectory=` in
|
service data may be placed on the host file system. Use `StateDirectory=` in
|
||||||
the unit files to enable such behaviour and add a local data directory to the
|
the unit files to enable such behaviour and add a local data directory to the
|
||||||
|
@ -34,7 +34,7 @@ architecture.
|
|||||||
variable logic in `meson.build` to be set to the right architecture string
|
variable logic in `meson.build` to be set to the right architecture string
|
||||||
as defined by the UEFI specification. (This ensures that `systemd-boot` will
|
as defined by the UEFI specification. (This ensures that `systemd-boot` will
|
||||||
be built as the appropriately named `BOOT<arch>.EFI` binary.) Also, if your
|
be built as the appropriately named `BOOT<arch>.EFI` binary.) Also, if your
|
||||||
architecture uses a special boot protocol for the Linux kernel make sure to
|
architecture uses a special boot protocol for the Linux kernel, make sure to
|
||||||
implement it in `src/boot/efi/linux*.c`, so that the `systemd-stub` EFI stub
|
implement it in `src/boot/efi/linux*.c`, so that the `systemd-stub` EFI stub
|
||||||
can work.
|
can work.
|
||||||
|
|
||||||
@ -54,5 +54,5 @@ architecture.
|
|||||||
`/usr/` mounted in.
|
`/usr/` mounted in.
|
||||||
|
|
||||||
7. If your architecture supports VM virtualization and provides CPU opcodes
|
7. If your architecture supports VM virtualization and provides CPU opcodes
|
||||||
similar to x86' CPUID consider adding native support for detecting VMs this
|
similar to x86' CPUID, consider adding native support for detecting VMs this
|
||||||
way to `src/basic/virt.c`.
|
way to `src/basic/virt.c`.
|
||||||
|
@ -26,23 +26,23 @@ The Linux kernel provides three relevant userspace APIs to request random data
|
|||||||
from the kernel's entropy pool:
|
from the kernel's entropy pool:
|
||||||
|
|
||||||
* The [`getrandom()`](https://man7.org/linux/man-pages/man2/getrandom.2.html)
|
* The [`getrandom()`](https://man7.org/linux/man-pages/man2/getrandom.2.html)
|
||||||
system call with its `flags` parameter set to 0. If invoked the calling
|
system call with its `flags` parameter set to 0. If invoked, the calling
|
||||||
program will synchronously block until the random pool is fully initialized
|
program will synchronously block until the random pool is fully initialized
|
||||||
and the requested bytes can be provided.
|
and the requested bytes can be provided.
|
||||||
|
|
||||||
* The `getrandom()` system call with its `flags` parameter set to
|
* The `getrandom()` system call with its `flags` parameter set to
|
||||||
`GRND_NONBLOCK`. If invoked the request for random bytes will fail if the
|
`GRND_NONBLOCK`. If invoked, the request for random bytes will fail if the
|
||||||
pool is not initialized yet.
|
pool is not initialized yet.
|
||||||
|
|
||||||
* Reading from the
|
* Reading from the
|
||||||
[`/dev/urandom`](https://man7.org/linux/man-pages/man4/urandom.4.html)
|
[`/dev/urandom`](https://man7.org/linux/man-pages/man4/urandom.4.html)
|
||||||
pseudo-device will always return random bytes immediately, even if the pool
|
pseudo-device will always return random bytes immediately, even if the pool
|
||||||
is not initialized. The provided random bytes will be of low quality in this
|
is not initialized. The provided random bytes will be of low quality in this
|
||||||
case however. Moreover the kernel will log about all programs using this
|
case however. Moreover, the kernel will log about all programs using this
|
||||||
interface in this state, and which thus potentially rely on an uninitialized
|
interface in this state, and which thus potentially rely on an uninitialized
|
||||||
entropy pool.
|
entropy pool.
|
||||||
|
|
||||||
(Strictly speaking there are more APIs, for example `/dev/random`, but these
|
(Strictly speaking, there are more APIs, for example `/dev/random`, but these
|
||||||
should not be used by almost any application and hence aren't mentioned here.)
|
should not be used by almost any application and hence aren't mentioned here.)
|
||||||
|
|
||||||
Note that the time it takes to initialize the random pool may differ between
|
Note that the time it takes to initialize the random pool may differ between
|
||||||
@ -107,7 +107,7 @@ encrypted storage which might need random numbers. systemd itself requires
|
|||||||
random numbers as well, including for the following uses:
|
random numbers as well, including for the following uses:
|
||||||
|
|
||||||
* systemd assigns 'invocation' UUIDs to all services it invokes that uniquely
|
* systemd assigns 'invocation' UUIDs to all services it invokes that uniquely
|
||||||
identify each invocation. This is useful retain a global handle on a specific
|
identify each invocation. This is useful to retain a global handle on a specific
|
||||||
service invocation and relate it to other data. For example, log data
|
service invocation and relate it to other data. For example, log data
|
||||||
collected by the journal usually includes the invocation UUID and thus the
|
collected by the journal usually includes the invocation UUID and thus the
|
||||||
runtime context the service manager maintains can be neatly matched up with
|
runtime context the service manager maintains can be neatly matched up with
|
||||||
|
@ -31,11 +31,11 @@ Note that this will only work with a recent version of mkosi (>= 14 or by runnin
|
|||||||
|
|
||||||
## gcc
|
## gcc
|
||||||
gcc compiles in sanitizer libraries dynamically by default, so you need to get
|
gcc compiles in sanitizer libraries dynamically by default, so you need to get
|
||||||
the shared libraries first - on Fedora these are shipped as a separate packages
|
the shared libraries first - on Fedora these are shipped as separate packages
|
||||||
(`libasan` for Address Sanitizer and `libubsan` for Undefined Behavior Sanitizer).
|
(`libasan` for Address Sanitizer and `libubsan` for Undefined Behavior Sanitizer).
|
||||||
|
|
||||||
The compilation itself is then a matter of simply adding `-Db_sanitize=address,undefined`
|
The compilation itself is then a matter of simply adding `-Db_sanitize=address,undefined`
|
||||||
to `meson`. That's it - following executions of `meson test` and integrations tests
|
to `meson`. That's it - following executions of `meson test` and integration tests
|
||||||
under `test/` subdirectory will run with sanitizers enabled. However, to get
|
under `test/` subdirectory will run with sanitizers enabled. However, to get
|
||||||
truly useful results, you should tweak the runtime configuration of respective
|
truly useful results, you should tweak the runtime configuration of respective
|
||||||
sanitizers; e.g. in systemd we set the following environment variables:
|
sanitizers; e.g. in systemd we set the following environment variables:
|
||||||
|
@ -29,7 +29,7 @@ Generally, the same rules apply for user as for group names.
|
|||||||
hyphen](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282),
|
hyphen](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282),
|
||||||
with the restriction that hyphen is not allowed as first character of the
|
with the restriction that hyphen is not allowed as first character of the
|
||||||
user name. Interestingly no size limit is declared, i.e. in neither
|
user name. Interestingly no size limit is declared, i.e. in neither
|
||||||
direction, meaning that strictly speaking according to POSIX both the empty
|
direction, meaning that strictly speaking, according to POSIX, both the empty
|
||||||
string is a valid user name as well as a string of gigabytes in length.
|
string is a valid user name as well as a string of gigabytes in length.
|
||||||
|
|
||||||
* Debian/Ubuntu based systems enforce the regular expression
|
* Debian/Ubuntu based systems enforce the regular expression
|
||||||
|
Loading…
Reference in New Issue
Block a user