{
    "mode": "man",
    "parameter": "systemd-confext",
    "section": "8",
    "url": "https://www.chedong.com/phpMan.php/man/systemd-confext/8/json",
    "generated": "2026-10-09T13:03:49Z",
    "synopsis": "systemd-sysext [OPTIONS...] COMMAND\nsystemd-sysext.service\nsystemd-confext [OPTIONS...] COMMAND\nsystemd-confext.service",
    "sections": {
        "NAME": {
            "content": "systemd-sysext, systemd-sysext.service, systemd-confext, systemd-confext.service - Activates\nSystem Extension Images\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "systemd-sysext [OPTIONS...] COMMAND\n\nsystemd-sysext.service\n\n\nsystemd-confext [OPTIONS...] COMMAND\n\nsystemd-confext.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 overlaying or removing files, but it is recommended not to make use\nof 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. erofs,\nsquashfs or ext4)\n\nThese image formats are the same ones that systemd-nspawn(1) supports via its\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 searched for in the directories /etc/extensions/, /run/extensions/ and\n/var/lib/extensions/. The first two listed directories are not suitable for carrying large\nbinary images, however are still useful for carrying symlinks to them. The primary place for\ninstalling system extensions is /var/lib/extensions/. Any directories found in these search\ndirectories are considered directory based extension images; any files with the .raw suffix\nare considered disk image based extension images. When invoked in the initrd, the additional\ndirectory /.extra/sysext/ is included in the directories that are searched for extension\nimages. Note however, that by default a tighter image policy applies to images found there,\nthough, see below. This directory is populated by systemd-stub(7) with extension images found\nin the system's EFI System Partition.\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 may be located have been mounted. This means they are not suitable for shipping\nresources that are processed by subsystems running in earliest boot. Specifically, OS\nextension images are not suitable for shipping system services or systemd-sysusers(8)\ndefinitions. See the Portable Services[2] page for a simple mechanism for shipping system\nservices in disk images, in a similar fashion to OS extensions. Note the different isolation\non these two mechanisms: while system extension directly extend the underlying OS image with\nadditional files that appear in a way very similar to as if they were shipped in the OS image\nitself and thus imply no security isolation, portable services imply service level sandboxing\nin one way or another. The systemd-sysext.service service is guaranteed to finish start-up\nbefore basic.target is reached; i.e. at the time regular services initialize (those which do\nnot use DefaultDependencies=no), the files and directories system extensions provide are\navailable in /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. However, you can place an\nempty directory named like the extension (no .raw) in /etc/extensions/ to \"mask\" an extension\nwith the same name in a system folder with lower precedence.\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 unless\n\"any\" is set for the extension. If the extension ID= is not \"any\", the SYSEXTLEVEL= field\n(if defined) has to match. If the latter is not defined, the VERSIONID= field has to match\ninstead. If the extension defines the ARCHITECTURE= field and the value is not \"any\" it has\nto match the kernel's architecture reported by uname(2) but the used architecture identifiers\nare the same as for ConditionArchitecture= described in systemd.unit(5).\nEXTENSIONRELOADMANAGER= can be set to 1 if the extension requires a service manager reload\nafter application of the extension. Note that the for the reasons mentioned earlier: Portable\nServices[2] remain the recommended way to ship system services. System extensions should not\nship a /usr/lib/os-release file (as that would be merged into the host /usr/ tree, overriding\nthe host OS version data, which is not desirable). The extension-release file follows the\nsame format and semantics, and carries the same content, as the os-release file of the OS,\nbut it describes the resources carried in the extension image.\n\nThe systemd-confext concept follows the same principle as the systemd-sysext(1) functionality\nbut instead of working on /usr and /opt, confext will extend only /etc. Files and directories\ncontained in the confext images outside of the /etc/ hierarchy are not merged, and hence have\nno effect when included in the image. Formats for these images are of the same as sysext\nimages. The merged hierarchy will be mounted with \"nosuid\" and (if not disabled via\n--noexec=false) \"noexec\".\n\nConfexts are looked for in the directories /run/confexts/, /var/lib/confexts/,\n/usr/lib/confexts/ and /usr/local/lib/confexts/. The first listed directory is not suitable\nfor carrying large binary images, however is still useful for carrying symlinks to them. The\nprimary place for installing configuration extensions is /var/lib/confexts/. Any directories\nfound in these search directories are considered directory based confext images; any files\nwith the .raw suffix are considered disk image based confext images.\n\nAgain, just like sysext images, the confext images will contain a\n/etc/extension-release.d/extension-release.NAME file, which must match the image name (with\nthe usual escape hatch of the user.extension-release.strict xattr(7)), and again with content\nbeing one or more of ID=, VERSIONID=, and CONFEXTLEVEL. Confext images will then be checked\nand matched against the base OS layer.\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\nFor the confext case, the OSConfig project aims to perform runtime reconfiguration of OS\nservices. Sometimes, there is a need to swap certain configuration parameter values or\nrestart only a specific service without deployment of new code or a complete OS deployment.\nIn other words, we want to be able to tie the most frequently configured options to runtime\nupdateable flags that can be changed without a system reboot. This will help reduce servicing\ntimes when there is a need for changing the OS configuration.\n",
            "subsections": []
        },
        "COMMANDS": {
            "content": "The following commands are understood by both the sysext and confext concepts:\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/ of sysext and for /etc/ of\nconfext).\n\nAdded in version 248.\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. For confext, the merge happens into the /etc/ directory\ninstead.\n\nAdded in version 248.\n"
                },
                {
                    "name": "unmerge",
                    "content": "Unmerges all currently installed system extension images from /usr/ and /opt/ for sysext\nand /etc/, for confext, by unmounting the \"overlayfs\" file systems created by merge\nprior.\n\nAdded in version 248.\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\nAdded in version 248.\n"
                },
                {
                    "name": "list",
                    "content": "A brief list of installed extension images is shown.\n\nAdded in version 248.\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 for sysext or /etc/ for confext,\nbut below some specified root directory.\n\nAdded in version 248.\n"
                },
                {
                    "name": "--force",
                    "content": "When merging system extensions into /usr/ and /opt/ for sysext and /etc/ for confext,\nignore version incompatibilities, i.e. force merging regardless of whether the version\ninformation included in the images matches the host or not.\n\nAdded in version 248.\n\n--image-policy=policy\nTakes an image policy string as argument, as per systemd.image-policy(7). The policy is\nenforced when operating on system extension disk images. If not specified defaults to\n\"root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent\"\nfor system extensions, i.e. only the root and /usr/ file systems in the image are used.\nFor configuration extensions defaults to\n\"root=verity+signed+encrypted+unprotected+absent\". When run in the initrd and operating\non a system extension image stored in the /.extra/sysext/ directory a slightly stricter\npolicy is used by default: \"root=signed+absent:usr=signed+absent\", see above for details.\n\nAdded in version 254.\n\n--noexec=BOOL\nWhen merging configuration extensions into /etc/ the \"MSNOEXEC\" mount flag is used by\ndefault. This option can be used to disable it.\n\nAdded in version 254.\n",
                    "long": "--force"
                },
                {
                    "name": "--no-reload",
                    "content": "When used with merge, unmerge or refresh, do not reload daemon after executing the\nchanges even if an extension that is applied requires a reload via the\nEXTENSIONRELOADMANAGER= set to 1.\n\nAdded in version 255.\n",
                    "long": "--no-reload"
                },
                {
                    "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), systemd-stub(7)\n",
            "subsections": []
        },
        "NOTES": {
            "content": "1. Discoverable Partitions Specification\nhttps://uapi-group.org/specifications/specs/discoverablepartitionsspecification\n\n2. Portable Services\nhttps://systemd.io/PORTABLESERVICES\n\nsystemd 255                                                                        SYSTEMD-SYSEXT(8)",
            "subsections": []
        }
    },
    "summary": "systemd-sysext, systemd-sysext.service, systemd-confext, systemd-confext.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 for sysext or /etc/ for confext, but below some specified root directory. Added in version 248."
        },
        {
            "flag": "",
            "long": "--force",
            "arg": null,
            "description": "When merging system extensions into /usr/ and /opt/ for sysext and /etc/ for confext, ignore version incompatibilities, i.e. force merging regardless of whether the version information included in the images matches the host or not. Added in version 248. --image-policy=policy Takes an image policy string as argument, as per systemd.image-policy(7). The policy is enforced when operating on system extension disk images. If not specified defaults to \"root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent\" for system extensions, i.e. only the root and /usr/ file systems in the image are used. For configuration extensions defaults to \"root=verity+signed+encrypted+unprotected+absent\". When run in the initrd and operating on a system extension image stored in the /.extra/sysext/ directory a slightly stricter policy is used by default: \"root=signed+absent:usr=signed+absent\", see above for details. Added in version 254. --noexec=BOOL When merging configuration extensions into /etc/ the \"MSNOEXEC\" mount flag is used by default. This option can be used to disable it. Added in version 254."
        },
        {
            "flag": "",
            "long": "--no-reload",
            "arg": null,
            "description": "When used with merge, unmerge or refresh, do not reload daemon after executing the changes even if an extension that is applied requires a reload via the EXTENSIONRELOADMANAGER= set to 1. Added in version 255."
        },
        {
            "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"
        },
        {
            "name": "systemd-stub",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/systemd-stub/7/json"
        }
    ]
}