diff --git a/man/org.freedesktop.portable1.xml b/man/org.freedesktop.portable1.xml new file mode 100644 index 0000000000..e6d2f4f536 --- /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 bd0c9e0573..3f37ad1164 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 c13c8efc5c..c8e589e0f0 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 ce91b4fcbb..23906f2663 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 diff --git a/src/portable/portabled-bus.c b/src/portable/portabled-bus.c index c31ab092b4..fa143b71c0 100644 --- a/src/portable/portabled-bus.c +++ b/src/portable/portabled-bus.c @@ -3,6 +3,7 @@ #include "alloc-util.h" #include "btrfs-util.h" #include "bus-common-errors.h" +#include "bus-object.h" #include "bus-polkit.h" #include "discover-image.h" #include "fd-util.h" @@ -359,21 +360,91 @@ const sd_bus_vtable manager_vtable[] = { SD_BUS_PROPERTY("PoolUsage", "t", property_get_pool_usage, 0, 0), SD_BUS_PROPERTY("PoolLimit", "t", property_get_pool_limit, 0, 0), SD_BUS_PROPERTY("Profiles", "as", property_get_profiles, 0, 0), - SD_BUS_METHOD("GetImage", "s", "o", method_get_image, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ListImages", NULL, "a(ssbtttso)", method_list_images, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetImageOSRelease", "s", "a{ss}", method_get_image_os_release, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetImageMetadata", "sas", "saya{say}", method_get_image_metadata, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetImageState", "s", "s", method_get_image_state, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("AttachImage", "sassbs", "a(sss)", method_attach_image, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("DetachImage", "sb", "a(sss)", method_detach_image, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("ReattachImage", "sassbs", "a(sss)a(sss)", method_reattach_image, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("RemoveImage", "s", NULL, method_remove_image, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("MarkImageReadOnly", "sb", NULL, method_mark_image_read_only, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetImageLimit", "st", NULL, method_set_image_limit, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetPoolLimit", "t", NULL, method_set_pool_limit, SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("GetImage", + SD_BUS_ARGS("s", image), + SD_BUS_RESULT("o", object), + method_get_image, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("ListImages", + SD_BUS_NO_ARGS, + SD_BUS_RESULT("a(ssbtttso)", images), + method_list_images, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("GetImageOSRelease", + SD_BUS_ARGS("s", image), + SD_BUS_RESULT("a{ss}", os_release), + method_get_image_os_release, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("GetImageMetadata", + SD_BUS_ARGS("s", image, + "as", matches), + SD_BUS_RESULT("s", image, + "ay", os_release, + "a{say}", units), + method_get_image_metadata, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("GetImageState", + SD_BUS_ARGS("s", image), + SD_BUS_RESULT("s", state), + method_get_image_state, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("AttachImage", + SD_BUS_ARGS("s", image, + "as", matches, + "s", profile, + "b", runtime, + "s", copy_mode), + SD_BUS_RESULT("a(sss)", changes), + method_attach_image, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("DetachImage", + SD_BUS_ARGS("s", image, + "b", runtime), + SD_BUS_RESULT("a(sss)", changes), + method_detach_image, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("ReattachImage", + SD_BUS_ARGS("s", image, + "as", matches, + "s", profile, + "b", runtime, + "s", copy_mode), + SD_BUS_RESULT("a(sss)", changes_removed, + "a(sss)", changes_updated), + method_reattach_image, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("RemoveImage", + SD_BUS_ARGS("s", image), + SD_BUS_NO_RESULT, + method_remove_image, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("MarkImageReadOnly", + SD_BUS_ARGS("s", image, + "b", read_only), + SD_BUS_NO_RESULT, + method_mark_image_read_only, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("SetImageLimit", + SD_BUS_ARGS("s", image, + "t", limit), + SD_BUS_NO_RESULT, + method_set_image_limit, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("SetPoolLimit", + SD_BUS_ARGS("t", limit), + SD_BUS_NO_RESULT, + method_set_pool_limit, + SD_BUS_VTABLE_UNPRIVILEGED), SD_BUS_VTABLE_END }; +const BusObjectImplementation manager_object = { + "/org/freedesktop/portable1", + "org.freedesktop.portable1.Manager", + .vtables = BUS_VTABLES(manager_vtable), + .children = BUS_IMPLEMENTATIONS(&image_object), +}; + static int reply_portable_compose_message(sd_bus_message *reply, const PortableChange *changes, size_t n_changes) { size_t i; int r; diff --git a/src/portable/portabled-image-bus.c b/src/portable/portabled-image-bus.c index 630648ba3c..75bb4d80c1 100644 --- a/src/portable/portabled-image-bus.c +++ b/src/portable/portabled-image-bus.c @@ -9,6 +9,7 @@ #include "bus-common-errors.h" #include "bus-get-properties.h" #include "bus-label.h" +#include "bus-object.h" #include "bus-polkit.h" #include "bus-util.h" #include "discover-image.h" @@ -707,15 +708,60 @@ const sd_bus_vtable image_vtable[] = { SD_BUS_PROPERTY("Limit", "t", NULL, offsetof(Image, limit), 0), SD_BUS_PROPERTY("UsageExclusive", "t", NULL, offsetof(Image, usage_exclusive), 0), SD_BUS_PROPERTY("LimitExclusive", "t", NULL, offsetof(Image, limit_exclusive), 0), - SD_BUS_METHOD("GetOSRelease", NULL, "a{ss}", bus_image_method_get_os_release, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetMetadata", "as", "saya{say}", bus_image_method_get_metadata, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("GetState", NULL, "s", bus_image_method_get_state, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Attach", "assbs", "a(sss)", bus_image_method_attach, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Detach", "b", "a(sss)", bus_image_method_detach, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Reattach", "assbs", "a(sss)a(sss)", bus_image_method_reattach, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("Remove", NULL, NULL, bus_image_method_remove, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("MarkReadOnly", "b", NULL, bus_image_method_mark_read_only, SD_BUS_VTABLE_UNPRIVILEGED), - SD_BUS_METHOD("SetLimit", "t", NULL, bus_image_method_set_limit, SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("GetOSRelease", + SD_BUS_NO_ARGS, + SD_BUS_RESULT("a{ss}", os_release), + bus_image_method_get_os_release, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("GetMetadata", + SD_BUS_ARGS("as", matches), + SD_BUS_RESULT("s", image, + "ay", os_release, + "a{say}", units), + bus_image_method_get_metadata, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("GetState", + SD_BUS_NO_ARGS, + SD_BUS_RESULT("s", state), + bus_image_method_get_state, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("Attach", + SD_BUS_ARGS("as", matches, + "s", profile, + "b", runtime, + "s", copy_mode), + SD_BUS_RESULT("a(sss)", changes), + bus_image_method_attach, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("Detach", + SD_BUS_ARGS("b", runtime), + SD_BUS_RESULT("a(sss)", changes), + bus_image_method_detach, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("Reattach", + SD_BUS_ARGS("as", matches, + "s", profile, + "b", runtime, + "s", copy_mode), + SD_BUS_RESULT("a(sss)", changes_removed, + "a(sss)", changes_updated), + bus_image_method_reattach, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("Remove", + SD_BUS_NO_ARGS, + SD_BUS_NO_RESULT, + bus_image_method_remove, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("MarkReadOnly", + SD_BUS_ARGS("b", read_only), + SD_BUS_NO_RESULT, + bus_image_method_mark_read_only, + SD_BUS_VTABLE_UNPRIVILEGED), + SD_BUS_METHOD_WITH_ARGS("SetLimit", + SD_BUS_ARGS("t", limit), + SD_BUS_NO_RESULT, + bus_image_method_set_limit, + SD_BUS_VTABLE_UNPRIVILEGED), SD_BUS_VTABLE_END }; @@ -919,3 +965,10 @@ int bus_image_node_enumerator(sd_bus *bus, const char *path, void *userdata, cha return 1; } + +const BusObjectImplementation image_object = { + "/org/freedesktop/portable1/image", + "org.freedesktop.portable1.Image", + .fallback_vtables = BUS_FALLBACK_VTABLES({image_vtable, bus_image_object_find}), + .node_enumerator = bus_image_node_enumerator, +}; diff --git a/src/portable/portabled-image-bus.h b/src/portable/portabled-image-bus.h index e5faf43d90..763a0890f9 100644 --- a/src/portable/portabled-image-bus.h +++ b/src/portable/portabled-image-bus.h @@ -15,6 +15,7 @@ int bus_image_common_mark_read_only(Manager *m, sd_bus_message *message, const c int bus_image_common_set_limit(Manager *m, sd_bus_message *message, const char *name_or_path, Image *image, sd_bus_error *error); extern const sd_bus_vtable image_vtable[]; +extern const BusObjectImplementation image_object; int bus_image_path(Image *image, char **ret); diff --git a/src/portable/portabled.c b/src/portable/portabled.c index 8a17f09365..3c8e20e0f3 100644 --- a/src/portable/portabled.c +++ b/src/portable/portabled.c @@ -15,6 +15,7 @@ #include "portabled-image-bus.h" #include "portabled.h" #include "process-util.h" +#include "service-util.h" #include "signal-util.h" static Manager* manager_unref(Manager *m); @@ -73,17 +74,9 @@ static int manager_connect_bus(Manager *m) { if (r < 0) return log_error_errno(r, "Failed to connect to system bus: %m"); - r = sd_bus_add_object_vtable(m->bus, NULL, "/org/freedesktop/portable1", "org.freedesktop.portable1.Manager", manager_vtable, m); + r = bus_add_implementation(m->bus, &manager_object, m); if (r < 0) - return log_error_errno(r, "Failed to add manager object vtable: %m"); - - r = sd_bus_add_fallback_vtable(m->bus, NULL, "/org/freedesktop/portable1/image", "org.freedesktop.portable1.Image", image_vtable, bus_image_object_find, m); - if (r < 0) - return log_error_errno(r, "Failed to add image object vtable: %m"); - - r = sd_bus_add_node_enumerator(m->bus, NULL, "/org/freedesktop/portable1/image", bus_image_node_enumerator, m); - if (r < 0) - return log_error_errno(r, "Failed to add image enumerator: %m"); + return r; r = bus_log_control_api_register(m->bus); if (r < 0) @@ -137,6 +130,14 @@ static int run(int argc, char *argv[]) { log_setup(); + r = service_parse_argv("systemd-portabled.service", + "Manage registrations of portable images.", + BUS_IMPLEMENTATIONS(&manager_object, + &log_control_object), + argc, argv); + if (r <= 0) + return r; + umask(0022); if (argc != 1) diff --git a/src/portable/portabled.h b/src/portable/portabled.h index 03a9996916..71ec41d4f1 100644 --- a/src/portable/portabled.h +++ b/src/portable/portabled.h @@ -4,6 +4,7 @@ #include "sd-bus.h" #include "sd-event.h" +#include "bus-object.h" #include "hashmap.h" #include "list.h" @@ -23,3 +24,5 @@ struct Manager { LIST_HEAD(Operation, operations); unsigned n_operations; }; + +extern const BusObjectImplementation manager_object;