title: org.freedesktop.import1(5)

summary: The D\-Bus interface of systemd\-importd

text:
# org.freedesktop.import1(5)

## NAME
org.freedesktop.import1 - The D-Bus interface of systemd-importd

## INTRODUCTION
systemd-importd.service(8) is a system service which may be used to import, export and download disk images. These images can be used by tools such as systemd-nspawn(1) to run local containers. The service is used as the backend for importctl pull-raw, importctl pull-tar and related commands. This page describes the D-Bus interface.

Note that systemd-importd.service(8) is mostly a small companion service for systemd-machined.service(8). Many operations to manipulate local container and VM images are hence available via the systemd-machined D-Bus API, c.f. org.freedesktop.machine1(5).

## THE MANAGER OBJECT
The service exposes the following interfaces on the Manager object on the bus:

```
node /org/freedesktop/import1 {

  interface org.freedesktop.import1.Manager {

    methods:

      ImportTar(in  h fd,

                in  s local_name,

                in  b force,

                in  b read_only,

                out u transfer_id,

                out o transfer_path);

      ImportTarEx(in  h fd,

                  in  s local_name,

                  in  s class,

                  in  t flags,

                  out u transfer_id,

                  out o transfer_path);

      ImportRaw(in  h fd,

                in  s local_name,

                in  b force,

                in  b read_only,

                out u transfer_id,

                out o transfer_path);

      ImportRawEx(in  h fd,

                  in  s local_name,

                  in  s class,

                  in  t flags,

                  out u transfer_id,

                  out o transfer_path);

      ImportFileSystem(in  h fd,

                       in  s local_name,

                       in  b force,

                       in  b read_only,

                       out u transfer_id,

                       out o transfer_path);

      ImportFileSystemEx(in  h fd,

                         in  s local_name,

                         in  s class,

                         in  t flags,

                         out u transfer_id,

                         out o transfer_path);

      ExportTar(in  s local_name,

                in  h fd,

                in  s format,

                out u transfer_id,

                out o transfer_path);

      ExportTarEx(in  s local_name,

                  in  s class,

                  in  h fd,

                  in  s format,

                  in  t flags,

                  out u transfer_id,

                  out o transfer_path);

      ExportRaw(in  s local_name,

                in  h fd,

                in  s format,

                out u transfer_id,

                out o transfer_path);

      ExportRawEx(in  s local_name,

                  in  s class,

                  in  h fd,

                  in  s format,

                  in  t flags,

                  out u transfer_id,

                  out o transfer_path);

      PullTar(in  s url,

              in  s local_name,

              in  s verify_mode,

              in  b force,

              out u transfer_id,

              out o transfer_path);

      PullTarEx(in  s url,

                in  s local_name,

                in  s class,

                in  s verify_mode,

                in  t flags,

                out u transfer_id,

                out o transfer_path);

      PullRaw(in  s url,

              in  s local_name,

              in  s verify_mode,

              in  b force,

              out u transfer_id,

              out o transfer_path);

      PullRawEx(in  s url,

                in  s local_name,

                in  s class,

                in  s verify_mode,

                in  t flags,

                out u transfer_id,

                out o transfer_path);

      ListTransfers(out a(usssdo) transfers);

      ListTransfersEx(in  s class,

                      in  t flags,

                      out a(ussssdo) transfers);

      CancelTransfer(in  u transfer_id);

      ListImages(in  s class,

                 in  t flags,

                 out a(ssssbtttttt) images);

    signals:

      TransferNew(u transfer_id,

                  o transfer_path);

      TransferRemoved(u transfer_id,

                      o transfer_path,

                      s result);

  };

  interface org.freedesktop.DBus.Peer { ... };

  interface org.freedesktop.DBus.Introspectable { ... };

  interface org.freedesktop.DBus.Properties { ... };
};
```

### Methods
ImportTar()/ImportTarEx() and ImportRaw()/ImportRawEx() import a disk image and place it into the image directory. The first argument should be a file descriptor (opened for reading) referring to the tar or raw file to import. It should reference a file on disk, a pipe or a socket. When ImportTar()/ImportTarEx() is used the file descriptor should refer to a tar file, optionally compressed with gzip(1), bzip2(1), or xz(1). systemd-importd will detect the used compression scheme (if any) automatically. When ImportRaw()/ImportRawEx() is used the file descriptor should refer to a raw or qcow2 disk image containing an MBR or GPT disk label, also optionally compressed with gzip, bzip2 or xz. In either case, if the file is specified as a file descriptor on disk, progress information is generated for the import operation (as in that case we know the total size on disk). If a socket or pipe is specified, progress information is not available. The file descriptor argument is followed by a local name for the image. This should be a name suitable as a hostname and will be used to name the imported image below /var/lib/machines/. A tar import is placed as a directory tree or a btrfs(8) subvolume below the image directory under the specified name with no suffix appended. A raw import is placed as a file in the image directory with the .raw suffix appended. In case of ImportTar()/ImportRaw(), if the force argument is true, any pre-existing image with the same name is removed before starting the operation. Otherwise, the operation fails if an image with the same name already exists. The read_only argument controls whether to create a writable or read-only image. In case of ImportTarEx()/ImportRawEx() these boolean flags are provided via a 64bit flags parameter instead, with bit 0 mapping to the force parameter, and bit 1 mapping to read_only. The class parameter specifies the image class, and takes one of "machine", "portable", "sysext", "confext". All four methods return immediately after starting the import, with the import transfer ongoing. They return a pair of transfer identifier and object path, which may be used to retrieve progress information about the transfer or to cancel it. The transfer identifier is a simple numeric identifier, the object path references an org.freedesktop.import1.Transfer object, see below. Listen for a TransferRemoved() signal for the transfer ID in order to detect when a transfer is complete. The returned transfer object is useful to determine the current progress or log output of the ongoing import operation.

ExportTar()/ExportTarEx() and ExportRaw()/ExportRaw() implement the reverse operation, and may be used to export a system image in order to place it in a tar or raw image. They take the machine name to export as their first parameter, followed by a file descriptor (opened for writing) where the tar or raw file will be written. It may either reference a file on disk or a pipe/socket. The third argument specifies in which compression format to write the image. It takes one of "uncompressed", "xz", "bzip2" or "gzip", depending on which compression scheme is required. The image written to the specified file descriptor will be a tar file in case of ExportTar()/ExportTarEx() or a raw disk image in case of ExportRaw()/ExportRawEx(). Note that currently raw disk images may not be exported as tar files, and vice versa. This restriction might be lifted eventually. The method returns a transfer identifier and object path for cancelling or tracking the export operation, similarly to ImportTar()/ImportTarEx() or ImportRaw()/ImportRawEx() as described above. ExportTarEx()/ExportRawEx() expect the image class as additional parameter, as well as a 64bit flags parameter that currently must be specified as zero.

PullTar()/PullTarEx() and PullRaw()/PullRawEx() may be used to download, verify and import a system image from a URL. They take a URL argument which should point to a tar or raw file on the "http://" or "https://" protocols, possibly compressed with xz, bzip2 or gzip. The second argument is a local name for the image. It should be suitable as a hostname, similarly to the matching argument of the ImportTar()/ImportTarEx() and ImportRaw()/ImportRawEx() methods above. The third argument indicates the verification mode for the image. It may be one of "no", "checksum", "signature". "no" turns off any kind of verification of the image; "checksum" looks for a SHA256SUM file next to the downloaded image and verifies any SHA256 hash value in that file against the image; "signature" does the same but also tries to authenticate the SHA256SUM file via gpg(8) first. In case of PullTar()/PullRaw() the last argument indicates whether to replace a possibly pre-existing image with the same local name (if "true"), or whether to fail (if "false"). In case of PullTarEx()/PullRawEx() the last argument is a 64bit flags parameter, where bit 0 controls the "force" flag, bit 1 is a "read_only" flag that controls whether the created image shall be marked read-only, and bit 2 is a "keep_download" flag that indicates whether a pristine, read-only copy of the downloaded image shell be kept, in addition for the local copy of the image. The ..._Ex() variants also expect an image class string (as above). Like the import and export calls above, these calls return a pair of transfer identifier and object path for the ongoing download.

ImportFileSystem()/ImportFileSystemEx() are similar to ImportTar()/ImportTarEx() but import a directory tree. The first argument must refer to a directory file descriptor for the source hierarchy to import.

ListTransfers()/ListTransfersEx() return a list of ongoing import, export or download operations as created with the six calls described above. They return an array of structures which consist of the numeric transfer identifier, a string indicating the operation (one of "import-tar", "import-raw", "export-tar", "export-raw", "pull-tar" or "pull-raw"), a string describing the remote file (in case of download operations this is the source URL, in case of import/export operations this is a short string describing the file descriptor passed in), a string with the local machine image name, the image class (only in case of ListTransfersEx(); one of "machine", "portable", "sysext", "confext"), a progress value between 0.0 (for 0%) and 1.0 (for 100%), as well as the transfer object path.

CancelTransfer() may be used to cancel an ongoing import, export or download operation. Simply specify the transfer identifier to cancel the ongoing operation.

ListImages() returns a list of currently installed images. It takes a image class string and a flags parameter. The image class is either the empty string or specifies one of the four image classes, by which it will then filter. The flags parameter must be zero at this time. It returns an array of items, each describing one image. The item fields are in order: the image class, the local image name, the image type, the image path, the read-only flag, the creation and modification times (in microseconds since the UNIX epoch), as well as the current disk usage in bytes (both overall, and exclusive), as well as any size limit in bytes set on the image (both overall and exclusive).

### Signals
The TransferNew() signal is generated each time a new transfer is started with the import, export or download calls described above. It carries the transfer ID and object path that have just been created.

The TransferRemoved() signal is sent each time a transfer finishes, is canceled or fails. It also carries the transfer ID and object path, followed by a string indicating the result of the operation, which is one of "done" (on success), "canceled" or "failed".

## THE TRANSFER OBJECT

```
node /org/freedesktop/import1/transfer/_1 {

  interface org.freedesktop.import1.Transfer {

    methods:

      Cancel();

    signals:

      LogMessage(u priority,

                 s line);

      ProgressUpdate(d progress);

    properties:

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly u Id = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s Local = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s Remote = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s Type = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s Verify = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly d Progress = ...;

  };

  interface org.freedesktop.DBus.Peer { ... };

  interface org.freedesktop.DBus.Introspectable { ... };

  interface org.freedesktop.DBus.Properties { ... };
};
```

### Methods
The Cancel() method may be used to cancel the transfer. It takes no parameters. This method is pretty much equivalent to the CancelTransfer() method on the Manager interface (see above), but is exposed on the Transfer object itself instead of taking a transfer ID.

### Properties
The Id property exposes the numeric transfer ID of the transfer object.

The Local, Remote and Type properties expose the local container name of this transfer, the remote source (in case of download: the URL, in case of import/export: a string describing the file descriptor passed in), and the type of operation (see the Manager's ListTransfer() method above for an explanation of the possible values).

The Verify property exposes the selected verification setting and is only defined for download operations (see above).

The Progress property exposes the current progress of the transfer as a value between 0.0 and 1.0. To show a progress bar on screen we recommend to query this value in regular intervals, for example every 500 ms or so.

### Signals
The LogMessage() signal is emitted for log messages generated by a transfer. It carries a pair of syslog log level integer and log string.

The ProgressUpdate() signal is emitted in regular intervals when new download progress information is available for a transfer. It carries a double precision floating pointer number between 0.0 and 1.0 indicating the transfer progress.

## EXAMPLES
Example 1. Introspect org.freedesktop.import1.Manager on the bus

```
$ gdbus introspect --system \

  --dest org.freedesktop.import1 \

  --object-path /org/freedesktop/import1
```

Example 2. Introspect org.freedesktop.import1.Transfer on the bus

```
$ gdbus introspect --system \

  --dest org.freedesktop.import1 \

  --object-path /org/freedesktop/import1/transfer/_1
```

## VERSIONING
These D-Bus interfaces follow the usual interface versioning guidelines[1].

## HISTORY

### The Manager Object
ImportTarEx(), ImportRawEx(), ImportFileSystemEx(), ExportTarEx(), ExportRawEx(), PullTarEx(), PullRawEx(), ListTransfersEx(), ListImages() were added in version 256.

### Transfer Objects
ProgressUpdate() was added in version 256.

## SEE ALSO
systemd(1), systemd-importd.service(8), importctl(1)

## NOTES
1.

the usual interface versioning guidelines

https://0pointer.de/blog/projects/versioning-dbus.html


package: systemd-container

title: org.freedesktop.machine1(5)

summary: The D\-Bus interface of systemd\-machined

text:
# org.freedesktop.machine1(5)

## NAME
org.freedesktop.machine1 - The D-Bus interface of systemd-machined

## INTRODUCTION
systemd-machined.service(8) is a system service that keeps track of locally running virtual machines and containers. This page describes the D-Bus interface.

## THE MANAGER OBJECT
The service exposes the following interfaces on the Manager object on the bus:

```
node /org/freedesktop/machine1 {

  interface org.freedesktop.machine1.Manager {

    methods:

      GetMachine(in  s name,

                 out o machine);

      GetImage(in  s name,

               out o image);

      GetMachineByPID(in  u pid,

                      out o machine);

      ListMachines(out a(ssso) machines);

      ListImages(out a(ssbttto) images);

      @org.freedesktop.systemd1.Privileged("true")

      CreateMachine(in  s name,

                    in  ay id,

                    in  s service,

                    in  s class,

                    in  u leader,

                    in  s root_directory,

                    in  a(sv) scope_properties,

                    out o path);

      @org.freedesktop.systemd1.Privileged("true")

      CreateMachineWithNetwork(in  s name,

                               in  ay id,

                               in  s service,

                               in  s class,

                               in  u leader,

                               in  s root_directory,

                               in  ai ifindices,

                               in  a(sv) scope_properties,

                               out o path);

      @org.freedesktop.systemd1.Privileged("true")

      RegisterMachine(in  s name,

                      in  ay id,

                      in  s service,

                      in  s class,

                      in  u leader,

                      in  s root_directory,

                      out o path);

      @org.freedesktop.systemd1.Privileged("true")

      RegisterMachineWithNetwork(in  s name,

                                 in  ay id,

                                 in  s service,

                                 in  s class,

                                 in  u leader,

                                 in  s root_directory,

                                 in  ai ifindices,

                                 out o path);

      UnregisterMachine(in  s name);

      TerminateMachine(in  s id);

      KillMachine(in  s name,

                  in  s whom,

                  in  i signal);

      GetMachineAddresses(in  s name,

                          out a(iay) addresses);

      GetMachineSSHInfo(in  s name,

                        out s ssh_address,

                        out s ssh_private_key_path);

      GetMachineOSRelease(in  s name,

                          out a{ss} fields);

      @org.freedesktop.systemd1.Privileged("true")

      OpenMachinePTY(in  s name,

                     out h pty,

                     out s pty_path);

      OpenMachineLogin(in  s name,

                       out h pty,

                       out s pty_path);

      OpenMachineShell(in  s name,

                       in  s user,

                       in  s path,

                       in  as args,

                       in  as environment,

                       out h pty,

                       out s pty_path);

      BindMountMachine(in  s name,

                       in  s source,

                       in  s destination,

                       in  b read_only,

                       in  b mkdir);

      CopyFromMachine(in  s name,

                      in  s source,

                      in  s destination);

      CopyToMachine(in  s name,

                    in  s source,

                    in  s destination);

      CopyFromMachineWithFlags(in  s name,

                               in  s source,

                               in  s destination,

                               in  t flags);

      CopyToMachineWithFlags(in  s name,

                             in  s source,

                             in  s destination,

                             in  t flags);

      OpenMachineRootDirectory(in  s name,

                               out h fd);

      GetMachineUIDShift(in  s name,

                         out u shift);

      RemoveImage(in  s name);

      RenameImage(in  s name,

                  in  s new_name);

      CloneImage(in  s name,

                 in  s new_name,

                 in  b read_only);

      MarkImageReadOnly(in  s name,

                        in  b read_only);

      GetImageHostname(in  s name,

                       out s hostname);

      GetImageMachineID(in  s name,

                        out ay id);

      GetImageMachineInfo(in  s name,

                          out a{ss} machine_info);

      GetImageOSRelease(in  s name,

                        out a{ss} os_release);

      SetPoolLimit(in  t size);

      SetImageLimit(in  s name,

                    in  t size);

      CleanPool(in  s mode,

                out a(st) images);

      MapFromMachineUser(in  s name,

                         in  u uid_inner,

                         out u uid_outer);

      MapToMachineUser(in  u uid_outer,

                       out s machine_name,

                       out o machine_path,

                       out u uid_inner);

      MapFromMachineGroup(in  s name,

                          in  u gid_inner,

                          out u gid_outer);

      MapToMachineGroup(in  u gid_outer,

                        out s machine_name,

                        out o machine_path,

                        out u gid_inner);

    signals:

      MachineNew(s machine,

                 o path);

      MachineRemoved(s machine,

                     o path);

    properties:

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly s PoolPath = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly t PoolUsage = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly t PoolLimit = ...;

  };

  interface org.freedesktop.DBus.Peer { ... };

  interface org.freedesktop.DBus.Introspectable { ... };

  interface org.freedesktop.DBus.Properties { ... };
};
```

### Methods
GetMachine() may be used to get the machine object path for the machine with the specified name. Similarly, GetMachineByPID() gets the machine object the specified PID belongs to if there is any.

GetImage() may be used to get the image object path of the image with the specified name.

ListMachines() returns an array of all currently registered machines. The structures in the array consist of the following fields: machine name, machine class, an identifier for the service that registered the machine and the machine object path.

ListImages() returns an array of all currently known images. The structures in the array consist of the following fields: image name, type, read-only flag, creation time, modification time, current disk space, and image object path.

CreateMachine() may be used to register a new virtual machine or container with systemd-machined, creating a scope unit for it. It accepts the following arguments: a machine name chosen by the registrar, an optional UUID as a 32 byte array, a string that identifies the service that registers the machine, a class string, the PID of the leader process of the machine, an optional root directory of the container, and an array of additional properties to use for the scope registration. The virtual machine name must be suitable as a hostname, and hence should follow the usual DNS hostname rules, as well as the Linux hostname restrictions. Specifically, only 7 bit ASCII is permitted, a maximum length of 64 characters is enforced, only characters from the set "a-zA-Z0-9-_." are allowed, the name may not begin with a dot, and it may not contain two dots immediately following each other. Container and VM managers should ideally use the hostname used internally in the machine for this parameter. This recommendation is made in order to make the machine name naturally resolvable using nss-mymachines(8). If a container manager needs to embed characters outside of the indicated range, escaping is required, possibly using "_" as the escape character. Another (somewhat natural) option would be to utilize Internet IDNA encoding. The UUID is passed as a 32 byte array or, if no suitable UUID is available, an empty array (zero length) or zeroed out array shall be passed. The UUID should identify the virtual machine/container uniquely and should ideally be the same UUID that /etc/machine-id in the VM/container is initialized from. The service string can be free-form, but it is recommended to pass a short lowercase identifier like "systemd-nspawn", "libvirt-lxc" or similar. The class string should be either "container" or "vm" indicating whether the machine to register is of the respective class. The leader PID should be the host PID of the init process of the container or the encapsulating process of the VM. If the root directory of the container is known and available in the host's hierarchy, it should be passed. Otherwise, pass the empty string instead. Finally, the scope properties are passed as array in the same way as to PID1's StartTransientUnit() method. Calling this method will internally register a transient scope unit for the calling client (utilizing the passed scope_properties) and move the leader PID into it. The method returns an object path for the registered machine object that implements the org.freedesktop.machine1.Machine interface (see below). Also see the New Control Group Interfaces[1] for details about scope units and how to alter resource control settings on the created machine at runtime.

RegisterMachine() is similar to CreateMachine(). However, it only registers a machine and does not create a scope unit for it. Instead, the caller's unit is registered. We recommend to only use this method for container or VM managers that are run multiple times, one instance for each container/VM they manage, and are invoked as system services.

CreateMachineWithNetwork() and RegisterMachineWithNetwork() are similar to CreateMachine() and RegisterMachine() but take an extra argument: an array of network interface indices that point towards the virtual machine or container. The interface indices should reference one or more network interfaces on the host that can be used to communicate with the guest. Commonly, the passed interface index refers to the host side of a "veth" link (in case of containers), a "tun"/"tap" link (in case of VMs), or the host side of a bridge interface that bridges access to the VM/container interfaces. Specifying this information is useful to enable support for link-local IPv6 communication to the machines since the scope field of sockaddr_in6 can be initialized by the specified ifindex. nss-mymachines(8) makes use of this information.

KillMachine() sends a UNIX signal to the machine's processes. As its arguments, it takes a machine name (as originally passed to CreateMachine() or returned by ListMachines()), an identifier that specifies what precisely to send the signal to (either "leader" or "all"), and a numeric UNIX signal integer.

TerminateMachine() terminates a virtual machine, killing its processes. It takes a machine name as its only argument.

GetMachineAddresses() retrieves the IP addresses of a container. This method returns an array of pairs consisting of an address family specifier (AF_INET or AF_INET6) and a byte array containing the addresses. This is only supported for containers that make use of network namespacing.

GetMachineSSHInfo() retrieves the SSH information of a machine. This method returns two strings, the SSH address which can be used to tell SSH where to connect, and the path to the SSH private key required for the connection to succeed.

GetMachineOSRelease() retrieves the OS release information of a container. This method returns an array of key value pairs read from the os-release(5) file in the container and is useful to identify the operating system used in a container.

OpenMachinePTY() allocates a pseudo TTY in the container and returns a file descriptor and its path. This is equivalent to transitioning into the container and invoking posix_openpt(3).

OpenMachineLogin() allocates a pseudo TTY in the container and ensures that a getty login prompt of the container is running on the other end. It returns the file descriptor of the PTY and the PTY path. This is useful for acquiring a pty with a login prompt from the container.

OpenMachineShell() allocates a pseudo TTY in the container, as the specified user, and invokes the executable at the specified path with a list of arguments (starting from argv[0]) and an environment block. It then returns the file descriptor of the PTY and the PTY path.

BindMountMachine() bind mounts a file or directory from the host into the container. Its arguments consist of a machine name, the source directory on the host, the destination directory in the container, and two booleans, one indicating whether the bind mount shall be read-only, the other indicating whether the destination mount point shall be created first, if it is missing.

CopyFromMachine() copies files or directories from a container into the host. It takes a container name, a source directory in the container and a destination directory on the host as arguments. CopyToMachine() does the opposite and copies files from a source directory on the host into a destination directory in the container. CopyFromMachineWithFlags() and CopyToMachineWithFlags() do the same but take an additional flags argument.

RemoveImage() removes the image with the specified name.

RenameImage() renames the specified image.

CloneImage() clones the specified image under a new name. It also takes a boolean argument indicating whether the resulting image shall be read-only or not.

MarkImageReadOnly() toggles the read-only flag of an image.

SetPoolLimit() sets an overall quota limit on the pool of images.

SetImageLimit() sets a per-image quota limit.

MapFromMachineUser(), MapToMachineUser(), MapFromMachineGroup(), and MapToMachineGroup() may be used to map UIDs/GIDs from the host user namespace to a container user namespace or vice versa.

### Signals
MachineNew() and MachineRemoved() are sent whenever a new machine is registered or removed. These signals carry the machine name and the object path to the corresponding org.freedesktop.machine1.Machine interface (see below).

### Properties
PoolPath specifies the file system path where images are written to.

PoolUsage specifies the current usage size of the image pool in bytes.

PoolLimit specifies the size limit of the image pool in bytes.

## MACHINE OBJECTS

```
node /org/freedesktop/machine1/machine/rawhide {

  interface org.freedesktop.machine1.Machine {

    methods:

      Terminate();

      Kill(in  s whom,

           in  i signal);

      GetAddresses(out a(iay) addresses);

      GetSSHInfo(out s ssh_address,

                 out s ssh_private_key_path);

      GetOSRelease(out a{ss} fields);

      GetUIDShift(out u shift);

      OpenPTY(out h pty,

              out s pty_path);

      OpenLogin(out h pty,

                out s pty_path);

      OpenShell(in  s user,

                in  s path,

                in  as args,

                in  as environment,

                out h pty,

                out s pty_path);

      BindMount(in  s source,

                in  s destination,

                in  b read_only,

                in  b mkdir);

      CopyFrom(in  s source,

               in  s destination);

      CopyTo(in  s source,

             in  s destination);

      CopyFromWithFlags(in  s source,

                        in  s destination,

                        in  t flags);

      CopyToWithFlags(in  s source,

                      in  s destination,

                      in  t flags);

      OpenRootDirectory(out h fd);

    properties:

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s Name = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly ay Id = [...];

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly t Timestamp = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly t TimestampMonotonic = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s Service = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s Unit = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly u Leader = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s Class = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s RootDirectory = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly ai NetworkInterfaces = [...];

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly u VSockCID = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s SSHAddress = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s SSHPrivateKeyPath = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly s State = '...';

  };

  interface org.freedesktop.DBus.Peer { ... };

  interface org.freedesktop.DBus.Introspectable { ... };

  interface org.freedesktop.DBus.Properties { ... };
};
```

### Methods
Terminate() and Kill() terminate/kill the machine. These methods take the same arguments as TerminateMachine() and KillMachine() on the Manager interface, respectively.

GetAddresses(), GetSSHInfo() and GetOSRelease() get the IP address, SSH connection and OS release information from the machine. These methods take the same arguments as GetMachineAddresses(), GetMachineSSHInfo() and GetMachineOSRelease() of the Manager interface, respectively.

### Properties
Name is the machine name as it was passed in during registration with CreateMachine() on the manager object.

Id is the machine UUID.

Timestamp and TimestampMonotonic are the realtime and monotonic timestamps when the virtual machines where created in microseconds since the epoch.

Service contains a short string identifying the registering service as passed in during registration of the machine.

Unit is the systemd scope or service unit name for the machine.

Leader is the PID of the leader process of the machine.

Class is the class of the machine and is either the string "vm" (for real VMs based on virtualized hardware) or "container" (for lightweight userspace virtualization sharing the same kernel as the host).

RootDirectory is the root directory of the container if it is known and applicable or the empty string.

NetworkInterfaces contains an array of network interface indices that point towards the container, the VM or the host. For details about this information see the description of CreateMachineWithNetwork() above.

VSockCID is the VSOCK CID of the VM if it is known, or VMADDR_CID_ANY otherwise.

SSHAddress is the address of the VM in a format ssh can understand if it is known or the empty string.

SSHPrivateKeyPath is the path to the SSH private key of the VM if it is known or the empty string.

State is the state of the machine and is one of "opening", "running", or "closing". Note that the state machine is not considered part of the API and states might be removed or added without this being considered API breakage.

## EXAMPLES
Example 1. Introspect org.freedesktop.machine1.Manager on the bus

```
$ gdbus introspect --system \

  --dest org.freedesktop.machine1 \

  --object-path /org/freedesktop/machine1
```

Example 2. Introspect org.freedesktop.machine1.Machine on the bus

```
$ gdbus introspect --system \

  --dest org.freedesktop.machine1 \

  --object-path /org/freedesktop/machine1/machine/rawhide
```

## VERSIONING
These D-Bus interfaces follow the usual interface versioning guidelines[2].

## HISTORY

### The Manager Object
CopyFromMachineWithFlags() and CopyToMachineWithFlags() were added in version 252.

GetMachineSSHInfo() was added in version 256.

### Machine Objects
CopyFromWithFlags() and CopyToWithFlags() were added in version 252.

GetSSHInfo(), VSockCID, SSHAddress and SSHPrivateKeyPath were added in version 256.

## SEE ALSO
systemd(1), systemd-machined.service(8), machinectl(1)

## NOTES
1.

New Control Group Interfaces

https://systemd.io/CONTROL_GROUP_INTERFACE

2.

the usual interface versioning guidelines

https://0pointer.de/blog/projects/versioning-dbus.html


systemd.nspawn

title: systemd.nspawn(5)

summary: Container settings

text:
# systemd.nspawn(5)

## NAME
systemd.nspawn - Container settings

## SYNOPSIS
/etc/systemd/nspawn/machine.nspawn

/run/systemd/nspawn/machine.nspawn

/var/lib/machines/machine.nspawn

## DESCRIPTION
An nspawn container settings file (suffix .nspawn) contains runtime configuration for a local container, and is used by systemd-nspawn(1). Files of this type are named after the containers they define settings for. They are optional, and only required for containers whose execution environment shall differ from the defaults. Files of this type mostly contain settings that may also be set on the systemd-nspawn command line, and make it easier to persistently attach specific settings to specific containers. The syntax of these files is inspired by .desktop files, similarly to other configuration files supported by the systemd project. See systemd.syntax(7) for an overview.

## .NSPAWN FILE DISCOVERY
Files are searched for by appending the .nspawn suffix to the machine name of the container, as specified with the --machine= switch of systemd-nspawn, or derived from the directory or image file name. This file is first searched for in /etc/systemd/nspawn/ and /run/systemd/nspawn/. If found there, the settings are read and all of them take full effect (but may still be overridden by corresponding command line arguments). Otherwise, the file will then be searched for next to the image file or in the immediate parent of the root directory of the container. If the file is found there, only a subset of the settings will take effect however. All settings that possibly elevate privileges or grant additional access to resources of the host (such as files or directories) are ignored. To which options this applies is documented below.

Persistent settings files created and maintained by the administrator (and thus trusted) should be placed in /etc/systemd/nspawn/, while automatically downloaded (and thus potentially untrusted) settings files are placed in /var/lib/machines/ instead (next to the container images), where their security impact is limited. In order to add privileged settings to .nspawn files acquired from the image vendor, it is recommended to copy the settings files into /etc/systemd/nspawn/ and edit them there, so that the privileged options become available. The precise algorithm for how the files are searched and interpreted may be configured with systemd-nspawn's --settings= switch, see systemd-nspawn(1) for details.

## [EXEC] SECTION OPTIONS
Settings files may include an [Exec] section, which carries various execution parameters:

Boot=

Takes a boolean argument, which defaults to off. If enabled, systemd-nspawn will automatically search for an init executable and invoke it. In this case, the specified parameters using Parameters= are passed as additional arguments to the init process. This setting corresponds to the --boot switch on the systemd-nspawn command line. This option may not be combined with ProcessTwo=yes. This option is specified by default in the systemd-nspawn@.service template unit. Added in version 226.

Ephemeral=

Takes a boolean argument, which defaults to off, If enabled, the container is run with a temporary snapshot of its file system that is removed immediately when the container terminates. This is equivalent to the --ephemeral command line switch. See systemd-nspawn(1) for details about the specific options supported. Added in version 240.

ProcessTwo=

Takes a boolean argument, which defaults to off. If enabled, the specified program is run as PID 2. A stub init process is run as PID 1. This setting corresponds to the --as-pid2 switch on the systemd-nspawn command line. This option may not be combined with Boot=yes. Added in version 229.

Parameters=

Takes a whitespace-separated list of arguments. Single ("'") and double (""") quotes may be used around arguments with whitespace. This is either a command line, beginning with the binary name to execute, or – if Boot= is enabled – the list of arguments to pass to the init process. This setting corresponds to the command line parameters passed on the systemd-nspawn command line. Note: Boot=no, Parameters=a b "c c" is the same as systemd-nspawn a b "c c", and Boot=yes, Parameters=b 'c c' is the same as systemd-nspawn --boot b 'c c'.

Added in version 226.

Environment=

Takes an environment variable assignment consisting of key and value, separated by "=". Sets an environment variable for the main process invoked in the container. This setting may be used multiple times to set multiple environment variables. It corresponds to the --setenv= command line switch. Added in version 226.

User=

Takes a UNIX user name. Specifies the user name to invoke the main process of the container as. This user must be known in the container's user database. This corresponds to the --user= command line switch. Added in version 226.

WorkingDirectory=

Selects the working directory for the process invoked in the container. Expects an absolute path in the container's file system namespace. This corresponds to the --chdir= command line switch. Added in version 229.

PivotRoot=

Selects a directory to pivot to / inside the container when starting up. Takes a single path, or a pair of two paths separated by a colon. Both paths must be absolute, and are resolved in the container's file system namespace. This corresponds to the --pivot-root= command line switch. Added in version 233.

Capability=, DropCapability=

Takes a space-separated list of Linux process capabilities (see capabilities(7) for details). The Capability= setting specifies additional capabilities to pass on top of the default set of capabilities. The DropCapability= setting specifies capabilities to drop from the default set. These settings correspond to the --capability= and --drop-capability= command line switches. Note that Capability= is a privileged setting, and only takes effect in .nspawn files in /etc/systemd/nspawn/ and /run/system/nspawn/ (see above). On the other hand, DropCapability= takes effect in all cases. If the special value "all" is passed, all capabilities are retained (or dropped). These settings change the bounding set of capabilities which also limits the ambient capabilities as given with the AmbientCapability=.

Added in version 226.

AmbientCapability=

Takes a space-separated list of Linux process capabilities (see capabilities(7) for details). The AmbientCapability= setting specifies capabilities which will be passed to the started program in the inheritable and ambient capability sets. This will grant these capabilities to this process. This setting correspond to the --ambient-capability= command line switch. The value "all" is not supported for this setting.

The setting of AmbientCapability= must be covered by the bounding set settings which were established by Capability= and DropCapability=.

Note that AmbientCapability= is a privileged setting (see above).

Added in version 248.

NoNewPrivileges=

Takes a boolean argument that controls the PR_SET_NO_NEW_PRIVS flag for the container payload. This is equivalent to the --no-new-privileges= command line switch. See systemd-nspawn(1) for details. Added in version 239.

KillSignal=

Specify the process signal to send to the container's PID 1 when nspawn itself receives SIGTERM, in order to trigger an orderly shutdown of the container. Defaults to SIGRTMIN+3 if Boot= is used (on systemd-compatible init systems SIGRTMIN+3 triggers an orderly shutdown). For a list of valid signals, see signal(7). Added in version 230.

Personality=

Configures the kernel personality for the container. This is equivalent to the --personality= switch. Added in version 226.

MachineID=

Configures the 128-bit machine ID (UUID) to pass to the container. This is equivalent to the --uuid= command line switch. This option is privileged (see above). Added in version 226.

PrivateUsers=

Configures support for usernamespacing. This is equivalent to the --private-users= command line switch, and takes the same options. This option is privileged (see above). This option is the default if the systemd-nspawn@.service template unit file is used. Added in version 230.

NotifyReady=

Configures support for notifications from the container's init process. This is equivalent to the --notify-ready= command line switch, and takes the same parameters. See systemd-nspawn(1) for details about the specific options supported. Added in version 231.

SystemCallFilter=

Configures the system call filter applied to containers. This is equivalent to the --system-call-filter= command line switch, and takes the same list parameter. See systemd-nspawn(1) for details. Added in version 235.

LimitCPU=, LimitFSIZE=, LimitDATA=, LimitSTACK=, LimitCORE=, LimitRSS=, LimitNOFILE=, LimitAS=, LimitNPROC=, LimitMEMLOCK=, LimitLOCKS=, LimitSIGPENDING=, LimitMSGQUEUE=, LimitNICE=, LimitRTPRIO=, LimitRTTIME=

Configures various types of resource limits applied to containers. This is equivalent to the --rlimit= command line switch, and takes the same arguments. See systemd-nspawn(1) for details. Added in version 239.

OOMScoreAdjust=

Configures the OOM score adjustment value. This is equivalent to the --oom-score-adjust= command line switch, and takes the same argument. See systemd-nspawn(1) for details. Added in version 239.

CPUAffinity=

Configures the CPU affinity. This is equivalent to the --cpu-affinity= command line switch, and takes the same argument. See systemd-nspawn(1) for details. Added in version 239.

Hostname=

Configures the kernel hostname set for the container. This is equivalent to the --hostname= command line switch, and takes the same argument. See systemd-nspawn(1) for details. Added in version 239.

ResolvConf=

Configures how /etc/resolv.conf in the container shall be handled. This is equivalent to the --resolv-conf= command line switch, and takes the same argument. See systemd-nspawn(1) for details. Added in version 239.

Timezone=

Configures how /etc/localtime in the container shall be handled. This is equivalent to the --timezone= command line switch, and takes the same argument. See systemd-nspawn(1) for details. Added in version 239.

LinkJournal=

Configures how to link host and container journal setups. This is equivalent to the --link-journal= command line switch, and takes the same parameter. See systemd-nspawn(1) for details. Added in version 239.

SuppressSync=

Configures whether to suppress disk synchronization for the container payload. This is equivalent to the --suppress-sync= command line switch, and takes the same parameter. See systemd-nspawn(1) for details. Added in version 250.

## [FILES] SECTION OPTIONS
Settings files may include a [Files] section, which carries various parameters configuring the file system of the container:

ReadOnly=

Takes a boolean argument, which defaults to off. If specified, the container will be run with a read-only file system. This setting corresponds to the --read-only command line switch. Added in version 226.

Volatile=

Takes a boolean argument, or the special value "state". This configures whether to run the container with volatile state and/or configuration. This option is equivalent to --volatile=, see systemd-nspawn(1) for details about the specific options supported. Added in version 226.

Bind=, BindReadOnly=

Adds a bind mount from the host into the container. Takes a single path, a pair of two paths separated by a colon, or a triplet of two paths plus an option string separated by colons. This option may be used multiple times to configure multiple bind mounts. This option is equivalent to the command line switches --bind= and --bind-ro=, see systemd-nspawn(1) for details about the specific options supported. This setting is privileged (see above). Added in version 226.

BindUser=

Binds a user from the host into the container. This option is equivalent to the command line switch --bind-user=, see systemd-nspawn(1) for details about the specific options supported. This setting is privileged (see above). Added in version 249.

TemporaryFileSystem=

Adds a "tmpfs" mount to the container. Takes a path or a pair of path and option string, separated by a colon. This option may be used multiple times to configure multiple "tmpfs" mounts. This option is equivalent to the command line switch --tmpfs=, see systemd-nspawn(1) for details about the specific options supported. This setting is privileged (see above). Added in version 226.

Inaccessible=

Masks the specified file or directory in the container, by over-mounting it with an empty file node of the same type with the most restrictive access mode. Takes a file system path as argument. This option may be used multiple times to mask multiple files or directories. This option is equivalent to the command line switch --inaccessible=, see systemd-nspawn(1) for details about the specific options supported. This setting is privileged (see above). Added in version 242.

Overlay=, OverlayReadOnly=

Adds an overlay mount point. Takes a colon-separated list of paths. This option may be used multiple times to configure multiple overlay mounts. This option is equivalent to the command line switches --overlay= and --overlay-ro=, see systemd-nspawn(1) for details about the specific options supported. This setting is privileged (see above). Added in version 233.

PrivateUsersOwnership=

Configures whether the ownership of the files and directories in the container tree shall be adjusted to the UID/GID range used, if necessary and user namespacing is enabled. This is equivalent to the --private-users-ownership= command line switch. This option is privileged (see above). Added in version 249.

## [NETWORK] SECTION OPTIONS
Settings files may include a [Network] section, which carries various parameters configuring the network connectivity of the container:

Private=

Takes a boolean argument, which defaults to off. If enabled, the container will run in its own network namespace and not share network interfaces and configuration with the host. This setting corresponds to the --private-network command line switch. Added in version 226.

VirtualEthernet=

Takes a boolean argument. Configures whether to create a virtual Ethernet connection ("veth") between host and the container. This setting implies Private=yes. This setting corresponds to the --network-veth command line switch. This option is privileged (see above). This option is the default if the systemd-nspawn@.service template unit file is used. Added in version 226.

VirtualEthernetExtra=

Takes a colon-separated pair of interface names. Configures an additional virtual Ethernet connection ("veth") between host and the container. The first specified name is the interface name on the host, the second the interface name in the container. The latter may be omitted in which case it is set to the same name as the host side interface. This setting implies Private=yes. This setting corresponds to the --network-veth-extra= command line switch, and may be used multiple times. It is independent of VirtualEthernet=. Note that this option is unrelated to the Bridge= setting below, and thus any connections created this way are not automatically added to any bridge device on the host side. This option is privileged (see above). Added in version 228.

Interface=

Takes a space-separated list of interfaces to add to the container. The interface object is defined either by a single interface name, referencing the name on the host, or a colon-separated pair of interfaces, in which case the first one references the name on the host, and the second one the name in the container. This option corresponds to the --network-interface= command line switch and implies Private=yes. This option is privileged (see above). Added in version 226.

MACVLAN=, IPVLAN=

Takes a space-separated list of interfaces to add MACLVAN or IPVLAN interfaces to, which are then added to the container. The interface object is defined either by a single interface name, referencing the name on the host, or a colon-separated pair of interfaces, in which case the first one references the name on the host, and the second one the name in the container. These options correspond to the --network-macvlan= and --network-ipvlan= command line switches and imply Private=yes. These options are privileged (see above). Added in version 226.

Bridge=

Takes an interface name. This setting implies VirtualEthernet=yes and Private=yes and has the effect that the host side of the created virtual Ethernet link is connected to the specified bridge interface. This option corresponds to the --network-bridge= command line switch. This option is privileged (see above). Added in version 226.

Zone=

Takes a network zone name. This setting implies VirtualEthernet=yes and Private=yes and has the effect that the host side of the created virtual Ethernet link is connected to an automatically managed bridge interface named after the passed argument, prefixed with "vz-". This option corresponds to the --network-zone= command line switch. This option is privileged (see above). Added in version 230.

Port=

Exposes a TCP or UDP port of the container on the host. This option corresponds to the --port= command line switch, see systemd-nspawn(1) for the precise syntax of the argument this option takes. This option is privileged (see above). Added in version 226.

## SEE ALSO
systemd(1), systemd-nspawn(1), systemd.directives(7)


coredump.conf

package: systemd-coredump

title: coredump.conf(5)

summary: Core dump storage configuration files

text:
# coredump.conf(5)

## NAME
coredump.conf, coredump.conf.d - Core dump storage configuration files

## SYNOPSIS
/etc/systemd/coredump.conf

/run/systemd/coredump.conf

/usr/local/lib/systemd/coredump.conf

/usr/lib/systemd/coredump.conf

/etc/systemd/coredump.conf.d/*.conf

/run/systemd/coredump.conf.d/*.conf

/usr/local/lib/systemd/coredump.conf.d/*.conf

/usr/lib/systemd/coredump.conf.d/*.conf

## DESCRIPTION
These files configure the behavior of systemd-coredump(8), a handler for core dumps invoked by the kernel. Whether systemd-coredump is used is determined by the kernel's kernel.core_pattern sysctl(8) setting. See systemd-coredump(8) and core(5) pages for the details.

## CONFIGURATION DIRECTORIES AND PRECEDENCE
The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults. The main configuration file is loaded from one of the listed directories in order of priority, only the first file found is used: /etc/systemd/, /run/systemd/, /usr/local/lib/systemd/ [1], /usr/lib/systemd/. The vendor version of the file contains commented out entries showing the defaults as a guide to the administrator. Local overrides can also be created by creating drop-ins, as described below. The main configuration file can also be edited for this purpose (or a copy in /etc/ if it is shipped under /usr/), however using drop-ins for local configuration is recommended over modifications to the main configuration file.

In addition to the main configuration file, drop-in configuration snippets are read from /usr/lib/systemd/*.conf.d/, /usr/local/lib/systemd/*.conf.d/, and /etc/systemd/*.conf.d/. Those drop-ins have higher precedence and override the main configuration file. Files in the *.conf.d/ configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files.

When packages need to customize the configuration, they can install drop-ins under /usr/. Files in /etc/ are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages. Drop-ins have to be used to override package drop-ins, since the main configuration file has lower precedence. It is recommended to prefix all filenames in those subdirectories with a two-digit number and a dash, to simplify the ordering. This also defines a concept of drop-in priorities to allow OS vendors to ship drop-ins within a specific range lower than the range used by users. This should lower the risk of package drop-ins overriding accidentally drop-ins defined by users. It is recommended to use the range 10-40 for drop-ins in /usr/ and the range 60-90 for drop-ins in /etc/ and /run/, to make sure that local and transient drop-ins take priority over drop-ins shipped by the OS vendor.

To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to /dev/null in the configuration directory in /etc/, with the same filename as the vendor configuration file.

## OPTIONS
All options are configured in the [Coredump] section:

Storage=

Controls where to store cores. One of "none", "external", and "journal". When "none", the core dumps may be logged (including the backtrace if possible), but not stored permanently. When "external" (the default), cores will be stored in /var/lib/systemd/coredump/. When "journal", cores will be stored in the journal and rotated following normal journal rotation patterns. When cores are stored in the journal, they might be compressed following journal compression settings, see journald.conf(5). When cores are stored externally, they will be compressed by default, see below.

Note that in order to process a coredump (i.e. extract a stack trace) the core must be written to disk first. Thus, unless ProcessSizeMax= is set to 0 (see below), the core will be written to /var/lib/systemd/coredump/ either way (under a temporary filename, or even in an unlinked file), Storage= thus only controls whether to leave it there even after it was processed.

Added in version 215.

Compress=

Controls compression for external storage. Takes a boolean argument, which defaults to "yes". Added in version 215.

ProcessSizeMax=

The maximum size in bytes of a core which will be processed. Core dumps exceeding this size may be stored, but the stack trace will not be generated. Like other sizes in this same config file, the usual suffixes to the base of 1024 are allowed (B, K, M, G, T, P, and E). Defaults to 1G on 32-bit systems, 32G on 64-bit systems. Setting Storage=none and ProcessSizeMax=0 disables all coredump handling except for a log entry.

Added in version 215.

EnterNamespace=

For processes belonging to a PID namespace, controls whether systemd-coredump(8) shall attempt to process core dumps on the host, using debug information from the file system hierarchy (i.e. the mount namespace) of the process that crashed. Access to the process' file system hierarchy might be necessary to generate a fully symbolized backtrace. If set to "yes", systemd-coredump will obtain the tree of mounts from the crashing process' mount namespace and will try to generate the stack trace in host context using the debug information of binaries and libraries contained in the crashing process' hierarchy. Defaults to "no", i.e. no attempt is made to acquire external debug information from the process' mount namespace, in order to maximize security. This option has no effect on processes that are part of the host's PID namespace. Note that the coredump of the namespaced process is still saved in /var/lib/systemd/coredump/ on the host even if EnterNamespace= is set to "no" (subject to Storage=).

Note that EnterNamespace= only has an effect if a core dump is generated by a container whose unit does not have CoredumpReceive= enabled.

Note that it's typically preferable to let containers and other namespace-based sandboxes process their own coredumps, if possible, for best security. This may be enabled on the container's unit via the CoredumpReceive= setting, see systemd.resource-control(5) for details.

Added in version 257.

ExternalSizeMax=, JournalSizeMax=

The maximum (compressed or uncompressed) size in bytes of a coredump to be saved in separate files on disk (default: 1G on 32-bit systems, 32G on 64-bit systems) or in the journal (default: 767M). Note that the journal service enforces a hard limit on journal log records of 767M, and will ignore larger submitted log records. Hence, JournalSizeMax= may be lowered relative to the default, but not increased. Unit suffixes are allowed just as in ProcessSizeMax=. ExternalSizeMax=infinity sets the core size to unlimited.

Added in version 215.

MaxUse=, KeepFree=

Enforce limits on the disk space, specified in bytes, taken up by externally stored core dumps. Unit suffixes are allowed just as in ProcessSizeMax=. MaxUse= makes sure that old core dumps are removed as soon as the total disk space taken up by core dumps grows beyond this limit (defaults to 10% of the total disk size). KeepFree= controls how much disk space to keep free at least (defaults to 15% of the total disk size). Note that the disk space used by core dumps might temporarily exceed these limits while core dumps are processed. Note that old core dumps are also removed based on time via systemd-tmpfiles(8). Set either value to 0 to turn off size-based cleanup. Added in version 215.

The defaults for all values are listed as comments in the template /etc/systemd/coredump.conf file that is installed by default.

## SEE ALSO
systemd-journald.service(8), coredumpctl(1), systemd-tmpfiles(8)

## NOTES
1.

💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If /usr/local/ is a separate partition, it may not be available during early boot, and must not be used for configuration.


homed.conf

package: systemd-homed

title: homed.conf(5)

text:
# homed.conf(5)

## NAME
homed.conf, homed.conf.d - Home area/user account manager configuration files

## SYNOPSIS
/etc/systemd/homed.conf

/run/systemd/homed.conf

/usr/local/lib/systemd/homed.conf

/usr/lib/systemd/homed.conf

/etc/systemd/homed.conf.d/*.conf

/run/systemd/homed.conf.d/*.conf

/usr/local/lib/systemd/homed.conf.d/*.conf

/usr/lib/systemd/homed.conf.d/*.conf

## DESCRIPTION
These configuration files control default parameters for home areas/user accounts created and managed by systemd-homed.service(8).

## CONFIGURATION DIRECTORIES AND PRECEDENCE
The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults. The main configuration file is loaded from one of the listed directories in order of priority, only the first file found is used: /etc/systemd/, /run/systemd/, /usr/local/lib/systemd/ [1], /usr/lib/systemd/. The vendor version of the file contains commented out entries showing the defaults as a guide to the administrator. Local overrides can also be created by creating drop-ins, as described below. The main configuration file can also be edited for this purpose (or a copy in /etc/ if it is shipped under /usr/), however using drop-ins for local configuration is recommended over modifications to the main configuration file.

In addition to the main configuration file, drop-in configuration snippets are read from /usr/lib/systemd/*.conf.d/, /usr/local/lib/systemd/*.conf.d/, and /etc/systemd/*.conf.d/. Those drop-ins have higher precedence and override the main configuration file. Files in the *.conf.d/ configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files.

When packages need to customize the configuration, they can install drop-ins under /usr/. Files in /etc/ are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages. Drop-ins have to be used to override package drop-ins, since the main configuration file has lower precedence. It is recommended to prefix all filenames in those subdirectories with a two-digit number and a dash, to simplify the ordering. This also defines a concept of drop-in priorities to allow OS vendors to ship drop-ins within a specific range lower than the range used by users. This should lower the risk of package drop-ins overriding accidentally drop-ins defined by users. It is recommended to use the range 10-40 for drop-ins in /usr/ and the range 60-90 for drop-ins in /etc/ and /run/, to make sure that local and transient drop-ins take priority over drop-ins shipped by the OS vendor.

To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to /dev/null in the configuration directory in /etc/, with the same filename as the vendor configuration file.

## OPTIONS
The following options are available in the [Home] section:

DefaultStorage=

The default storage to use for home areas. Takes one of "luks", "fscrypt", "directory", "subvolume", "cifs". For details about these options, see homectl(1). If not configured or assigned the empty string, the default storage is automatically determined: if not running in a container environment and /home/ is not itself encrypted, defaults to "luks". Otherwise, defaults to "subvolume" if /home/ is on a btrfs file system, and "directory" otherwise. Note that the storage selected on the homectl command line always takes precedence. Added in version 246.

DefaultFileSystemType=

When using "luks" as storage (see above), selects the default file system to use inside the user's LUKS volume. Takes one of "btrfs", "ext4" or "xfs". If not specified, defaults to "btrfs". This setting has no effect if a different storage mechanism is used. The file system type selected on the homectl command line always takes precedence. Added in version 246.

## SEE ALSO
systemd(1), systemd-homed.service(8)

## NOTES
1.

💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If /usr/local/ is a separate partition, it may not be available during early boot, and must not be used for configuration.


title: org.freedesktop.home1(5)

summary: The D\-Bus interface of systemd\-homed

text:
# org.freedesktop.home1(5)

## NAME
org.freedesktop.home1 - The D-Bus interface of systemd-homed

## INTRODUCTION
systemd-homed.service(8) is a system service which may be used to create, remove, change or inspect home areas. This page describes the D-Bus interface.

## THE MANAGER OBJECT
The service exposes the following interfaces on the Manager object on the bus:

```
node /org/freedesktop/home1 {

  interface org.freedesktop.home1.Manager {

    methods:

      GetHomeByName(in  s user_name,

                    out u uid,

                    out s home_state,

                    out u gid,

                    out s real_name,

                    out s home_directory,

                    out s shell,

                    out o bus_path);

      GetHomeByUID(in  u uid,

                   out s user_name,

                   out s home_state,

                   out u gid,

                   out s real_name,

                   out s home_directory,

                   out s shell,

                   out o bus_path);

      GetUserRecordByName(in  s user_name,

                          out s user_record,

                          out b incomplete,

                          out o bus_path);

      GetUserRecordByUID(in  u uid,

                         out s user_record,

                         out b incomplete,

                         out o bus_path);

      ListHomes(out a(susussso) home_areas);

      ActivateHome(in  s user_name,

                   in  s secret);

      ActivateHomeIfReferenced(in  s user_name,

                               in  s secret);

      @org.freedesktop.systemd1.Privileged("true")

      DeactivateHome(in  s user_name);

      RegisterHome(in  s user_record);

      UnregisterHome(in  s user_name);

      CreateHome(in  s user_record);

      CreateHomeEx(in  s user_record,

                   in  a{sh} blobs,

                   in  t flags);

      RealizeHome(in  s user_name,

                  in  s secret);

      RemoveHome(in  s user_name);

      @org.freedesktop.systemd1.Privileged("true")

      FixateHome(in  s user_name,

                 in  s secret);

      AuthenticateHome(in  s user_name,

                       in  s secret);

      UpdateHome(in  s user_record);

      UpdateHomeEx(in  s user_record,

                   in  a{sh} blobs,

                   in  t flags);

      ResizeHome(in  s user_name,

                 in  t size,

                 in  s secret);

      ChangePasswordHome(in  s user_name,

                         in  s new_secret,

                         in  s old_secret);

      @org.freedesktop.systemd1.Privileged("true")

      LockHome(in  s user_name);

      @org.freedesktop.systemd1.Privileged("true")

      UnlockHome(in  s user_name,

                 in  s secret);

      AcquireHome(in  s user_name,

                  in  s secret,

                  in  b please_suspend,

                  out h send_fd);

      @org.freedesktop.systemd1.Privileged("true")

      RefHome(in  s user_name,

              in  b please_suspend,

              out h send_fd);

      @org.freedesktop.systemd1.Privileged("true")

      RefHomeUnrestricted(in  s user_name,

                          in  b please_suspend,

                          out h send_fd);

      @org.freedesktop.systemd1.Privileged("true")

      ReleaseHome(in  s user_name);

      @org.freedesktop.systemd1.Privileged("true")

      LockAllHomes();

      @org.freedesktop.systemd1.Privileged("true")

      DeactivateAllHomes();

      @org.freedesktop.systemd1.Privileged("true")

      Rebalance();

    properties:

      readonly a(sso) AutoLogin = [...];

  };

  interface org.freedesktop.DBus.Peer { ... };

  interface org.freedesktop.DBus.Introspectable { ... };

  interface org.freedesktop.DBus.Properties { ... };
};
```

### Methods
GetHomeByName() returns basic user information (a minimal subset of the full user record), provided a user name. The information supplied more or less matches what getpwnam(3) returns: the numeric UID and GID, the real name, home directory and shell. In addition it returns a state identifier describing the state the user's home directory is in, as well as a bus path referring to the bus object encapsulating the user record and home directory. This object implements the org.freedesktop.home1.Home interface documented below. This method, and most others in this interface that take user names, will try to use the caller's home area if the specified user name is an empty string.

GetHomeByUID() is similar to GetHomeByName() but acquires the information based on the numeric UID of the user.

GetUserRecordByName() is also similar to GetHomeByName() but returns the full JSON user record data instead of the broken down records. An additional returned boolean indicates whether the record is complete or not. A record is considered complete when its "privileged" section is included, and incomplete if it was removed (see JSON User Records[1] for details about the various sections of a user record). Generally, only privileged clients and clients running under the identity of the user itself get access to the "privileged" section and will thus see complete records.

GetUserRecordByUID() is similar to GetUserRecordByName() but returns the user record matching the specified numeric UID.

ListHomes() returns an array of all locally managed users. The array contains the same fields GetHomeByName() returns: user name, numeric UID, state, numeric GID, real name, home directory, shell and bus path of the matching bus object.

ActivateHome() activates (i.e. mounts) the home directory of the specified user. The second argument shall contain a user record consisting only of a "secret" section (all other sections should be stripped, see JSON User Records[1] for details), and should contain only the secret credentials necessary for unlocking the home directory. Typically a client would invoke this function first with an entirely empty record (which is possibly sufficient if single-factor authentication with a plugged-in security token is configured), and would then retry with a record populated with more information, depending on the returned error code, in case more credentials are necessary. This function is synchronous and returns only after the home directory was fully activated (or the operation failed), which might take some time. Clients must be prepared for that, and typically should extend the D-Bus method call timeout accordingly. This method is equivalent to the Activate() method on the org.freedesktop.home1.Home interface documented below, but may be called on the manager object and takes a user name as additional argument, instead.

ActivateHomeIfReferenced() is identical to ActivateHome(). However, the call only succeeds if the home directory is currently referenced. Useful in conjunction with RefHomeUnrestricted(), which allows creating a reference to a home directory even if the home directory is not active.

DeactivateHome() deactivates (i.e. unmounts) the home directory of the specified user. It is equivalent to the Deactivate() method on the org.freedesktop.home1.Home interface documented below.

RegisterHome() registers a new home directory locally. It receives the JSON user record as only argument (which typically excludes the "secret" section). Registering a home directory just makes the user record known to the system, it does not create a home directory or such (which is expected to exist already, or created later). This operation is useful to register home directories locally that are not located where systemd-homed.service would find them automatically.

UnregisterHome() unregisters an existing home directory. It takes a user name as argument and undoes what RegisterHome() does. It does not attempt to remove the home directory itself, it just unregisters it with the local system. Note that if the home directory is placed where systemd-homed.service looks for home directories anyway this call will only undo fixation (see below), but the record will remain known to systemd-homed.service and be listed among known records. Since the user record is embedded into the home directory this operation generally does not discard data belonging to the user or their record. This method is equivalent to Unregister() on the org.freedesktop.home1.Home interface.

CreateHome() registers and creates a new home directory. This takes a fully specified JSON user record as argument (including the "secret" section). This registers the user record locally and creates a home directory matching it, depending on the settings specified in the record in combination with local configuration.

CreateHomeEx() is like CreateHome(), but it allows the home directory to be created with a pre-populated blob directory (see User Record Blob Directories[2] for more info). This can be done via the dictionary passed as the blobs argument to this method: the values are open file descriptors to regular files, and the keys are the filenames that should contain their respective file's data in the blob directory. Note that for security reasons, the file descriptors passed into this method must have enough privileges to read their target file and thus cannot be "O_PATH"; this is done to ensure the caller is actually permitted to read the file they are asking to publish in the blob directories. If the user record passed as the first argument contains a "blobManifest" field it will be enforced; otherwise, a "blobManifest" field will be generated and inserted into the record. The flags argument may be used for future expansion, but for now pass 0.

RealizeHome() creates a home directory whose user record is already registered locally. This takes a user name plus a user record consisting only of the "secret" section. Invoking RegisterHome() followed by RealizeHome() is mostly equivalent to calling CreateHome(), except that the latter combines the two in atomic fashion. This method is equivalent to Realize() on the org.freedesktop.home1.Home interface.

RemoveHome() unregisters a user record locally, and removes the home directory belonging to it, if it is accessible. It takes a user name as argument. This method is equivalent to Remove() on the org.freedesktop.home1.Home interface.

FixateHome() "fixates" an automatically discovered home directory. systemd-homed.service automatically discovers home directories dropped in our plugged in and adds them to the runtime list of user records it manages. A user record discovered that way may be "fixated", in which case it is copied out of the home directory, onto persistent storage, to fixate the UID/GID assignment of the record, and extract additional (typically previously encrypted) user record data from the home directory. A home directory mus be fixated before it can be logged into. This method call takes a user name and a JSON user record consisting only of the "secret" section as argument. This method is equivalent to Fixate() on the org.freedesktop.home1.Home interface.

AuthenticateHome() checks passwords or other authentication credentials associated with the home directory. It takes a user name and a JSON user record consisting only of the "secret" section as argument. Note that many of the other method calls authenticate the user first, in order to execute some other operation. This method call only authenticates and executes no further operation. Like ActivateHome() it is usually first invoked with an empty JSON user record, which is then populated for subsequent tries with additional authentication data supplied. This method is equivalent to Authenticate() on the org.freedesktop.home1.Home interface.

UpdateHome() updates a locally registered user record. Takes a fully specified JSON user record as argument (possibly including the "secret" section). A user with a matching name and realm must be registered locally already, and the last change timestamp of the newly supplied record must be newer than the previously existing user record. Note this operation updates the user record only, it does not propagate passwords/authentication tokens from the user record to the storage back-end, or resizes the storage back-end. Typically a home directory is first updated, and then the password of the underlying storage updated using ChangePasswordHome() as well as the storage resized using ResizeHome(). This method is equivalent to Update() on the org.freedesktop.home1.Home interface.

UpdateHomeEx() is like UpdateHome(), but it allows for changes to the blob directory (see User Record Blob Directories[2] for more info). The blobs argument works in the same way as CreateHomeEx(), so check there for details. The new blob directory contents passed into this method will completely replace the user's existing blob directory. The flags argument can be used to further customize the behavior of this method via flags defined as follows:

```
#define SD_HOMED_UPDATE_OFFLINE (UINT64_C(1) << 0)
```

When SD_HOMED_UPDATE_OFFLINE (0x01) is set, no attempt is made to update the copies of the user record and blob directory that are embedded into the home directory. Changes will be stored, however, and may be propagated into the home directory the next time it is reconciled (most likely when the user next logs in). Note that any changes made with this flag set may be lost if the home area has a newer record, which can happen if the home area is updated on another machine after this method call. This method is equivalent to UpdateEx() on the org.freedesktop.home1.Home interface.

ResizeHome() resizes the storage associated with a user record. Takes a user name, a disk size in bytes, and optionally a user record consisting only of the "secret" section as arguments. If the size is specified as UINT64_MAX the storage is resized to the size already specified in the user record. Typically, if the user record is updated using UpdateHome() above this is used to propagate the size configured there-in down to the underlying storage back-end. This method is equivalent to Resize() on the org.freedesktop.home1.Home interface.

ChangePasswordHome() changes the passwords/authentication tokens of a home directory. Takes a user name, and two JSON user record objects, each consisting only of the "secret" section, for the old and for the new passwords/authentication tokens. If the user record with the new passwords/authentication token data is specified as empty the existing user record's settings are propagated down to the home directory storage. This is typically used after a user record is updated using UpdateHome() in order to propagate the secrets/authentication tokens down to the storage. Background: depending on the backend the user's authentication credentials are stored at multiple places: the user record kept on the host, the user record kept in the home directory and the encrypted LUKS volume slot. If the home directory is used on a different machined temporarily, and the password is changed there, and then is moved back to the original host, the passwords of the three might get out of sync. By issuing ChangePasswordHome() the three locations are updated to match the newest information. This method is equivalent to ChangePassword() on the org.freedesktop.home1.Home interface.

LockHome() temporarily suspends access to a home directory, flushing out any cryptographic keys from memory. This is only supported on some back-ends, and is usually done during system suspend, in order to effectively secure home directories while the system is sleeping. Takes a user name as single argument. If an application attempts to access a home directory while it is locked it will typically freeze until the home directory is unlocked again. This method is equivalent to Lock() on the org.freedesktop.home1.Home interface.

UnlockHome() undoes the effect of LockHome(). Takes a user name and a user record consisting only of the "secret" section as arguments. This method is equivalent to Unlock() on the org.freedesktop.home1.Home interface.

AcquireHome() activates or unlocks a home directory in a reference counted mode of operation. Takes a user name and user record consisting only of "secret" section as argument. If the home directory is not active yet, it is activated. If it is currently locked it is unlocked. After completion a reference to the activation/unlocking of the home directory is returned via a file descriptor. When the last client which acquired such a file descriptor closes it the home directory is automatically deactivated again. This method is typically invoked when a user logs in, and the file descriptor is held until the user logs out again, thus ensuring the user's home directory can be unmounted automatically again in a robust fashion, when the user logs out. The third argument is a boolean which indicates whether the client invoking the call is able to automatically re-authenticate when the system comes back from suspending. It should be set by all clients that implement a secure lock screen running outside of the user's context, that is brought up when the system comes back from suspend and can be used to re-acquire the credentials to unlock the user's home directory. If a home directory has at least one client with an open reference to the home directory that does not support this it is not suspended automatically at system suspend, otherwise it is. This method is equivalent to Acquire() on the org.freedesktop.home1.Home interface.

RefHome() is similar to AcquireHome() but takes no user record with "secret" section, i.e. will take an additional reference to an already activated/unlocked home directory without attempting to activate/unlock it itself. It will fail if the home directory is not already activated. This method is equivalent to Ref() on the org.freedesktop.home1.Home interface.

RefHomeUnrestricted() is identical to RefHome() but succeeds even if the home area is not active currently. This is useful on conjunction with ActivateHomeIfReferenced().

ReleaseHome() releases a home directory again, if all file descriptors referencing it are already closed, that where acquired through AcquireHome() or RefHome(). Note that this call does not actually cause the deactivation of the home directory (which happens automatically when the last referencing file descriptor is closed), but is simply a synchronization mechanism that allows delaying of the user session's termination until any triggered deactivation is completed. This method is equivalent to Release() on the org.freedesktop.home1.Home interface.

LockAllHomes() locks all active home directories that only have references that opted into automatic suspending during system suspend. This is usually invoked automatically shortly before system suspend.

DeactivateAllHomes() deactivates all home areas that are currently active. This is usually invoked automatically shortly before system shutdown.

Rebalance() synchronously rebalances free disk space between home areas. This only executes an operation if at least one home area using the LUKS2 backend is active and has rebalancing enabled, and is otherwise a NOP.

### Properties
AutoLogin exposes an array of structures consisting of user name, seat name and object path of an home directory object. All locally managed users that have the "autoLogin" field set are listed here, with the seat name they are associated with. A display manager may watch this property and pre-fill the login screen with the users exposed this way.

## THE HOME OBJECT

```
node /org/freedesktop/home1/home {

  interface org.freedesktop.home1.Home {

    methods:

      Activate(in  s secret);

      ActivateIfReferenced(in  s secret);

      @org.freedesktop.systemd1.Privileged("true")

      Deactivate();

      Unregister();

      Realize(in  s secret);

      Remove();

      @org.freedesktop.systemd1.Privileged("true")

      Fixate(in  s secret);

      Authenticate(in  s secret);

      Update(in  s user_record);

      UpdateEx(in  s user_record,

               in  a{sh} blobs,

               in  t flags);

      Resize(in  t size,

             in  s secret);

      ChangePassword(in  s new_secret,

                     in  s old_secret);

      @org.freedesktop.systemd1.Privileged("true")

      Lock();

      @org.freedesktop.systemd1.Privileged("true")

      Unlock(in  s secret);

      @org.freedesktop.systemd1.Privileged("true")

      Acquire(in  s secret,

              in  b please_suspend,

              out h send_fd);

      @org.freedesktop.systemd1.Privileged("true")

      Ref(in  b please_suspend,

          out h send_fd);

      @org.freedesktop.systemd1.Privileged("true")

      RefUnrestricted(in  b please_suspend,

                      out h send_fd);

      @org.freedesktop.systemd1.Privileged("true")

      Release();

    properties:

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly s UserName = '...';

      readonly u UID = ...;

      readonly (suusss) UnixRecord = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly s State = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates")

      readonly (sb) UserRecord = ...;

  };

  interface org.freedesktop.DBus.Peer { ... };

  interface org.freedesktop.DBus.Introspectable { ... };

  interface org.freedesktop.DBus.Properties { ... };

  interface org.freedesktop.DBus.ObjectManager { ... };
};
```

### Methods
Activate(), ActivateIfReferenced(), Deactivate(), Unregister(), Realize(), Remove(), Fixate(), Authenticate(), Update(), UpdateEx(), Resize(), ChangePassword(), Lock(), Unlock(), Acquire(), Ref(), RefUnrestricted(), Release(), operate like their matching counterparts on the org.freedesktop.home1.Manager interface (see above). The main difference is that they are methods of the home directory objects, and hence carry no additional user name parameter. Which of the two flavors of methods to call depends on the handles to the user known on the client side: if only the user name is known, it is preferable to use the methods on the manager object since they operate with user names only. Clients can also easily operate on their own home area by using the methods on the manager object with an empty string as the user name. If the client has the home's object path already acquired in some way, however, it is preferable to operate on the org.freedesktop.home1.Home objects instead.

### Properties
UserName contains the user name of the user account/home directory.

UID contains the numeric UNIX UID of the user account.

UnixRecord contains a structure encapsulating the six fields a struct passwd typically contains (the password field is suppressed).

State exposes the current state home the home directory.

UserRecord contains the full JSON user record string of the user account.

## VERSIONING
These D-Bus interfaces follow the usual interface versioning guidelines[3].

## HISTORY

### The Manager Object
ActivateHomeIfReferenced(), RefHomeUnrestricted(), CreateHomeEx(), and UpdateHomeEx() were added in version 256.

### Home Objects
ActivateIfReferenced(), RefUnrestricted(), and UpdateEx() were added in version 256.

## SEE ALSO
systemd(1), systemd-homed.service(8), homectl(1)

## NOTES
1.

JSON User Records

https://systemd.io/USER_RECORD

2.

User Record Blob Directories

https://systemd.io/USER_RECORD_BLOB_DIRS

3.

the usual interface versioning guidelines

https://0pointer.de/blog/projects/versioning-dbus.html


journal-remote.conf

package: systemd-journal-remote

title: journal-remote.conf(5)

text:
# journal-remote.conf(5)

## NAME
journal-remote.conf, journal-remote.conf.d - Configuration files for the service accepting remote journal uploads

## SYNOPSIS
/etc/systemd/journal-remote.conf

/run/systemd/journal-remote.conf

/usr/local/lib/systemd/journal-remote.conf

/usr/lib/systemd/journal-remote.conf

/etc/systemd/journal-remote.conf.d/*.conf

/run/systemd/journal-remote.conf.d/*.conf

/usr/local/lib/systemd/journal-remote.conf.d/*.conf

/usr/lib/systemd/journal-remote.conf.d/*.conf

## DESCRIPTION
These files configure various parameters of systemd-journal-remote.service(8). See systemd.syntax(7) for a general description of the syntax.

## CONFIGURATION DIRECTORIES AND PRECEDENCE
The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults. The main configuration file is loaded from one of the listed directories in order of priority, only the first file found is used: /etc/systemd/, /run/systemd/, /usr/local/lib/systemd/ [1], /usr/lib/systemd/. The vendor version of the file contains commented out entries showing the defaults as a guide to the administrator. Local overrides can also be created by creating drop-ins, as described below. The main configuration file can also be edited for this purpose (or a copy in /etc/ if it is shipped under /usr/), however using drop-ins for local configuration is recommended over modifications to the main configuration file.

In addition to the main configuration file, drop-in configuration snippets are read from /usr/lib/systemd/*.conf.d/, /usr/local/lib/systemd/*.conf.d/, and /etc/systemd/*.conf.d/. Those drop-ins have higher precedence and override the main configuration file. Files in the *.conf.d/ configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files.

When packages need to customize the configuration, they can install drop-ins under /usr/. Files in /etc/ are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages. Drop-ins have to be used to override package drop-ins, since the main configuration file has lower precedence. It is recommended to prefix all filenames in those subdirectories with a two-digit number and a dash, to simplify the ordering. This also defines a concept of drop-in priorities to allow OS vendors to ship drop-ins within a specific range lower than the range used by users. This should lower the risk of package drop-ins overriding accidentally drop-ins defined by users. It is recommended to use the range 10-40 for drop-ins in /usr/ and the range 60-90 for drop-ins in /etc/ and /run/, to make sure that local and transient drop-ins take priority over drop-ins shipped by the OS vendor.

To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to /dev/null in the configuration directory in /etc/, with the same filename as the vendor configuration file.

## OPTIONS
All options are configured in the [Remote] section:

Seal=

Periodically sign the data in the journal using Forward Secure Sealing. Added in version 229.

SplitMode=

One of "host" or "none". Added in version 220.

ServerKeyFile=

SSL key in PEM format. Added in version 220.

ServerCertificateFile=

SSL certificate in PEM format. Added in version 220.

TrustedCertificateFile=

SSL CA certificate. Added in version 220.

MaxUse=, KeepFree=, MaxFileSize=, MaxFiles=

These are analogous to SystemMaxUse=, SystemKeepFree=, SystemMaxFileSize= and SystemMaxFiles= in journald.conf(5). MaxUse= controls how much disk space the systemd-journal-remote may use up at most. KeepFree= controls how much disk space systemd-journal-remote shall leave free for other uses. systemd-journal-remote will respect both limits and use the smaller of the two values.

MaxFiles= controls how many individual journal files to keep at most. Note that only archived files are deleted to reduce the number of files until this limit is reached; active files will stay around. This means that, in effect, there might still be more journal files around in total than this limit after a vacuuming operation is complete.

Added in version 253.

## SEE ALSO
journald.conf(5), systemd(1), systemd-journal-remote.service(8), systemd-journald.service(8)

## NOTES
1.

💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If /usr/local/ is a separate partition, it may not be available during early boot, and must not be used for configuration.