{
    "mode": "man",
    "parameter": "systemd-sysusers",
    "section": "8",
    "url": "https://www.chedong.com/phpMan.php/man/systemd-sysusers/8/json",
    "generated": "2026-09-14T11:08:12Z",
    "synopsis": "systemd-sysusers [OPTIONS...] [CONFIGFILE...]\nsystemd-sysusers.service",
    "sections": {
        "NAME": {
            "content": "systemd-sysusers, systemd-sysusers.service - Allocate system users and groups\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "systemd-sysusers [OPTIONS...] [CONFIGFILE...]\n\nsystemd-sysusers.service\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "systemd-sysusers creates system users and groups, based on files in the format described in\nsysusers.d(5).\n\nIf invoked with no arguments, it applies all directives from all files found in the\ndirectories specified by sysusers.d(5). When invoked with positional arguments, if option\n--replace=PATH is specified, arguments specified on the command line are used instead of the\nconfiguration file PATH. Otherwise, just the configuration specified by the command line\narguments is executed. The string \"-\" may be specified instead of a filename to instruct\nsystemd-sysusers to read the configuration from standard input. If the argument is a relative\npath, all configuration directories are searched for a matching file and the file found that\nhas the highest priority is executed. If the argument is an absolute path, that file is used\ndirectly without searching of the configuration directories.\n",
            "subsections": []
        },
        "OPTIONS": {
            "content": "The following options are understood:\n\n--root=root\nTakes a directory path as an argument. All paths will be prefixed with the given\nalternate root path, including config search paths.\n\nAdded in version 215.\n\n--image=image\nTakes a path to a disk image file or block device node. If specified all operations are\napplied to file system in the indicated disk image. This is similar to --root= but\noperates on file systems stored in disk images or block devices. The disk image should\neither contain just a file system or a set of file systems within a GPT partition table,\nfollowing the \u001b[34mDiscoverable Partitions Specification[1]. For further information on\nsupported disk images, see systemd-nspawn(1)'s switch of the same name.\n\nAdded in version 247.\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 the disk image specified via --image=, see above. If not\nspecified defaults to the \"*\" policy, i.e. all recognized file systems in the image are\nused.\n\n--replace=PATH\nWhen this option is given, one or more positional arguments must be specified. All\nconfiguration files found in the directories listed in sysusers.d(5) will be read, and\nthe configuration given on the command line will be handled instead of and with the same\npriority as the configuration file PATH.\n\nThis option is intended to be used when package installation scripts are running and\nfiles belonging to that package are not yet available on disk, so their contents must be\ngiven on the command line, but the admin configuration might already exist and should be\ngiven higher priority.\n\nExample 1. RPM installation script for radvd\n\necho 'u radvd - \"radvd daemon\"' | \\\nsystemd-sysusers --replace=/usr/lib/sysusers.d/radvd.conf -\n\nThis will create the radvd user as if /usr/lib/sysusers.d/radvd.conf was already on disk.\nAn admin might override the configuration specified on the command line by placing\n/etc/sysusers.d/radvd.conf or even /etc/sysusers.d/00-overrides.conf.\n\nNote that this is the expanded form, and when used in a package, this would be written\nusing a macro with \"radvd\" and a file containing the configuration line as arguments.\n\nAdded in version 238.\n",
            "subsections": [
                {
                    "name": "--dry-run",
                    "content": "Process the configuration and figure out what entries would be created, but don't\nactually write anything.\n\nAdded in version 250.\n",
                    "long": "--dry-run"
                },
                {
                    "name": "--inline",
                    "content": "Treat each positional argument as a separate configuration line instead of a file name.\n\nAdded in version 238.\n",
                    "long": "--inline"
                },
                {
                    "name": "--cat-config",
                    "content": "Copy the contents of config files to standard output. Before each file, the filename is\nprinted as a comment.\n",
                    "long": "--cat-config"
                },
                {
                    "name": "--tldr",
                    "content": "Copy the contents of config files to standard output. Only the \"interesting\" parts of the\nconfiguration files are printed, comments and empty lines are skipped. Before each file,\nthe filename is printed as a comment.\n",
                    "long": "--tldr"
                },
                {
                    "name": "--no-pager",
                    "content": "Do not pipe output into a pager.\n",
                    "long": "--no-pager"
                },
                {
                    "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"
                }
            ]
        },
        "CREDENTIALS": {
            "content": "systemd-sysusers supports the service credentials logic as implemented by\nImportCredential=/LoadCredential=/SetCredential= (see systemd.exec(1) for details). The\nfollowing credentials are used when passed in:\n\npasswd.hashed-password.user\nA UNIX hashed password string to use for the specified user, when creating an entry for\nit. This is particularly useful for the \"root\" user as it allows provisioning the default\nroot password to use via a unit file drop-in or from a container manager passing in this\ncredential. Note that setting this credential has no effect if the specified user account\nalready exists. This credential is hence primarily useful in first boot scenarios or\nsystems that are fully stateless and come up with an empty /etc/ on every boot.\n\nAdded in version 249.\n\npasswd.plaintext-password.user\nSimilar to \"passwd.hashed-password.user\" but expect a literal, plaintext password, which\nis then automatically hashed before used for the user account. If both the hashed and the\nplaintext credential are specified for the same user the former takes precedence. It's\ngenerally recommended to specify the hashed version; however in test environments with\nweaker requirements on security it might be easier to pass passwords in plaintext\ninstead.\n\nAdded in version 249.\n\npasswd.shell.user\nSpecifies the shell binary to use for the specified account when creating it.\n\nAdded in version 249.\n\nsysusers.extra\nThe contents of this credential may contain additional lines to operate on. The\ncredential contents should follow the same format as any other sysusers.d/ drop-in. If\nthis credential is passed it is processed after all of the drop-in files read from the\nfile system.\n\nAdded in version 252.\n\nNote that by default the systemd-sysusers.service unit file is set up to inherit the\n\"passwd.hashed-password.root\", \"passwd.plaintext-password.root\", \"passwd.shell.root\" and\n\"sysusers.extra\" credentials from the service manager. Thus, when invoking a container with\nan unpopulated /etc/ for the first time it is possible to configure the root user's password\nto be \"systemd\" like this:\n\n# systemd-nspawn --image=... --set-credential=passwd.hashed-password.root:'$y$j9T$yAuRJu1o5HioZAGDYPU5d.$F64ni6J2y2nNQve90M/p0ZP0ECP/qqzipNyaY9fjGpC' ...\n\nNote again that the data specified in this credential is consulted only when creating an\naccount for the first time, it may not be used for changing the password or shell of an\naccount that already exists.\n\nUse mkpasswd(1) for generating UNIX password hashes from the command line.\n",
            "subsections": []
        },
        "EXIT STATUS": {
            "content": "On success, 0 is returned, a non-zero failure code otherwise.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "systemd(1), sysusers.d(5), \u001b[34mUsers, Groups, UIDs and GIDs on systemd systems[2],\nsystemd.exec(1), mkpasswd(1)\n",
            "subsections": []
        },
        "NOTES": {
            "content": "1. Discoverable Partitions Specification\nhttps://uapi-group.org/specifications/specs/discoverablepartitionsspecification\n\n2. Users, Groups, UIDs and GIDs on systemd systems\nhttps://systemd.io/UIDS-GIDS\n\nsystemd 255                                                                      SYSTEMD-SYSUSERS(8)",
            "subsections": []
        }
    },
    "summary": "systemd-sysusers, systemd-sysusers.service - Allocate system users and groups",
    "flags": [
        {
            "flag": "",
            "long": "--dry-run",
            "arg": null,
            "description": "Process the configuration and figure out what entries would be created, but don't actually write anything. Added in version 250."
        },
        {
            "flag": "",
            "long": "--inline",
            "arg": null,
            "description": "Treat each positional argument as a separate configuration line instead of a file name. Added in version 238."
        },
        {
            "flag": "",
            "long": "--cat-config",
            "arg": null,
            "description": "Copy the contents of config files to standard output. Before each file, the filename is printed as a comment."
        },
        {
            "flag": "",
            "long": "--tldr",
            "arg": null,
            "description": "Copy the contents of config files to standard output. Only the \"interesting\" parts of the configuration files are printed, comments and empty lines are skipped. Before each file, the filename is printed as a comment."
        },
        {
            "flag": "",
            "long": "--no-pager",
            "arg": null,
            "description": "Do not pipe output into a pager."
        },
        {
            "flag": "-h",
            "long": "--help",
            "arg": null,
            "description": "Print a short help text and exit."
        },
        {
            "flag": "",
            "long": "--version",
            "arg": null,
            "description": "Print a short version string and exit."
        }
    ],
    "examples": [],
    "see_also": [
        {
            "name": "systemd",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/systemd/1/json"
        },
        {
            "name": "sysusers.d",
            "section": "5",
            "url": "https://www.chedong.com/phpMan.php/man/sysusers.d/5/json"
        },
        {
            "name": "systemd.exec",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/systemd.exec/1/json"
        },
        {
            "name": "mkpasswd",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/mkpasswd/1/json"
        }
    ]
}