NAME
org.freedesktop.portable1 - The D-Bus interface of systemd-portabledINTRODUCTION
systemd-portabled.service(8) is a system service that may be used to attach, detach and inspect portable services. This page describes the D-Bus interface.THE MANAGER OBJECT
The service exposes the following interfaces on the Manager object on the bus:node /org/freedesktop/portable1 { interface org.freedesktop.portable1.Manager { methods: GetImage(in s image, out o object); ListImages(out a(ssbtttso) images); GetImageOSRelease(in s image, out a{ss} os_release); GetImageMetadata(in s image, in as matches, out s image, out ay os_release, out a{say} units); GetImageMetadataWithExtensions(in s image, in as extensions, in as matches, in t flags, out s image, out ay os_release, out a{say} extensions, out a{say} units); GetImageState(in s image, out s state); GetImageStateWithExtensions(in s image, in as extensions, in t flags, out s state); AttachImage(in s image, in as matches, in s profile, in b runtime, in s copy_mode, out a(sss) changes); AttachImageWithExtensions(in s image, in as extensions, in as matches, in s profile, in s copy_mode, in t flags, out a(sss) changes); DetachImage(in s image, in b runtime, out a(sss) changes); DetachImageWithExtensions(in s image, in as extensions, in t flags, out a(sss) changes); ReattachImage(in s image, in as matches, in s profile, in b runtime, in s copy_mode, out a(sss) changes_removed, out a(sss) changes_updated); ReattachImageWithExtensions(in s image, in as extensions, in as matches, in s profile, in s copy_mode, in t flags, out a(sss) changes_removed, out a(sss) changes_updated); RemoveImage(in s image); MarkImageReadOnly(in s image, in b read_only); SetImageLimit(in s image, in t limit); SetPoolLimit(in t limit); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s PoolPath = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t PoolUsage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t PoolLimit = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly as Profiles = ['...', ...]; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; };
Methods
GetImage() may be used to get the image object path of the image with the specified name. ListImages() returns an array of all currently known images. The structures in the array consist of the following fields: image name, type, read-only flag, creation time, modification time, current disk space, usage and image object path. GetImageOSRelease() retrieves the OS release information of an image. This method returns an array of key value pairs read from the os-release(5) file in the image and is useful to identify the operating system used in a portable service. GetImageMetadata() retrieves metadata associated with an image. This method returns the image name, the image's os-release(5) content in the form of a (streamable) array of bytes, and a list of portable units contained in the image, in the form of a string (unit name) and an array of bytes with the content. GetImageMetadataWithExtensions() retrieves metadata associated with an image. This method is a superset of GetImageMetadata() with the addition of a list of extensions as input parameter, which were overlaid on top of the main image via AttachImageWithExtensions(). The path of each extension and an array of bytes with the content of the respective extension-release file are returned, one such structure for each extension named in the input arguments. GetImageState() retrieves the image state as one of the following strings:•detached
•attached
•attached-runtime
•enabled
•enabled-runtime
•running
•running-runtime
GetImageStateWithExtensions() is a superset of GetImageState(),
with additional support for a list of extensions as input parameters, which is
necessary to query the state in case the image was attached in that particular
way. The flag parameter is currently unused and reserved for future
purposes.
AttachImage() attaches a portable image to the system. This method takes
an image path or name, a list of strings that will be used to search for unit
files inside the image (partial or complete matches), a string indicating
which portable profile to use for the image (see Profiles property for
a list of available profiles), a boolean indicating whether to attach the
image only for the current boot session, and a string representing the
preferred copy mode (whether to copy the image or to just symlink it) with the
following possible values:
•(null)
•copy
•symlink
•copy
•symlink
•write
•mkdir
•unlink
#define SD_SYSTEMD_PORTABLE_RUNTIME (UINT64_C(1) << 0) #define SD_SYSTEMD_PORTABLE_FORCE_ATTACH (UINT64_C(1) << 1) #define SD_SYSTEMD_PORTABLE_FORCE_SYSEXT (UINT64_C(1) << 2)
Properties
PoolPath specifies the file system path where images are written to. PoolUsage specifies the current usage size of the image pool in bytes. PoolLimit specifies the size limit of the image pool in bytes. Profiles specifies the available runtime profiles for portable services.THE IMAGE OBJECT
The service exposes the following interfaces on the Image object on the bus:node /org/freedesktop/portable1 { interface org.freedesktop.portable1.Image { methods: GetOSRelease(out a{ss} os_release); GetMetadata(in as matches, out s image, out ay os_release, out a{say} units); GetMetadataWithExtensions(in as extensions, in as matches, in t flags, out s image, out ay os_release, out a{say} extensions, out a{say} units); GetState(out s state); GetStateWithExtensions(in as extensions, in t flags, out s state); Attach(in as matches, in s profile, in b runtime, in s copy_mode, out a(sss) changes); AttachWithExtensions(in as extensions, in as matches, in s profile, in s copy_mode, in t flags, out a(sss) changes); Detach(in b runtime, out a(sss) changes); DetachWithExtensions(in as extensions, in t flags, out a(sss) changes); Reattach(in as matches, in s profile, in b runtime, in s copy_mode, out a(sss) changes_removed, out a(sss) changes_updated); ReattacheWithExtensions(in as extensions, in as matches, in s profile, in s copy_mode, in t flags, out a(sss) changes_removed, out a(sss) changes_updated); Remove(); MarkReadOnly(in b read_only); SetLimit(in t limit); properties: @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s Name = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s Path = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly s Type = '...'; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly b ReadOnly = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t CreationTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t ModificationTimestamp = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t Usage = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t Limit = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t UsageExclusive = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("false") readonly t LimitExclusive = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; };
Methods
The following methods implement the same operation as the respective methods on the Manager object (see above). However, these methods operate on the image object and hence does not take an image name parameter. Invoking the methods directly on the Manager object has the advantage of not requiring a GetImage() call to get the image object for a specific image name. Calling the methods on the Manager object is hence a round trip optimization. List of methods:•GetOSRelease()
•GetMetadata()
•GetMetadataWithExtensions()
•GetState()
•Attach()
•AttachWithExtensions()
•Detach()
•DetachWithExtensions()
•Reattach()
•ReattacheWithExtensions()
•Remove()
•MarkReadOnly()
•SetLimit()
Properties
Name specifies the image name. Path specifies the file system path where image is stored. Type specifies the image type. ReadOnly specifies whether the image is read-only. CreationTimestamp specifies the image creation timestamp. ModificationTimestamp specifies the image modification timestamp. Usage specifies the image disk usage. Limit specifies the image disk usage limit. UsageExclusive specifies the image disk usage (exclusive). LimitExclusive specifies the image disk usage limit (exclusive).VERSIONING
These D-Bus interfaces follow the usual interface versioning guidelines[1].NOTES
- 1.
- the usual interface versioning guidelines
systemd 252 |