From: Luca Boccassi Date: Fri, 12 Feb 2021 16:35:38 +0000 (+0000) Subject: portabled: add DBUS documentation X-Git-Tag: v248-rc1~114^2 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=23e5c8d2966622f3c5c15ac3c2ac5ed04a72b77d;p=thirdparty%2Fsystemd.git portabled: add DBUS documentation --- diff --git a/man/org.freedesktop.portable1.xml b/man/org.freedesktop.portable1.xml new file mode 100644 index 00000000000..e6d2f4f536d --- /dev/null +++ b/man/org.freedesktop.portable1.xml @@ -0,0 +1,427 @@ + + + + + + + org.freedesktop.portable1 + systemd + + + + org.freedesktop.portable1 + 5 + + + + org.freedesktop.portable1 + The D-Bus interface of systemd-portabled + + + + Introduction + + + systemd-portabled.service8 + 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) UNNAMED); + 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); + GetImageState(in s image, + out s state); + AttachImage(in s image, + in as matches, + in s profile, + in b runtime, + in s copy_mode, + out a(sss) changes); + DetachImage(in s image, + in b runtime, + 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); + 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-release5 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. + + GetImageState() retrieves the image state as one of the following + strings: + + detached + + attached + + attached-runtime + + enabled + + enabled-runtime + + running + + running-runtime + + + 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 + + This method returns the list of changes applied to the system (for example, which unit was + added and is now available as a system service). Each change is represented as a triplet of + strings: the type of change applied, the path on which it was applied, and the source + (if any). The type of change applied will be one of the following possible values: + + copy + + symlink + + write + + mkdir + + Note that an image cannot be attached if a unit that it contains is already present + on the system. + + DetachImage() detaches a portable image from the system. + This method takes an image path or name, and a boolean indicating whether the image to + detach was attached only for the current boot session or persistently. This method + returns the list of changes applied to the system (for example, which unit was removed + and is no longer available as a system service). Each change is represented as a triplet of + strings: the type of change applied, the path on which it was applied, and the source + (if any). The type of change applied will be one of the following possible values: + + unlink + + Note that an image cannot be detached if a unit that it contains is running. + + ReattachImage() combines the effects of the + AttachImage() method and the DetachImage() method. + The difference is that it is allowed to reattach an image while one or more of its units + are running. The reattach operation will fail if no matching image is attached. + The input parameters match the AttachImage() method, and the return + parameters are the combination of the return parameters of the + DetachImage() method (first array, units that were removed) and the + AttachImage() method (second array, units that were updated or added). + + RemoveImage() removes the image with the specified name. + + MarkImageReadOnly() toggles the read-only flag of an image. + + SetPoolLimit() sets an overall quota limit on the pool of images. + + SetImageLimit() sets a per-image quota limit. + + + + 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} UNNAMED); + GetMetadata(in as matches, + out s image, + out ay os_release, + out a{say} units); + GetState(out s UNNAMED); + Attach(in as matches, + in s profile, + in b runtime, + in s copy_mode, + out a(sss) changes); + Detach(in b runtime, + 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); + 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() + + GetState() + + Attach() + + Detach() + + Reattach() + + 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. + + diff --git a/man/portablectl.xml b/man/portablectl.xml index bd0c9e0573b..3f37ad11642 100644 --- a/man/portablectl.xml +++ b/man/portablectl.xml @@ -434,6 +434,7 @@ See Also systemd1, + org.freedesktop.portable15, systemd-portabled.service8 diff --git a/man/rules/meson.build b/man/rules/meson.build index c13c8efc5c3..c8e589e0f04 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -57,6 +57,7 @@ manpages = [ ['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'], ['org.freedesktop.machine1', '5', [], 'ENABLE_MACHINED'], ['org.freedesktop.oom1', '5', [], 'ENABLE_OOMD'], + ['org.freedesktop.portable1', '5', [], 'ENABLE_PORTABLED'], ['org.freedesktop.resolve1', '5', [], 'ENABLE_RESOLVE'], ['org.freedesktop.systemd1', '5', [], ''], ['org.freedesktop.timedate1', '5', [], 'ENABLE_TIMEDATED'], diff --git a/man/systemd-portabled.service.xml b/man/systemd-portabled.service.xml index ce91b4fcbb0..23906f2663a 100644 --- a/man/systemd-portabled.service.xml +++ b/man/systemd-portabled.service.xml @@ -43,7 +43,8 @@ See Also systemd1, - portablectl1 + portablectl1, + org.freedesktop.portable15