{
    "mode": "man",
    "parameter": "ORG.FREEDESKTOP.MACHINE1",
    "section": "5",
    "url": "https://www.chedong.com/phpMan.php/man/ORG.FREEDESKTOP.MACHINE1/5/json",
    "generated": "2026-05-30T08:17:10Z",
    "sections": {
        "NAME": {
            "content": "org.freedesktop.machine1 - The D-Bus interface of systemd-machined\n",
            "subsections": []
        },
        "INTRODUCTION": {
            "content": "systemd-machined.service(8) is a system service that keeps track of locally running virtual\nmachines and containers. This page describes the D-Bus interface.\n",
            "subsections": []
        },
        "THE MANAGER OBJECT": {
            "content": "The service exposes the following interfaces on the Manager object on the bus:\n\nnode /org/freedesktop/machine1 {\ninterface org.freedesktop.machine1.Manager {\nmethods:\nGetMachine(in  s name,\nout o machine);\nGetImage(in  s name,\nout o image);\nGetMachineByPID(in  u pid,\nout o machine);\nListMachines(out a(ssso) machines);\nListImages(out a(ssbttto) images);\nCreateMachine(in  s name,\nin  ay id,\nin  s service,\nin  s class,\nin  u leader,\nin  s rootdirectory,\nin  a(sv) scopeproperties,\nout o path);\nCreateMachineWithNetwork(in  s name,\nin  ay id,\nin  s service,\nin  s class,\nin  u leader,\nin  s rootdirectory,\nin  ai ifindices,\nin  a(sv) scopeproperties,\nout o path);\nRegisterMachine(in  s name,\nin  ay id,\nin  s service,\nin  s class,\nin  u leader,\nin  s rootdirectory,\nout o path);\nRegisterMachineWithNetwork(in  s name,\nin  ay id,\nin  s service,\nin  s class,\nin  u leader,\nin  s rootdirectory,\nin  ai ifindices,\nout o path);\nUnregisterMachine(in  s name);\nTerminateMachine(in  s id);\nKillMachine(in  s name,\nin  s who,\nin  i signal);\nGetMachineAddresses(in  s name,\nout a(iay) addresses);\nGetMachineOSRelease(in  s name,\nout a{ss} fields);\nOpenMachinePTY(in  s name,\nout h pty,\nout s ptypath);\nOpenMachineLogin(in  s name,\nout h pty,\nout s ptypath);\nOpenMachineShell(in  s name,\nin  s user,\nin  s path,\nin  as args,\nin  as environment,\nout h pty,\nout s ptypath);\nBindMountMachine(in  s name,\nin  s source,\nin  s destination,\nin  b readonly,\nin  b mkdir);\nCopyFromMachine(in  s name,\nin  s source,\nin  s destination);\nCopyToMachine(in  s name,\nin  s source,\nin  s destination);\nOpenMachineRootDirectory(in  s name,\nout h fd);\nGetMachineUIDShift(in  s name,\nout u shift);\nRemoveImage(in  s name);\nRenameImage(in  s name,\nin  s newname);\nCloneImage(in  s name,\nin  s newname,\nin  b readonly);\nMarkImageReadOnly(in  s name,\nin  b readonly);\nGetImageHostname(in  s name,\nout s hostname);\nGetImageMachineID(in  s name,\nout ay id);\nGetImageMachineInfo(in  s name,\nout a{ss} machineinfo);\nGetImageOSRelease(in  s name,\nout a{ss} osrelease);\nSetPoolLimit(in  t size);\nSetImageLimit(in  s name,\nin  t size);\nCleanPool(in  s mode,\nout a(st) images);\nMapFromMachineUser(in  s name,\nin  u uidinner,\nout u uidouter);\nMapToMachineUser(in  u uidouter,\nout s machinename,\nout o machinepath,\nout u uidinner);\nMapFromMachineGroup(in  s name,\nin  u gidinner,\nout u gidouter);\nMapToMachineGroup(in  u gidouter,\nout s machinename,\nout o machinepath,\nout u gidinner);\nsignals:\nMachineNew(s machine,\no path);\nMachineRemoved(s machine,\no path);\nproperties:\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"false\")\nreadonly s PoolPath = '...';\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"false\")\nreadonly t PoolUsage = ...;\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"false\")\nreadonly t PoolLimit = ...;\n};\ninterface org.freedesktop.DBus.Peer { ... };\ninterface org.freedesktop.DBus.Introspectable { ... };\ninterface org.freedesktop.DBus.Properties { ... };\n};\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n",
            "subsections": [
                {
                    "name": "Methods",
                    "content": "GetMachine() may be used to get the machine object path for the machine with the specified\nname. Similarly, GetMachineByPID() gets the machine object the specified PID belongs to if\nthere is any.\n\nGetImage() may be used to get the image object path of the image with the specified name.\n\nListMachines() returns an array of all currently registered machines. The structures in the\narray consist of the following fields: machine name, machine class, an identifier for the\nservice that registered the machine and the machine object path.\n\nListImages() returns an array of all currently known images. The structures in the array\nconsist of the following fields: image name, type, read-only flag, creation time,\nmodification time, current disk space, and image object path.\n\nCreateMachine() may be used to register a new virtual machine or container with\nsystemd-machined, creating a scope unit for it. It accepts the following arguments: a machine\nname chosen by the registrar, an optional UUID as a 32 byte array, a string that identifies\nthe service that registers the machine, a class string, the PID of the leader process of the\nmachine, an optional root directory of the container, and an array of additional properties\nto use for the scope registration. The virtual machine name must be suitable as a hostname,\nand hence should follow the usual DNS hostname rules, as well as the Linux hostname\nrestrictions. Specifically, only 7 bit ASCII is permitted, a maximum length of 64 characters\nis enforced, only characters from the set \"a-zA-Z0-9-.\"  are allowed, the name may not begin\nwith a dot, and it may not contain two dots immediately following each other. Container and\nVM managers should ideally use the hostname used internally in the machine for this\nparameter. This recommendation is made in order to make the machine name naturally resolvable\nusing nss-mymachines(8). If a container manager needs to embed characters outside of the\nindicated range, escaping is required, possibly using \"\" as the escape character. Another\n(somewhat natural) option would be to utilize Internet IDNA encoding. The UUID is passed as a\n32 byte array or, if no suitable UUID is available, an empty array (zero length) or zeroed\nout array shall be passed. The UUID should identify the virtual machine/container uniquely\nand should ideally be the same UUID that /etc/machine-id in the VM/container is initialized\nfrom. The service string can be free-form, but it is recommended to pass a short lowercase\nidentifier like \"systemd-nspawn\", \"libvirt-lxc\" or similar. The class string should be either\n\"container\" or \"vm\" indicating whether the machine to register is of the respective class.\nThe leader PID should be the host PID of the init process of the container or the\nencapsulating process of the VM. If the root directory of the container is known and\navailable in the host's hierarchy, it should be passed. Otherwise, pass the empty string\ninstead. Finally, the scope properties are passed as array in the same way as to PID1's\nStartTransientUnit() method. Calling this method will internally register a transient scope\nunit for the calling client (utilizing the passed scopeproperties) and move the leader PID\ninto it. The method returns an object path for the registered machine object that implements\nthe org.freedesktop.machine1.Machine interface (see below). Also see the New Control Group\nInterfaces[1] for details about scope units and how to alter resource control settings on the\ncreated machine at runtime.\n\nRegisterMachine() is similar to CreateMachine(). However, it only registers a machine and\ndoes not create a scope unit for it. Instead, the caller's unit is registered. We recommend\nto only use this method for container or VM managers that are run multiple times, one\ninstance for each container/VM they manage, and are invoked as system services.\n\nCreateMachineWithNetwork() and RegisterMachineWithNetwork() are similar to CreateMachine()\nand RegisterMachine() but take an extra argument: an array of network interface indices that\npoint towards the virtual machine or container. The interface indices should reference one or\nmore network interfaces on the host that can be used to communicate with the guest. Commonly,\nthe passed interface index refers to the host side of a \"veth\" link (in case of containers),\na \"tun\"/\"tap\" link (in case of VMs), or the host side of a bridge interface that bridges\naccess to the VM/container interfaces. Specifying this information is useful to enable\nsupport for link-local IPv6 communication to the machines since the scope field of\nsockaddrin6 can be initialized by the specified ifindex.  nss-mymachines(8) makes use of\nthis information.\n\nKillMachine() sends a UNIX signal to the machine's processes. As its arguments, it takes a\nmachine name (as originally passed to CreateMachine() or returned by ListMachines()), an\nidentifier that specifies what precisely to send the signal to (either \"leader\" or \"all\"),\nand a numeric UNIX signal integer.\n\nTerminateMachine() terminates a virtual machine, killing its processes. It takes a machine\nname as its only argument.\n\nGetMachineAddresses() retrieves the IP addresses of a container. This method returns an array\nof pairs consisting of an address family specifier (AFINET or AFINET6) and a byte array\ncontaining the addresses. This is only supported for containers that make use of network\nnamespacing.\n\nGetMachineOSRelease() retrieves the OS release information of a container. This method\nreturns an array of key value pairs read from the os-release(5) file in the container and is\nuseful to identify the operating system used in a container.\n\nOpenMachinePTY() allocates a pseudo TTY in the container and returns a file descriptor and\nits path. This is equivalent to transitioning into the container and invoking\nposixopenpt(3).\n\nOpenMachineLogin() allocates a pseudo TTY in the container and ensures that a getty login\nprompt of the container is running on the other end. It returns the file descriptor of the\nPTY and the PTY path. This is useful for acquiring a pty with a login prompt from the\ncontainer.\n\nOpenMachineShell() allocates a pseudo TTY in the container, as the specified user, and\ninvokes the executable at the specified path with a list of arguments (starting from argv[0])\nand an environment block. It then returns the file descriptor of the PTY and the PTY path.\n\nBindMountMachine() bind mounts a file or directory from the host into the container. Its\narguments consist of a machine name, the source directory on the host, the destination\ndirectory in the container, and two booleans, one indicating whether the bind mount shall be\nread-only, the other indicating whether the destination mount point shall be created first,\nif it is missing.\n\nCopyFromMachine() copies files or directories from a container into the host. It takes a\ncontainer name, a source directory in the container and a destination directory on the host\nas arguments.  CopyToMachine() does the opposite and copies files from a source directory on\nthe host into a destination directory in the container.\n\nRemoveImage() removes the image with the specified name.\n\nRenameImage() renames the specified image.\n\nCloneImage() clones the specified image under a new name. It also takes a boolean argument\nindicating whether the resulting image shall be read-only or not.\n\nMarkImageReadOnly() toggles the read-only flag of an image.\n\nSetPoolLimit() sets an overall quota limit on the pool of images.\n\nSetImageLimit() sets a per-image quota limit.\n\nMapFromMachineUser(), MapToMachineUser(), MapFromMachineGroup(), and MapToMachineGroup() may\nbe used to map UIDs/GIDs from the host user namespace to a container user namespace or vice\nversa.\n"
                },
                {
                    "name": "Signals",
                    "content": "MachineNew and MachineRemoved are sent whenever a new machine is registered or removed. These\nsignals carry the machine name and the object path to the corresponding\norg.freedesktop.machine1.Machine interface (see below).\n"
                },
                {
                    "name": "Properties",
                    "content": "PoolPath specifies the file system path where images are written to.\n\nPoolUsage specifies the current usage size of the image pool in bytes.\n\nPoolLimit specifies the size limit of the image pool in bytes.\n"
                }
            ]
        },
        "MACHINE OBJECTS": {
            "content": "node /org/freedesktop/machine1/machine/rawhide {\ninterface org.freedesktop.machine1.Machine {\nmethods:\nTerminate();\nKill(in  s who,\nin  i signal);\nGetAddresses(out a(iay) addresses);\nGetOSRelease(out a{ss} fields);\nGetUIDShift(out u shift);\nOpenPTY(out h pty,\nout s ptypath);\nOpenLogin(out h pty,\nout s ptypath);\nOpenShell(in  s user,\nin  s path,\nin  as args,\nin  as environment,\nout h pty,\nout s ptypath);\nBindMount(in  s source,\nin  s destination,\nin  b readonly,\nin  b mkdir);\nCopyFrom(in  s source,\nin  s destination);\nCopyTo(in  s source,\nin  s destination);\nOpenRootDirectory(out h fd);\nproperties:\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"const\")\nreadonly s Name = '...';\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"const\")\nreadonly ay Id = [...];\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"const\")\nreadonly t Timestamp = ...;\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"const\")\nreadonly t TimestampMonotonic = ...;\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"const\")\nreadonly s Service = '...';\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"const\")\nreadonly s Unit = '...';\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"const\")\nreadonly u Leader = ...;\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"const\")\nreadonly s Class = '...';\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"const\")\nreadonly s RootDirectory = '...';\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"const\")\nreadonly ai NetworkInterfaces = [...];\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"false\")\nreadonly s State = '...';\n};\ninterface org.freedesktop.DBus.Peer { ... };\ninterface org.freedesktop.DBus.Introspectable { ... };\ninterface org.freedesktop.DBus.Properties { ... };\n};\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n",
            "subsections": [
                {
                    "name": "Methods",
                    "content": "Terminate() and Kill() terminate/kill the machine. These methods take the same arguments as\nTerminateMachine() and KillMachine() on the Manager interface, respectively.\n\nGetAddresses() and GetOSRelease() get the IP address and OS release information from the\nmachine. These methods take the same arguments as GetMachineAddresses() and\nGetMachineOSRelease() of the Manager interface, respectively.\n"
                },
                {
                    "name": "Properties",
                    "content": "Name is the machine name as it was passed in during registration with CreateMachine() on the\nmanager object.\n\nId is the machine UUID.\n\nTimestamp and TimestampMonotonic are the realtime and monotonic timestamps when the virtual\nmachines where created in microseconds since the epoch.\n\nService contains a short string identifying the registering service as passed in during\nregistration of the machine.\n\nUnit is the systemd scope or service unit name for the machine.\n\nLeader is the PID of the leader process of the machine.\n\nClass is the class of the machine and is either the string \"vm\" (for real VMs based on\nvirtualized hardware) or \"container\" (for light-weight userspace virtualization sharing the\nsame kernel as the host).\n\nRootDirectory is the root directory of the container if it is known and applicable or the\nempty string.\n\nNetworkInterfaces contains an array of network interface indices that point towards the\ncontainer, the VM or the host. For details about this information see the description of\nCreateMachineWithNetwork() above.\n\nState is the state of the machine and is one of \"opening\", \"running\", or \"closing\". Note that\nthe state machine is not considered part of the API and states might be removed or added\nwithout this being considered API breakage.\n"
                }
            ]
        },
        "EXAMPLES": {
            "content": "",
            "subsections": [
                {
                    "name": "Example 1. Introspect org.freedesktop.machine1.Manager on the bus",
                    "content": "$ gdbus introspect --system \\\n--dest org.freedesktop.machine1 \\\n--object-path /org/freedesktop/machine1\n\n"
                },
                {
                    "name": "Example 2. Introspect org.freedesktop.machine1.Machine on the bus",
                    "content": "$ gdbus introspect --system \\\n--dest org.freedesktop.machine1 \\\n--object-path /org/freedesktop/machine1/machine/rawhide\n\n"
                }
            ]
        },
        "VERSIONING": {
            "content": "These D-Bus interfaces follow the usual interface versioning guidelines[2].\n",
            "subsections": []
        },
        "NOTES": {
            "content": "1. New Control Group Interfaces\nhttps://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/\n\n2. the usual interface versioning guidelines\nhttp://0pointer.de/blog/projects/versioning-dbus.html\n\n\n\nsystemd 249                                                              ORG.FREEDESKTOP.MACHINE1(5)",
            "subsections": []
        }
    },
    "summary": "org.freedesktop.machine1 - The D-Bus interface of systemd-machined",
    "flags": [],
    "examples": [
        "$ gdbus introspect --system \\",
        "--dest org.freedesktop.machine1 \\",
        "--object-path /org/freedesktop/machine1",
        "$ gdbus introspect --system \\",
        "--dest org.freedesktop.machine1 \\",
        "--object-path /org/freedesktop/machine1/machine/rawhide"
    ],
    "see_also": []
}