systemd

https://systemd.io
Admin
systemd is a system and service manager for Linux that runs as PID 1, providing service management,...
Tokens:48,549
Snippets:300
Trust Score:9.6
Update:1 week ago
Show doc for...
Tokens:
Raw
### systemd-boot configuration examples

Source: https://systemd.io/BOOT

Example configuration files for systemd-boot: loader.conf sets timeout and default entry pattern; entry files define kernel, initrd, and options. The examples show typical usage with UUIDs and partition UUIDs.

```plaintext
/boot/loader/loader.conf
timeout 3
default 6a9857a393724b7a981ebb5b8495b9ea-*

/boot/loader/entries/6a9857a393724b7a981ebb5b8495b9ea-3.8.0-2.fc19.x86_64.conf
title      Fedora 19 (Rawhide)
version    3.8.0-2.fc19.x86_64
machine-id 6a9857a393724b7a981ebb5b8495b9ea
linux      /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/linux
initrd     /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/initrd
options    root=UUID=f8f83f73-df71-445c-87f7-31f70263b83b quiet

/boot/loader/entries/custom-kernel.conf
title      My kernel
efi        /bzImage
options    root=PARTUUID=084917b7-8be2-4e86-838d-f771a9902e08

/boot/loader/entries/custom-kernel-initrd.conf
title      My kernel with initrd
linux      /bzImage
initrd     /initrd.img
options    root=PARTUUID=084917b7-8be2-4e86-838d-f771a9902e08 quiet
```

--------------------------------

### Compile and Execute take_BSD_lock.c

Source: https://systemd.io/BLOCK_DEVICE_LOCKING

Compile the example with gcc linking libsystemd, then run it on a partition. The first run succeeds, the second fails because the disk is already locked with flock.

```bash
$ gcc -o take_BSD_lock -lsystemd take_BSD_lock.c

$ ./take_BSD_lock /dev/sda1
Successfully took a BSD lock: /dev/sda

$ flock -x /dev/sda ./take_BSD_lock /dev/sda1
Failed to take a BSD lock on /dev/sda: Resource temporarily unavailable

```

--------------------------------

### Delay service start until network-online.target

Source: https://systemd.io/NETWORK_ONLINE

Add these lines to a .service file to delay service start until network-online.target is reached. This target is considered 'up' when the network management software reports it, and it times out after 90 seconds.

```ini
After=network-online.target
Wants=network-online.target

```

--------------------------------

### Compile ResolveHostname example with gcc

Source: https://systemd.io/WRITING_RESOLVER_CLIENTS

Compiles the C source (saved as addrtest.c) into an executable named addrtest, linking against libsystemd via pkg-config.

```bash
gcc addrtest.c -o addrtest -Wall `pkg-config --cflags --libs libsystemd`

```

--------------------------------

### Sysext component example

Source: https://systemd.io/APPSTREAM_BUNDLE

Defines a sysext named 'devel' using class="extension". The software center presents it as a plugin for the OS, updated via systemd-sysupdated's extension:devel target.

```xml
<component type="addon">
	<id>com.example.Devel</id>
	<extends>com.example.OS</extends>
	<name>Development Tools</name>
	<summary>Tools essential to develop Example OS</summary>
	<provides>
		<binary>gcc</binary>
		<binary>g++</binary>
		<binary>make</binary>
		<binary>autoconf</binary>
		<binary>cmake</binary>
		<binary>meson</binary>
		<binary>ninja</binary>
	</provides>
	<developer_name>Example, inc.</developer_name>
	<releases>
		<release version="45" date="2024-01-15" />
		<release version="44" date="2023-12-08" />
		<release version="43" date="2023-11-10" />
	</releases>
	<bundle type="systemd" class="extension">devel</bundle>
</component>
```

--------------------------------

### Host OS sysupdate component example

Source: https://systemd.io/APPSTREAM_BUNDLE

Extends existing appstream metadata for the host OS with a changelog. The empty bundle value for class="sysupdate" indicates the host system, updated via the 'host' target for systemd-sysupdated.

```xml
<component merge="append">
	<id>com.example.OS</id>
	<releases>
		<release version="45" date="2024-01-15" urgency="high">
			<description>
				<p>This release includes various bug fixes and performance improvements</p>
			</description>
		</release>
	</releases>
	<bundle type="systemd" class="sysupdate" />
</component>
```

--------------------------------

### Portable service component example

Source: https://systemd.io/APPSTREAM_BUNDLE

Defines a portable service named 'foobar' using class="portable". It is updated via systemd-sysupdated's portable:foobar target, marked as urgent, and presented with display name, description, and custom icon.

```xml
<component type="service">
	<id>com.example.Foobar</id>
	<name>Foobar Service</name>
	<summary>Service that does foo to bar</summary>
	<icon type="remote">https://example.com/products/foobar/logo.svg</icon>
	<url type="homepage">https://example.com/products/foobar</url>
	<provides>
		<dbus type="system">com.example.Foobar</dbus>
	</provides>
	<developer_name>Example, inc.</developer_name>
	<releases>
		<release version="1.0.1" date="2024-02-16" urgency="critical">
			<description>
				<p>This release fixes a major security vulnerability. Please update ASAP.</p>
			</description>
			<issues>
				<issue type="cve">CVE-2024-28153</issue>
			</issues>
		</release>
		<release version="1.1-beta" date="2024-01-08" type="development" />
		<release version="1.0" date="2023-11-23">
			<description>
				<p>Initial release!</p>
			</description>
		</release>
	</releases>
	<bundle type="systemd" class="portable">foobar</bundle>
</component>
```

--------------------------------

### C Example: lock_whole_disk_from_devname

Source: https://systemd.io/BLOCK_DEVICE_LOCKING

Full C program that takes a BSD lock on the whole disk of a block device using libsystemd. Requires libsystemd version 251 or newer. The main function locks /dev/sda1 and prints success or failure.

```c
/* SPDX-License-Identifier: MIT-0 */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/file.h>
#include <systemd/sd-device.h>
#include <unistd.h>

static inline void closep(int *fd) {
    if (*fd >= 0)
        close(*fd);
}

/**
 * lock_whole_disk_from_devname
 * @devname: devname of a block device, e.g., /dev/sda or /dev/sda1
 * @open_flags: the flags to open the device, e.g., O_RDONLY|O_CLOEXEC|O_NONBLOCK|O_NOCTTY
 * @flock_operation: the operation to call flock, e.g., LOCK_EX|LOCK_NB
 *
 * given the devname of a block device, take a BSD lock of the whole disk
 *
 * Returns: negative errno value on error, or non-negative fd if the lock was taken successfully.
 **/
int lock_whole_disk_from_devname(const char *devname, int open_flags, int flock_operation) {
    __attribute__((cleanup(sd_device_unrefp))) sd_device *dev = NULL;
    sd_device *whole_dev;
    const char *whole_disk_devname, *subsystem, *devtype;
    int r;

    // create a sd_device instance from devname
    r = sd_device_new_from_devname(&dev, devname);
    if (r < 0) {
        errno = -r;
        fprintf(stderr, "Failed to create sd_device: %m\n");
        return r;
    }

    // if the subsystem of dev is block, but its devtype is not disk, find its parent
    r = sd_device_get_subsystem(dev, &subsystem);
    if (r < 0) {
        errno = -r;
        fprintf(stderr, "Failed to get the subsystem: %m\n");
        return r;
    }
    if (strcmp(subsystem, "block") != 0) {
        fprintf(stderr, "%s is not a block device, refusing.\n", devname);
        return -EINVAL;
    }

    r = sd_device_get_devtype(dev, &devtype);
    if (r < 0) {
        errno = -r;
        fprintf(stderr, "Failed to get the devtype: %m\n");
        return r;
    }
    if (strcmp(devtype, "disk") == 0)
        whole_dev = dev;
    else {
        r = sd_device_get_parent_with_subsystem_devtype(dev, "block", "disk", &whole_dev);
        if (r < 0) {
            errno = -r;
            fprintf(stderr, "Failed to get the parent device: %m\n");
            return r;
        }
    }

    // open the whole disk device node
    __attribute__((cleanup(closep))) int fd = sd_device_open(whole_dev, open_flags);
    if (fd < 0) {
        errno = -fd;
        fprintf(stderr, "Failed to open the device: %m\n");
        return fd;
    }

    // get the whole disk devname
    r = sd_device_get_devname(whole_dev, &whole_disk_devname);
    if (r < 0) {
        errno = -r;
        fprintf(stderr, "Failed to get the whole disk name: %m\n");
        return r;
    }

    // take a BSD lock of the whole disk device node
    if (flock(fd, flock_operation) < 0) {
        r = -errno;
        fprintf(stderr, "Failed to take a BSD lock on %s: %m\n", whole_disk_devname);
        return r;
    }

    printf("Successfully took a BSD lock: %s\n", whole_disk_devname);

    // take the fd to avoid automatic cleanup
    int ret_fd = fd;
    fd = -EBADF;
    return ret_fd;
}

int main(int argc, char **argv) {
    if (argc != 2) {
        fprintf(stderr, "Invalid number of parameters.\n");
        return EXIT_FAILURE;
    }

    // try to take an exclusive and nonblocking BSD lock (use O_WRONLY mode to ensure udev
    // rescans the device once the lock is closed)
    __attribute__((cleanup(closep))) int fd =
        lock_whole_disk_from_devname(
            argv[1],
            O_WRONLY|O_CLOEXEC|O_NONBLOCK|O_NOCTTY,
            LOCK_EX|LOCK_NB);

    if (fd < 0)
        return EXIT_FAILURE;

    /**
     * The device is now locked until the return below.
     * Now you can safely manipulate the block device.
     **/

    return EXIT_SUCCESS;
}

```

--------------------------------

### ResolveHostname() C example using sd-bus

Source: https://systemd.io/WRITING_RESOLVER_CLIENTS

C program that calls ResolveHostname() on the system bus, requesting AF_UNSPEC addresses (both A and AAAA) on any interface (index 0). It parses the returned array of (ifindex, family, address) tuples and prints each IP address and the canonical name. Requires libsystemd and a running systemd-resolved.

```c
#include <arpa/inet.h>
#include <netinet/in.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/socket.h>
#include <systemd/sd-bus.h>

int main(int argc, char*argv[]) {
        sd_bus_error error = SD_BUS_ERROR_NULL;
        sd_bus_message *reply = NULL;
        const char *canonical;
        sd_bus *bus = NULL;
        uint64_t flags;
        int r;

        r = sd_bus_open_system(&bus);
        if (r < 0) {
                fprintf(stderr, "Failed to open system bus: %s\n", strerror(-r));
                goto finish;
        }

        r = sd_bus_call_method(bus,
                               "org.freedesktop.resolve1",
                               "/org/freedesktop/resolve1",
                               "org.freedesktop.resolve1.Manager",
                               "ResolveHostname",
                               &error,
                               &reply,
                               "isit",
                               0,                                        /* Network interface index where to look (0 means any) */
                               argc >= 2 ? argv[1] : "www.github.com",   /* Hostname */
                               AF_UNSPEC,                                /* Which address family to look for */
                               UINT64_C(0));                             /* Input flags parameter */
        if (r < 0) {
                fprintf(stderr, "Failed to resolve hostname: %s\n", error.message);
                sd_bus_error_free(&error);
                goto finish;
        }

        r = sd_bus_message_enter_container(reply, 'a', "(iiay)");
        if (r < 0)
                goto parse_failure;

        for (;;) {
                char buf[INET6_ADDRSTRLEN];
                int ifindex, family;
                const void *data;
                size_t length;

                r = sd_bus_message_enter_container(reply, 'r', "iiay");
                if (r < 0)
                        goto parse_failure;
                if (r == 0)  /* Reached end of array */
                        break;
                r = sd_bus_message_read(reply, "ii", &ifindex, &family);
                if (r < 0)
                        goto parse_failure;
                r = sd_bus_message_read_array(reply, 'y', &data, &length);
                if (r < 0)
                        goto parse_failure;
                r = sd_bus_message_exit_container(reply);
                if (r < 0)
                        goto parse_failure;

                printf("Found IP address %s on interface %i.\n", inet_ntop(family, data, buf, sizeof(buf)), ifindex);
        }

        r = sd_bus_message_exit_container(reply);
        if (r < 0)
                goto parse_failure;
        r = sd_bus_message_read(reply, "st", &canonical, &flags);
        if (r < 0)
                goto parse_failure;

        printf("Canonical name is %s\n", canonical);
        goto finish;

parse_failure:
        fprintf(stderr, "Parse failure: %s\n", strerror(-r));

finish:
        sd_bus_message_unref(reply);
        sd_bus_flush_close_unref(bus);
        return r < 0 ? EXIT_FAILURE : EXIT_SUCCESS;
}

```

--------------------------------

### ResolveHostname

Source: https://systemd.io/WRITING_RESOLVER_CLIENTS

Example of resolving a hostname using the systemd-resolved D-Bus API, including input parameters and response parsing.

```APIDOC
## ResolveHostname

### Description
Resolves a hostname to one or more IP addresses using the systemd-resolved D-Bus API. The call takes a network interface index, hostname, address family, and input flags, and returns a list of addresses along with the canonical name and output flags.

### Method
D-Bus method call

### Endpoint
`org.freedesktop.resolve1.Manager.ResolveHostname` on the system bus

### Parameters
#### Input Parameters (in order)
- **ifindex** (int32) - Required - Network interface index where to look (0 means any)
- **hostname** (string) - Required - Hostname to resolve
- **family** (int32) - Required - Address family to look for (e.g., AF_UNSPEC, AF_INET, AF_INET6)
- **flags** (uint64) - Required - Input flags parameter (e.g., 0 for no flags)

### Request Example
```
sd_bus_call_method(bus,
                   "org.freedesktop.resolve1",
                   "/org/freedesktop/resolve1",
                   "org.freedesktop.resolve1.Manager",
                   "ResolveHostname",
                   &error,
                   &reply,
                   "isit",
                   0,
                   "www.github.com",
                   AF_UNSPEC,
                   UINT64_C(0));
```

### Response
#### Success Response
- **addresses** (array of (int32 ifindex, int32 family, array of bytes address)) - List of resolved addresses with their interface index and address family
- **canonical** (string) - Canonical name of the resolved hostname
- **flags** (uint64) - Output flags parameter (e.g., SD_RESOLVED_AUTHENTICATED bit)

#### Response Example
```
printf("Found IP address %s on interface %i.\n", inet_ntop(family, data, buf, sizeof(buf)), ifindex);
printf("Canonical name is %s\n", canonical);
```
```

--------------------------------

### Mask dev-hugepages.mount to disable huge memory page API FS

Source: https://systemd.io/API_FILE_SYSTEMS

Use systemctl mask to disable automatic mounting of the huge memory page API file system. This takes effect starting with the next boot.

```bash
systemctl mask dev-hugepages.mount
```
Tokens:
Raw