{
    "mode": "man",
    "parameter": "systemd-sysext.service",
    "section": "8",
    "url": "https://www.chedong.com/phpMan.php/man/systemd-sysext.service/8/json",
    "generated": "2026-06-13T19:28:58Z",
    "synopsis": "systemd-sysext [OPTIONS...]\nsystemd-sysext.service",
    "sections": {
        "NAME": {
            "content": "systemd-sysext, systemd-sysext.service - Activates System Extension Images\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "systemd-sysext [OPTIONS...]\n\nsystemd-sysext.service\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "systemd-sysext activates/deactivates system extension images. System extension images may –\ndynamically at runtime — extend the /usr/ and /opt/ directory hierarchies with additional\nfiles. This is particularly useful on immutable system images where a /usr/ and/or /opt/\nhierarchy residing on a read-only file system shall be extended temporarily at runtime\nwithout making any persistent modifications.\n\nSystem extension images should contain files and directories similar in fashion to regular\noperating system tree. When one or more system extension images are activated, their /usr/\nand /opt/ hierarchies are combined via \"overlayfs\" with the same hierarchies of the host OS,\nand the host /usr/ and /opt/ overmounted with it (\"merging\"). When they are deactivated, the\nmount point is disassembled — again revealing the unmodified original host version of the\nhierarchy (\"unmerging\"). Merging thus makes the extension's resources suddenly appear below\nthe /usr/ and /opt/ hierarchies as if they were included in the base OS image itself.\nUnmerging makes them disappear again, leaving in place only the files that were shipped with\nthe base OS image itself.\n\nFiles and directories contained in the extension images outside of the /usr/ and /opt/\nhierarchies are not merged, and hence have no effect when included in a system extension\nimage. In particular, files in the /etc/ and /var/ included in a system extension image will\nnot appear in the respective hierarchies after activation.\n\nSystem extension images are strictly read-only, and the host /usr/ and /opt/ hierarchies\nbecome read-only too while they are activated.\n\nSystem extensions are supposed to be purely additive, i.e. they are supposed to include only\nfiles that do not exist in the underlying basic OS image. However, the underlying mechanism\n(overlayfs) also allows removing files, but it is recommended not to make use of this.\n\nSystem extension images may be provided in the following formats:\n\n1. Plain directories or btrfs subvolumes containing the OS tree\n\n2. Disk images with a GPT disk label, following the Discoverable Partitions Specification[1]\n\n3. Disk images lacking a partition table, with a naked Linux file system (e.g. squashfs or\next4)\n\nThese image formats are the same ones that systemd-nspawn(1) supports via it's\n--directory=/--image= switches and those that the service manager supports via\nRootDirectory=/RootImage=. Similar to them they may optionally carry Verity authentication\ninformation.\n\nSystem extensions are automatically looked for in the directories /etc/extensions/,\n/run/extensions/, /var/lib/extensions/, /usr/lib/extensions/ and /usr/local/lib/extensions/.\nThe first two listed directories are not suitable for carrying large binary images, however\nare still useful for carrying symlinks to them. The primary place for installing system\nextensions is /var/lib/extensions/. Any directories found in these search directories are\nconsidered directory based extension images, any files with the .raw suffix are considered\ndisk image based extension images.\n\nDuring boot OS extension images are activated automatically, if the systemd-sysext.service is\nenabled. Note that this service runs only after the underlying file systems where system\nextensions are searched are mounted. This means they are not suitable for shipping resources\nthat are processed by subsystems running in earliest boot. Specifically, OS extension images\nare not suitable for shipping system services or systemd-sysusers(8) definitions. See\nPortable Services[2] for a simple mechanism for shipping system services in disk images, in a\nsimilar fashion to OS extensions. Note the different isolation on these two mechanisms: while\nsystem extension directly extend the underlying OS image with additional files that appear in\na way very similar to as if they were shipped in the OS image itself and thus imply no\nsecurity isolation, portable services imply service level sandboxing in one way or another.\nThe systemd-sysext.service service is guaranteed to finish start-up before basic.target is\nreached; i.e. at the time regular services initialize (those which do not use\nDefaultDependencies=no), the files and directories system extensions provide are available in\n/usr/ and /opt/ and may be accessed.\n\nNote that there is no concept of enabling/disabling installed system extension images: all\ninstalled extension images are automatically activated at boot.\n\nA simple mechanism for version compatibility is enforced: a system extension image must carry\na /usr/lib/extension-release.d/extension-release.$name file, which must match its image name,\nthat is compared with the host os-release file: the contained ID= fields have to match, as\nwell as the SYSEXTLEVEL= field (if defined). If the latter is not defined, the VERSIONID=\nfield has to match instead. System extensions should not ship a /usr/lib/os-release file (as\nthat would be merged into the host /usr/ tree, overriding the host OS version data, which is\nnot desirable). The extension-release file follows the same format and semantics, and carries\nthe same content, as the os-release file of the OS, but it describes the resources carried in\nthe extension image.\n",
            "subsections": []
        },
        "USES": {
            "content": "The primary use case for system images are immutable environments where debugging and\ndevelopment tools shall optionally be made available, but not included in the immutable base\nOS image itself (e.g.  strace(1) and gdb(1) shall be an optionally installable addition in\norder to make debugging/development easier). System extension images should not be\nmisunderstood as a generic software packaging framework, as no dependency scheme is\navailable: system extensions should carry all files they need themselves, except for those\nalready shipped in the underlying host system image. Typically, system extension images are\nbuilt at the same time as the base OS image — within the same build system.\n\nAnother use case for the system extension concept is temporarily overriding OS supplied\nresources with newer ones, for example to install a locally compiled development version of\nsome low-level component over the immutable OS image without doing a full OS rebuild or\nmodifying the nominally immutable image. (e.g. \"install\" a locally built package with\nDESTDIR=/var/lib/extensions/mytest make install && systemd-sysext refresh, making it\navailable in /usr/ as if it was installed in the OS image itself.) This case works regardless\nif the underlying host /usr/ is managed as immutable disk image or is a traditional package\nmanager controlled (i.e. writable) tree.\n",
            "subsections": []
        },
        "COMMANDS": {
            "content": "The following commands are understood:\n",
            "subsections": [
                {
                    "name": "status",
                    "content": "When invoked without any command verb, or when status is specified the current merge\nstatus is shown, separately for both /usr/ and /opt/.\n"
                },
                {
                    "name": "merge",
                    "content": "Merges all currently installed system extension images into /usr/ and /opt/, by\novermounting these hierarchies with an \"overlayfs\" file system combining the underlying\nhierarchies with those included in the extension images. This command will fail if the\nhierarchies are already merged.\n"
                },
                {
                    "name": "unmerge",
                    "content": "Unmerges all currently installed system extension images from /usr/ and /opt/, by\nunmounting the \"overlayfs\" file systems created by merge prior.\n"
                },
                {
                    "name": "refresh",
                    "content": "A combination of unmerge and merge: if already mounted the existing \"overlayfs\" instance\nis unmounted temporarily, and then replaced by a new version. This command is useful\nafter installing/removing system extension images, in order to update the \"overlayfs\"\nfile system accordingly. If no system extensions are installed when this command is\nexecuted, the equivalent of unmerge is executed, without establishing any new \"overlayfs\"\ninstance. Note that currently there's a brief moment where neither the old nor the new\n\"overlayfs\" file system is mounted. This implies that all resources supplied by a system\nextension will briefly disappear — even if it exists continuously during the refresh\noperation.\n"
                },
                {
                    "name": "list",
                    "content": "A brief list of installed extension images is shown.\n"
                },
                {
                    "name": "-h --help",
                    "content": "Print a short help text and exit.\n",
                    "flag": "-h",
                    "long": "--help"
                },
                {
                    "name": "--version",
                    "content": "Print a short version string and exit.\n",
                    "long": "--version"
                }
            ]
        },
        "OPTIONS": {
            "content": "",
            "subsections": [
                {
                    "name": "--root=",
                    "content": "Operate relative to the specified root directory, i.e. establish the \"overlayfs\" mount\nnot on the top-level host /usr/ and /opt/ hierarchies, but below some specified root\ndirectory.\n"
                },
                {
                    "name": "--force",
                    "content": "When merging system extensions into /usr/ and /opt/, ignore version incompatibilities,\ni.e. force merging regardless of whether the version information included in the\nextension images matches the host or not.\n",
                    "long": "--force"
                },
                {
                    "name": "--no-pager",
                    "content": "Do not pipe output into a pager.\n",
                    "long": "--no-pager"
                },
                {
                    "name": "--no-legend",
                    "content": "Do not print the legend, i.e. column headers and the footer with hints.\n\n--json=MODE\nShows output formatted as JSON. Expects one of \"short\" (for the shortest possible output\nwithout any redundant whitespace or line breaks), \"pretty\" (for a pretty version of the\nsame, with indentation and line breaks) or \"off\" (to turn off JSON output, the default).\n",
                    "long": "--no-legend"
                }
            ]
        },
        "EXIT STATUS": {
            "content": "On success, 0 is returned.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "systemd(1), systemd-nspawn(1)\n",
            "subsections": []
        },
        "NOTES": {
            "content": "1. Discoverable Partitions Specification\nhttps://systemd.io/DISCOVERABLEPARTITIONS\n\n2. Portable Services\nhttps://systemd.io/PORTABLESERVICES\n\n\n\nsystemd 249                                                                        SYSTEMD-SYSEXT(8)",
            "subsections": []
        }
    },
    "summary": "systemd-sysext, systemd-sysext.service - Activates System Extension Images",
    "flags": [
        {
            "flag": "",
            "long": null,
            "arg": null,
            "description": "Operate relative to the specified root directory, i.e. establish the \"overlayfs\" mount not on the top-level host /usr/ and /opt/ hierarchies, but below some specified root directory."
        },
        {
            "flag": "",
            "long": "--force",
            "arg": null,
            "description": "When merging system extensions into /usr/ and /opt/, ignore version incompatibilities, i.e. force merging regardless of whether the version information included in the extension images matches the host or not."
        },
        {
            "flag": "",
            "long": "--no-pager",
            "arg": null,
            "description": "Do not pipe output into a pager."
        },
        {
            "flag": "",
            "long": "--no-legend",
            "arg": null,
            "description": "Do not print the legend, i.e. column headers and the footer with hints. --json=MODE Shows output formatted as JSON. Expects one of \"short\" (for the shortest possible output without any redundant whitespace or line breaks), \"pretty\" (for a pretty version of the same, with indentation and line breaks) or \"off\" (to turn off JSON output, the default)."
        }
    ],
    "examples": [],
    "see_also": [
        {
            "name": "systemd",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/systemd/1/json"
        },
        {
            "name": "systemd-nspawn",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/systemd-nspawn/1/json"
        }
    ]
}