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>