{
    "content": [
        {
            "type": "text",
            "text": "# org.freedesktop.import1(5) (man)\n\n**Summary:** org.freedesktop.import1 - The D-Bus interface of systemd-importd\n\n## Examples\n\n- `$ gdbus introspect --system \\`\n- `--dest org.freedesktop.import1 \\`\n- `--object-path /org/freedesktop/import1`\n- `$ gdbus introspect --system \\`\n- `--dest org.freedesktop.import1 \\`\n- `--object-path /org/freedesktop/import1/transfer/1`\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **INTRODUCTION** (9 lines)\n- **THE MANAGER OBJECT** (72 lines) — 2 subsections\n  - Methods (64 lines)\n  - Signals (8 lines)\n- **THE TRANSFER OBJECT** (36 lines) — 2 subsections\n  - Methods (4 lines)\n  - Properties (14 lines)\n- **EXAMPLES** (1 lines) — 2 subsections\n  - Example 1. Introspect org.freedesktop.import1.Manager on the (5 lines)\n  - Example 2. Introspect org.freedesktop.import1.Transfer on th (5 lines)\n- **VERSIONING** (2 lines)\n- **NOTES** (6 lines)\n\n## Full Content\n\n### NAME\n\norg.freedesktop.import1 - The D-Bus interface of systemd-importd\n\n### INTRODUCTION\n\nsystemd-importd.service(8) is a system service which may be used to import, export and\ndownload additional system images. These images can be used by tools such as systemd-\nnspawn(1) to run local containers. The service is used as the backend for machinectl\npull-raw, machinectl pull-tar and related commands. This page describes the D-Bus interface.\n\nNote that systemd-importd.service(8) is mostly a small companion service for systemd-\nmachined.service(8). Many operations to manipulate local container and VM images are hence\navailable via the systemd-machined D-Bus API, c.f.  org.freedesktop.machine1(5).\n\n### THE MANAGER OBJECT\n\nThe service exposes the following interfaces on the Manager object on the bus:\n\nnode /org/freedesktop/import1 {\ninterface org.freedesktop.import1.Manager {\nmethods:\nImportTar(in  h fd,\nin  s localname,\nin  b force,\nin  b readonly,\nout u transferid,\nout o transferpath);\nImportRaw(in  h fd,\nin  s localname,\nin  b force,\nin  b readonly,\nout u transferid,\nout o transferpath);\nImportFileSystem(in  h fd,\nin  s localname,\nin  b force,\nin  b readonly,\nout u transferid,\nout o transferpath);\nExportTar(in  s localname,\nin  h fd,\nin  s format,\nout u transferid,\nout o transferpath);\nExportRaw(in  s localname,\nin  h fd,\nin  s format,\nout u transferid,\nout o transferpath);\nPullTar(in  s url,\nin  s localname,\nin  s verifymode,\nin  b force,\nout u transferid,\nout o transferpath);\nPullRaw(in  s url,\nin  s localname,\nin  s verifymode,\nin  b force,\nout u transferid,\nout o transferpath);\nListTransfers(out a(usssdo) transfers);\nCancelTransfer(in  u transferid);\nsignals:\nTransferNew(u transferid,\no transferpath);\nTransferRemoved(u transferid,\no transferpath,\ns result);\n};\ninterface org.freedesktop.DBus.Peer { ... };\ninterface org.freedesktop.DBus.Introspectable { ... };\ninterface org.freedesktop.DBus.Properties { ... };\n};\n\n#### Methods\n\nImportTar() and ImportRaw() import a system image and place it into /var/lib/machines/. The\nfirst argument should be a file descriptor (opened for reading) referring to the tar or raw\nfile to import. It should reference a file on disk, a pipe or a socket. When ImportTar() is\nused the file descriptor should refer to a tar file, optionally compressed with gzip(1),\nbzip2(1), or xz(1).  systemd-importd will detect the used compression scheme (if any)\nautomatically. When ImportRaw() is used the file descriptor should refer to a raw or qcow2\ndisk image containing an MBR or GPT disk label, also optionally compressed with gzip, bzip2\nor xz. In either case, if the file is specified as a file descriptor on disk, progress\ninformation is generated for the import operation (as in that case we know the total size on\ndisk). If a socket or pipe is specified, progress information is not available. The file\ndescriptor argument is followed by a local name for the image. This should be a name suitable\nas a hostname and will be used to name the imported image below /var/lib/machines/. A tar\nimport is placed as a directory tree or a btrfs(8) subvolume below /var/lib/machines/ under\nthe specified name with no suffix appended. A raw import is placed as a file in\n/var/lib/machines/ with the .raw suffix appended. If the force argument is true, any\npre-existing image with the same name is removed before starting the operation. Otherwise,\nthe operation fails if an image with the same name already exists. Finally, the readonly\nargument controls whether to create a writable or read-only image. Both methods return\nimmediately after starting the import, with the import transfer ongoing. They return a pair\nof transfer identifier and object path, which may be used to retrieve progress information\nabout the transfer or to cancel it. The transfer identifier is a simple numeric identifier,\nthe object path references an org.freedesktop.import1.Transfer object, see below. Listen for\na TransferRemoved signal for the transfer ID in order to detect when a transfer is complete.\nThe returned transfer object is useful to determine the current progress or log output of the\nongoing import operation.\n\nExportTar() and ExportRaw() implement the reverse operation, and may be used to export a\nsystem image in order to place it in a tar or raw image. They take the machine name to export\nas their first parameter, followed by a file descriptor (opened for writing) where the tar or\nraw file will be written. It may either reference a file on disk or a pipe/socket. The third\nargument specifies in which compression format to write the image. It takes one of\n\"uncompressed\", \"xz\", \"bzip2\" or \"gzip\", depending on which compression scheme is required.\nThe image written to the specified file descriptor will be a tar file in case of ExportTar()\nor a raw disk image in case of ExportRaw(). Note that currently raw disk images may not be\nexported as tar files, and vice versa. This restriction might be lifted eventually. The\nmethod returns a transfer identifier and object path for cancelling or tracking the export\noperation, similar to ImportTar() or ImportRaw() as described above.\n\nPullTar() and PullRaw() may be used to download, verify and import a system image from a URL.\nThey take an URL argument which should point to a tar or raw file on the \"http://\" or\n\"https://\" protocols, possibly compressed with xz, bzip2 or gzip. The second argument is a\nlocal name for the image. It should be suitable as a hostname, similar to the matching\nargument of the ImportTar() and ImportRaw() methods above. The third argument indicates the\nverification mode for the image. It may be one of \"no\", \"checksum\", \"signature\".  \"no\" turns\noff any kind of verification of the image; \"checksum\" looks for a SHA256SUM file next to the\ndownloaded image and verifies any SHA256 hash value in that file against the image;\n\"signature\" does the same but also tries to authenticate the SHA256SUM file via gpg(8) first.\nThe last argument indicates whether to replace a possibly pre-existing image with the same\nlocal name (if \"true\"), or whether to fail (if \"false\"). Like the import and export calls\nabove, these calls return a pair of transfer identifier and object path for the ongoing\ndownload.\n\nListTransfers() returns a list of ongoing import, export or download operations as created\nwith the six calls described above. It returns an array of structures which consist of the\nnumeric transfer identifier, a string indicating the operation (one of \"import-tar\",\n\"import-raw\", \"export-tar\", \"export-raw\", \"pull-tar\" or \"pull-raw\"), a string describing the\nremote file (in case of download operations this is the source URL, in case of import/export\noperations this is a short string describing the file descriptor passed in), a string with\nthe local machine image name, a progress value between 0.0 (for 0%) and 1.0 (for 100%), as\nwell as the transfer object path.\n\nCancelTransfer() may be used to cancel an ongoing import, export or download operation.\nSimply specify the transfer identifier to cancel the ongoing operation.\n\n#### Signals\n\nThe TransferNew signal is generated each time a new transfer is started with the import,\nexport or download calls described above. It carries the transfer ID and object path that\nhave just been created.\n\nThe TransferRemoved signal is sent each time a transfer finishes, is canceled or fails. It\nalso carries the transfer ID and object path, followed by a string indicating the result of\nthe operation, which is one of \"done\" (on success), \"canceled\" or \"failed\".\n\n### THE TRANSFER OBJECT\n\nnode /org/freedesktop/import1/transfer/1 {\ninterface org.freedesktop.import1.Transfer {\nmethods:\nCancel();\nsignals:\nLogMessage(u priority,\ns line);\nproperties:\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"const\")\nreadonly u Id = ...;\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"const\")\nreadonly s Local = '...';\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"const\")\nreadonly s Remote = '...';\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"const\")\nreadonly s Type = '...';\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"const\")\nreadonly s Verify = '...';\n@org.freedesktop.DBus.Property.EmitsChangedSignal(\"false\")\nreadonly d Progress = ...;\n};\ninterface org.freedesktop.DBus.Peer { ... };\ninterface org.freedesktop.DBus.Introspectable { ... };\ninterface org.freedesktop.DBus.Properties { ... };\n};\n\n#### Methods\n\nThe Cancel() method may be used to cancel the transfer. It takes no parameters. This method\nis pretty much equivalent to the CancelTransfer() method on the Manager interface (see\nabove), but is exposed on the Transfer object itself instead of taking a transfer ID.\n\n#### Properties\n\nThe Id property exposes the numeric transfer ID of the transfer object.\n\nThe Local, Remote and Type properties expose the local container name of this transfer, the\nremote source (in case of download: the URL, in case of import/export: a string describing\nthe file descriptor passed in), and the type of operation (see the Manager's ListTransfer()\nmethod above for an explanation of the possible values).\n\nThe Verify property exposes the selected verification setting and is only defined for\ndownload operations (see above).\n\nThe Progress property exposes the current progress of the transfer as a value between 0.0 and\n1.0. To show a progress bar on screen we recommend to query this value in regular intervals,\nfor example every 500 ms or so.\n\n### EXAMPLES\n\n#### Example 1. Introspect org.freedesktop.import1.Manager on the bus\n\n$ gdbus introspect --system \\\n--dest org.freedesktop.import1 \\\n--object-path /org/freedesktop/import1\n\n#### Example 2. Introspect org.freedesktop.import1.Transfer on the bus\n\n$ gdbus introspect --system \\\n--dest org.freedesktop.import1 \\\n--object-path /org/freedesktop/import1/transfer/1\n\n### VERSIONING\n\nThese D-Bus interfaces follow the usual interface versioning guidelines[1].\n\n### NOTES\n\n1. the usual interface versioning guidelines\nhttp://0pointer.de/blog/projects/versioning-dbus.html\n\n\n\nsystemd 249                                                               ORG.FREEDESKTOP.IMPORT1(5)\n\n"
        }
    ],
    "structuredContent": {
        "command": "org.freedesktop.import1",
        "section": "5",
        "mode": "man",
        "summary": "org.freedesktop.import1 - The D-Bus interface of systemd-importd",
        "synopsis": null,
        "flags": [],
        "examples": [
            "$ gdbus introspect --system \\",
            "--dest org.freedesktop.import1 \\",
            "--object-path /org/freedesktop/import1",
            "$ gdbus introspect --system \\",
            "--dest org.freedesktop.import1 \\",
            "--object-path /org/freedesktop/import1/transfer/1"
        ],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "INTRODUCTION",
                "lines": 9,
                "subsections": []
            },
            {
                "name": "THE MANAGER OBJECT",
                "lines": 72,
                "subsections": [
                    {
                        "name": "Methods",
                        "lines": 64
                    },
                    {
                        "name": "Signals",
                        "lines": 8
                    }
                ]
            },
            {
                "name": "THE TRANSFER OBJECT",
                "lines": 36,
                "subsections": [
                    {
                        "name": "Methods",
                        "lines": 4
                    },
                    {
                        "name": "Properties",
                        "lines": 14
                    }
                ]
            },
            {
                "name": "EXAMPLES",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Example 1. Introspect org.freedesktop.import1.Manager on the bus",
                        "lines": 5
                    },
                    {
                        "name": "Example 2. Introspect org.freedesktop.import1.Transfer on the bus",
                        "lines": 5
                    }
                ]
            },
            {
                "name": "VERSIONING",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "NOTES",
                "lines": 6,
                "subsections": []
            }
        ]
    }
}