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/`.
|
||||
|
||||
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
|
||||
`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
|
||||
@ -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
|
||||
`src/core/load-fragment-gperf.gperf.in`
|
||||
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`
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
`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
|
||||
[`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)
|
||||
ordering, it is recommended to also add an explicit dependency (e.g.
|
||||
`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
|
||||
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
|
||||
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
|
||||
[`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
|
||||
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
|
||||
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)
|
||||
(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
|
||||
|
@ -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
|
||||
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
|
||||
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.
|
||||
|
||||
- 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
|
||||
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
|
||||
'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
|
||||
`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`
|
||||
|
@ -210,7 +210,7 @@ manager, please consider supporting the following interfaces.
|
||||
container name the external side `ve-` + the container name.
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
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
|
||||
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
|
||||
|
@ -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
|
||||
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
|
||||
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.
|
||||
|
||||
Example use:
|
||||
@ -179,17 +179,17 @@ via `systemd-creds cat`.
|
||||
|
||||
Credentials are supposed to be useful for carrying sensitive information, such
|
||||
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
|
||||
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
|
||||
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
|
||||
credentials protected this way can only be decrypted and validated on the
|
||||
local hardware and OS installation. Encrypted credentials stored on disk thus
|
||||
cannot be decrypted without access to the TPM2 chip and the aforementioned key
|
||||
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
|
||||
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
|
||||
configure the password (either in UNIX hashed form, or plaintext) or shell of
|
||||
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)
|
||||
will look for the credentials `firstboot.locale`, `firstboot.locale-messages`,
|
||||
|
@ -85,7 +85,7 @@ instead install your own.
|
||||
|
||||
## 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
|
||||
to make it work on your distribution, unless your code is generic
|
||||
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
|
||||
(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
|
||||
`/etc/resolv.conf`, the D-Bus system bus socket or write access to the logging
|
||||
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
|
||||
|
||||
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
|
||||
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
|
||||
|
@ -34,7 +34,7 @@ architecture.
|
||||
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
|
||||
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
|
||||
can work.
|
||||
|
||||
@ -54,5 +54,5 @@ architecture.
|
||||
`/usr/` mounted in.
|
||||
|
||||
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`.
|
||||
|
@ -26,23 +26,23 @@ The Linux kernel provides three relevant userspace APIs to request random data
|
||||
from the kernel's entropy pool:
|
||||
|
||||
* 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
|
||||
and the requested bytes can be provided.
|
||||
|
||||
* 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.
|
||||
|
||||
* Reading from the
|
||||
[`/dev/urandom`](https://man7.org/linux/man-pages/man4/urandom.4.html)
|
||||
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
|
||||
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
|
||||
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.)
|
||||
|
||||
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:
|
||||
|
||||
* 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
|
||||
collected by the journal usually includes the invocation UUID and thus the
|
||||
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 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).
|
||||
|
||||
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
|
||||
truly useful results, you should tweak the runtime configuration of respective
|
||||
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),
|
||||
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
|
||||
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.
|
||||
|
||||
* Debian/Ubuntu based systems enforce the regular expression
|
||||
|
Loading…
Reference in New Issue
Block a user