From 39262d0a2913fc8ee951beb3d0241720abf651c0 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Fri, 2 Jun 2017 14:52:03 +0100 Subject: spec: Document the initial Containers1 interface Signed-off-by: Simon McVittie Reviewed-by: Philip Withnall Bug: https://bugs.freedesktop.org/show_bug.cgi?id=101354 --- doc/dbus-specification.xml | 552 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 552 insertions(+) diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index c33f0a0c..abafb819 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -6416,6 +6416,44 @@ + + org.freedesktop.DBus.Containers1.Instance + OBJECT_PATH + + The container instance object path of the server through + which this connection is connected, as returned by + AddServer. 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 AddServer. + Omitted from the dictionary if this connection is not + via a container's server. For example, a typical value + for a Flatpak application would be + org.flatpak. + + + + + org.freedesktop.DBus.Containers1.Name + STRING + + The contained app name for the container instance, + as passed to AddServer. Omitted + from the dictionary if this connection is not via a + container's server. For example, a typical value for + a Flatpak application would be + org.gnome.Weather. + + + @@ -6647,6 +6685,520 @@ + + <literal>org.freedesktop.DBus.Containers1.AddServer</literal> + + As a method: + + AddServer (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. It must follow the + same syntactic rules as a + D-Bus + interface name. + + + + 1 + STRING + + Some unique identifier for an application or + container, whose meaning is defined by the + maintainers of the container type. If the container + type does not have a concept of identifying or + naming its applications or containers by a string, + using the empty string here is suggested. + + + + 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. Even if the specified container type and name are the + same as for a pre-existing container instance, each call + creates a new server with a new unique object path, 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 method call may fail with the error + org.freedesktop.DBus.Error.LimitsExceeded + if the caller provides more metadata than the message bus + 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. For example, GLib's gdbus-daemon might use + org.gtk.GDBus.SomeArgument if it used this + extension point. + + + + 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 by the message bus. + + + + In the most basic form of a call to this method, the server + socket will cease to listen for new connections (in the same + way as if StopListening had been called + successfully) 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 one or more confined connection via the same server + socket remain open, or there is a way for the server socket + to produce new connections in future (in other words, + either it is preparing to listen for new connections, or + it is currently listening for new connections). When the + container instance has ceased to listen for new connections + and no longer has any confined connections, the object path + becomes invalid, and API calls that specify it will fail with + the org.freedesktop.DBus.Error.NotContainer + error. + + + + + <literal>org.freedesktop.DBus.Containers1.StopInstance</literal> + + As a method: + + StopInstance (in OBJECT_PATH container_instance) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + OBJECT_PATH + + The opaque object path that was returned from the + AddServer 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. When all connections have + been disconnected, the instance will cease to exist. + + + If the given object path does not represent a valid container + instance (see + ), the + org.freedesktop.DBus.Error.NotContainer + error is returned. In particular, if this method is called + twice, the second call will fail in this way. + + + 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 a container instance or because its user ID does + not match the user ID of the creator of the container + instance), + the org.freedesktop.DBus.Error.AccessDenied + error is returned and nothing is stopped. + + + + + <literal>org.freedesktop.DBus.Containers1.StopListening</literal> + + As a method: + + StopListening (in OBJECT_PATH container_instance) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + OBJECT_PATH + + The opaque object path that was returned from the + AddServer 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 this method is called more than once, while the container + instance still exists because connections to it are still + open, the second and subsequent calls will be successful but + will have no practical effect. + + + If the given object path does not represent a valid container + instance (see + ), the + org.freedesktop.DBus.Error.NotContainer + error is returned. In particular, this will happen if the + container instance already stopped listening, and all + connections to it (if any) were already closed. + + + 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 a container instance or because its user ID does + not match the user ID of the creator of the container + instance), + the org.freedesktop.DBus.Error.AccessDenied + error is returned and nothing is stopped. + + + + + <literal>org.freedesktop.DBus.Containers1.GetConnectionInstance</literal> + + As a method: + + GetConnectionInstance (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 + AddServer method, identifying a + container instance. + + + + 2 + STRING + + Reversed domain name identifying a container + manager or container technology, as passed to the + AddServer method, 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.GetInstanceInfo</literal> + + As a method: + + GetInstanceInfo (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 + AddServer method, identifying a + container instance. + + + + 1 + STRING + + Reversed domain name identifying a container + manager or container technology, as passed to the + AddServer method, 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 a valid container instance, + (see ), + return information about it. Otherwise, the + org.freedesktop.DBus.Error.NotContainer error + is returned. + + + + + <literal>org.freedesktop.DBus.Containers1.InstanceRemoved</literal> + + As a signal emitted by the message bus: + + InstanceRemoved (OBJECT_PATH container_instance) + + Message arguments: + + + + + Argument + Type + Description + + + + + 0 + OBJECT_PATH + + The opaque object path that was returned from the + AddServer method, identifying a + container instance. + + + + + + + + + Emitted when a container instance ceases to exist. A container + instance continues to exist as long as it is listening for + new connections, or as long as connections to the instance + are open, whichever is longer. + + + <literal>org.freedesktop.DBus.Monitoring.BecomeMonitor</literal> -- cgit v1.2.3