`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
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
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:
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.
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
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)),
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
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
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`
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
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
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:
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:
`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`,
## 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
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.
## 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
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.
`/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`.
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
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
## 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:
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
projects / thirdparty / systemd.git / commitdiff
