From 4976db220d9f7e31a5b3d72efd627847a2c70011 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Fri, 2 Jun 2017 14:52:03 +0100 Subject: [PATCH 04/43] spec: Document the initial Containers1 interface Signed-off-by: Simon McVittie --- doc/dbus-specification.xml | 450 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 450 insertions(+) diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index c33f0a0c..abd83530 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -6416,6 +6416,42 @@ + + org.freedesktop.DBus.Containers1.Instance + OBJECT_PATH + + The container instance object path of the server through + which this connection is connected, as returned by + AddContainerServer. Omitted from the + dictionary if this connection is not via a container's + server. + + + + + org.freedesktop.DBus.Containers1.Type + STRING + + The container technology that created the container instance, + as passed to AddContainerServer. Omitted + from the dictionary if this connection is not via a + container's server. For example, a typical value for + a Flatpak app would be org.flatpak. + + + + + org.freedesktop.DBus.Containers1.Name + STRING + + The contained app name for the container instance, + as passed to AddContainerServer. Omitted + from the dictionary if this connection is not via a + container's server. For example, a typical value for + a Flatpak app would be org.gnome.Weather. + + + @@ -6647,6 +6683,420 @@ + + <literal>org.freedesktop.DBus.Containers1.AddContainerServer</literal> + + As a method: + + AddContainerServer (in STRING container_type, + in STRING container_name, + in DICT<STRING,VARIANT> metadata, + in DICT<STRING,VARIANT> named_arguments, + out OBJECT_PATH container_instance, + out ARRAY<BYTE> socket_path, + out STRING connectable_address) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + + Reversed domain name identifying a container manager or + container technology, such as + org.flatpak or + io.snapcraft + + + + 1 + STRING + + Some unique identifier for an application or container, + whose meaning is defined by the maintainers of the + container type + + + + 2 + DICT<STRING,VARIANT> + + Metadata describing the application or container, with the + keys and values defined by the maintainers of the container + type + + + + 3 + DICT<STRING,VARIANT> + + Additional arguments that extend this method. + The only named arguments that are allowed are the ones + listed in the + org.freedesktop.DBus.Containers1.SupportedArguments + property. All other named arguments are an error. + + + + 4 + OBJECT_PATH + + An opaque object path identifying the new container + instance. + + + + 5 + ARRAY<BYTE> + + The absolute filesystem path of the resulting + AF_UNIX socket, followed by a single + zero (nul) byte, for example + /run/user/1000/dbus-12345vwxyz\x00 + where \x00 represents the terminating zero byte. + + + + 6 + STRING + + A connectable D-Bus address, for example + unix:path=/run/user/1000/dbus-12345vwxyz. + + + + + + + + + Set up a new server socket for use in an application container. + Clients can connect to that socket, and the result will be as + though they had connected to the message bus, with a few differences. + The intention is that a container manager will call this method + to get a new server socket, bind-mount the server socket + into a location that is accessible by the confined (sandboxed) + application, and ensure that the normal message bus socket is + not accessible by the confined application. + + + + Each call to this method creates a new + container instance, identified by an object + path. This is true even if the specified container type and name + are the same as for a pre-existing container instance, because the + new container instance might represent a different version of the + confined application with different characteristics and restrictions. + The message bus may provide an object at the given object path, + but is not required to do so. + + + + Metadata from the first three arguments is stored by the message + bus, but not interpreted; software that interacts with the + container manager can use this metadata. The message bus may limit + the size of the metadata that it is willing to store. + + + + The last argument (the named arguments) + will be used in future versions of this specification to modify + the behaviour of this method call; all keys in this dictionary not + containing . are reserved by this specification + for this purpose. It can also contain implementation-specific + arguments for a particular message bus implementation, which + should start with a reversed domain name in the same way as + interface names. + + + + In the most basic form of a call to this method, the new server + socket is an AF_UNIX socket at a path chosen + by the message bus and returned from the method. Future versions + of this specification are likely to provide a way for the + message bus implementation to receive a socket from the caller + and arrange for it to listen for connections, using the named + arguments dictionary. + + + + Connections to the new server socket are said to be + confined. The message bus may prevent + confined connections from calling certain security-sensitive methods, + and may apply lower limits to these connections. However, container + managers and services must not rely on confined connections having + any particular filtering applied to them. + + + + In the most basic form of a call to this method, the server + socket will cease to listen for new connections when the caller of + this method disconnects from the bus. Any confined connections that + are already active are unaffected. Future versions of this + specification are likely to provide a way for the caller to alter + this behaviour by specifying named arguments. + + + + The container instance object path remains valid for as long as + either the server socket is listening for new connections, or any + confined connection via the same server socket remains open. + + + + + <literal>org.freedesktop.DBus.Containers1.StopContainerInstance</literal> + + As a method: + + StopContainerInstance (in OBJECT_PATH container_instance) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + OBJECT_PATH + + The opaque object path that was returned from the + AddContainerServer method, identifying a container instance + + + + + + + + + Terminate the container instance. The server will stop listening for + new connections, and any existing connections to that server will + be disconnected. If the given object path does not represent an + active container instance, the + org.freedesktop.DBus.Error.NotContainer error + is returned. If the given container instance exists but + the caller of this method is not allowed to stop it (for example + because the caller is in an app-container or because their user + ID does not match the user ID of the creator of the app-container), + the org.freedesktop.DBus.Error.AccessDenied error + is returned and nothing is stopped. + + + + + <literal>org.freedesktop.DBus.Containers1.StopContainerListening</literal> + + As a method: + + StopContainerListening (in OBJECT_PATH container_instance) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + OBJECT_PATH + + The opaque object path that was returned from the + AddContainerServer method, identifying a container instance + + + + + + + + + Stop listening for new connections to the server in the given + container instance, but do not disconnect any existing connections. + If the given object path does not represent an active container + instance, the + org.freedesktop.DBus.Error.NotContainer error + is returned. If the given container instance exists but + the caller of this method is not allowed to stop it (for example + because the caller is in an app-container or because their user + ID does not match the user ID of the creator of the app-container), + the org.freedesktop.DBus.Error.AccessDenied error + is returned and nothing is stopped. + + + + + <literal>org.freedesktop.DBus.Containers1.GetConnectionContainerInstance</literal> + + As a method: + + GetConnectionContainerInstance (in STRING bus_name, + out OBJECT_PATH container_instance, + out STRING container_type, + out STRING container_name, + out DICT<STRING,VARIANT> metadata) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + STRING + Unique or well-known bus name of the connection to + query, such as :12.34 or + com.example.tea + + + 1 + OBJECT_PATH + + The opaque object path that was returned from the + AddContainerServer method, identifying a container instance + + + + 2 + STRING + + Reversed domain name identifying a container manager or + container technology, such as + org.flatpak or + io.snapcraft + + + + 3 + STRING + + Some unique identifier for an application or container, + whose meaning is defined by the maintainers of the + container type + + + + 4 + DICT<STRING,VARIANT> + + Metadata describing the application or container, with the + keys and values defined by the maintainers of the container + type + + + + + + + + + If the given unique or well-known bus name is a connection to a + container server, return information about that container instance. + If the bus name exists but is not confined (in other words, if it + is a direct connection to the main message bus socket), the + org.freedesktop.DBus.Error.NotContainer error + is returned instead. If the given bus name has no owner at all, the + org.freedesktop.DBus.Error.NameHasNoOwner error + is returned instead. + + + + + <literal>org.freedesktop.DBus.Containers1.GetContainerInstanceInfo</literal> + + As a method: + + GetContainerInstanceInfo (in OBJECT_PATH container_instance, + out STRING container_type, + out STRING container_name, + out DICT<STRING,VARIANT> metadata) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + OBJECT_PATH + + The opaque object path that was returned from the + AddContainerServer method, identifying a container instance + + + + 1 + STRING + + Reversed domain name identifying a container manager or + container technology, such as + org.flatpak or + io.snapcraft + + + + 2 + STRING + + Some unique identifier for an application or container, + whose meaning is defined by the maintainers of the + container type + + + + 3 + DICT<STRING,VARIANT> + + Metadata describing the application or container, with the + keys and values defined by the maintainers of the container + type + + + + + + + + + If the given object path represents an active container instance, + return information about it. If not, the + org.freedesktop.DBus.Error.NotContainer error + is returned. + + + <literal>org.freedesktop.DBus.Monitoring.BecomeMonitor</literal> -- 2.13.2