From b20a425cd9d666463aaf163cdd8a471eb42ee5ed Mon Sep 17 00:00:00 2001
From: Antonio Murdaca <runcom@redhat.com>
Date: Tue, 8 Mar 2016 22:34:35 +0100
Subject: [PATCH] docs: extend: plugins: mention the sdk + systemd socket
 activation

Signed-off-by: Antonio Murdaca <runcom@redhat.com>
---
 docs/extend/index.md                          |  2 +-
 docs/extend/plugin_api.md                     | 44 ++++++++++++++++++-
 ...horization.md => plugins_authorization.md} |  1 +
 docs/reference/commandline/daemon.md          |  2 +-
 man/docker-daemon.8.md                        |  2 +-
 5 files changed, 47 insertions(+), 4 deletions(-)
 rename docs/extend/{authorization.md => plugins_authorization.md} (99%)

diff --git a/docs/extend/index.md b/docs/extend/index.md
index f491926e9a..8a061e4e29 100644
--- a/docs/extend/index.md
+++ b/docs/extend/index.md
@@ -18,5 +18,5 @@ Currently, you can extend Docker Engine by adding a plugin. This section contain
 * [Understand Docker plugins](plugins.md)
 * [Write a volume plugin](plugins_volume.md)
 * [Write a network plugin](plugins_network.md)
-* [Write an authorization plugin](authorization.md)
+* [Write an authorization plugin](plugins_authorization.md)
 * [Docker plugin API](plugin_api.md)
diff --git a/docs/extend/plugin_api.md b/docs/extend/plugin_api.md
index e0a91411f3..1a4237e2c7 100644
--- a/docs/extend/plugin_api.md
+++ b/docs/extend/plugin_api.md
@@ -96,6 +96,43 @@ directory and activates it with a handshake. See Handshake API below.
 Plugins are *not* activated automatically at Docker daemon startup. Rather,
 they are activated only lazily, or on-demand, when they are needed.
 
+## Systemd socket activation
+
+Plugins may also be socket activated by `systemd`. The official [Plugins helpers](https://github.com/docker/go-plugins-helpers)
+natively supports socket activation. In order for a plugin to be socket activated it needs
+a `service` file and a `socket` file.
+
+The `service` file (for example `/lib/systemd/system/your-plugin.service`):
+
+```
+[Unit]
+Description=Your plugin
+Before=docker.service
+After=network.target your-plugin.socket
+Requires=your-plugin.socket docker.service
+
+[Service]
+ExecStart=/usr/lib/docker/your-plugin
+
+[Install]
+WantedBy=multi-user.target
+```
+The `socket` file (for example `/lib/systemd/system/your-plugin.socket`):
+```
+[Unit]
+Description=Your plugin
+
+[Socket]
+ListenStream=/run/docker/plugins/your-plugin.sock
+
+[Install]
+WantedBy=sockets.target
+```
+
+This will allow plugins to be actually started when the Docker daemon connects to
+the sockets they're listening on (for instance the first time the daemon uses them
+or if one of the plugin goes down accidentally).
+
 ## API design
 
 The Plugin API is RPC-style JSON over HTTP, much like webhooks.
@@ -128,7 +165,7 @@ Responds with a list of Docker subsystems which this plugin implements.
 After activation, the plugin will then be sent events from this subsystem.
 
 Possible values are:
- - [`authz`](authorization.md)
+ - [`authz`](plugins_authorization.md)
  - [`NetworkDriver`](plugins_network.md)
  - [`VolumeDriver`](plugins_volume.md)
 
@@ -139,3 +176,8 @@ Attempts to call a method on a plugin are retried with an exponential backoff
 for up to 30 seconds. This may help when packaging plugins as containers, since
 it gives plugin containers a chance to start up before failing any user
 containers which depend on them.
+
+## Plugins helpers
+
+To ease plugins development, we're providing an `sdk` for each kind of plugins
+currently supported by Docker at [docker/go-plugins-helpers](https://github.com/docker/go-plugins-helpers).
diff --git a/docs/extend/authorization.md b/docs/extend/plugins_authorization.md
similarity index 99%
rename from docs/extend/authorization.md
rename to docs/extend/plugins_authorization.md
index 3512c56ccd..7db31b85c4 100644
--- a/docs/extend/authorization.md
+++ b/docs/extend/plugins_authorization.md
@@ -3,6 +3,7 @@
 title = "Access authorization plugin"
 description = "How to create authorization plugins to manage access control to your Docker daemon."
 keywords = ["security, authorization, authentication, docker, documentation, plugin, extend"]
+aliases = ["/engine/extend/authorization/"]
 [menu.main]
 parent = "engine_extend"
 weight = -1
diff --git a/docs/reference/commandline/daemon.md b/docs/reference/commandline/daemon.md
index ccd72c1034..aef28d576b 100644
--- a/docs/reference/commandline/daemon.md
+++ b/docs/reference/commandline/daemon.md
@@ -644,7 +644,7 @@ multiple plugins installed, at least one must allow the request for it to
 complete.
 
 For information about how to create an authorization plugin, see [authorization
-plugin](../../extend/authorization.md) section in the Docker extend section of this documentation.
+plugin](../../extend/plugins_authorization.md) section in the Docker extend section of this documentation.
 
 
 ## Daemon user namespace options
diff --git a/man/docker-daemon.8.md b/man/docker-daemon.8.md
index 9f699c7124..b3fc64dcc5 100644
--- a/man/docker-daemon.8.md
+++ b/man/docker-daemon.8.md
@@ -521,7 +521,7 @@ multiple plugins installed, at least one must allow the request for it to
 complete.
 
 For information about how to create an authorization plugin, see [authorization
-plugin](https://docs.docker.com/engine/extend/authorization.md) section in the
+plugin](https://docs.docker.com/engine/extend/plugins_authorization.md) section in the
 Docker extend section of this documentation.