Add outline of steps for configuring LDAP (#171)

* Add outline of steps for configuring LDAP

* Change title per feedback

_data/toc.yaml

@@ -1638,6 +1638,8 @@ manuals:
           title: Integrate with Docker Trusted Registry
         - path: /datacenter/ucp/2.2/guides/admin/configure/external-auth/
           title: Integrate with LDAP
+        - path: /datacenter/ucp/2.2/guides/admin/configure/external-auth/enable-ldap-config-file
+          title: Integrate with LDAP by using a configuration file
       - sectiontitle: Manage users
         section:
         - path: /datacenter/ucp/2.2/guides/admin/manage-users/

datacenter/ucp/2.2/guides/admin/configure/external-auth/enable-ldap-config-file.md

@@ -0,0 +1,64 @@
+---
+title: Integrate with LDAP by using a configuration file
+description: Set up LDAP authentication by using a configuration file.
+keywords: UCP, LDAP, config
+---
+
+Docker UCP integrates with LDAP directory services, so that you can manage
+users and groups from your organization's directory and automatically
+propagate this information to UCP and DTR. You can set up your swarm's LDAP
+configuration by using the UCP web UI, or you can use a
+[UCP configuration file](../ucp-configuration-file.md).
+
+To see an example TOML config file that shows how to configure UCP settings,
+run UCP with the `example-config` option.
+[Learn about UCP configuration files](../ucp-configuration-file.md).
+
+```bash
+$ docker container run --rm {{ page.ucp_org }}/{{ page.ucp_repo }}:{{ page.ucp_version }} example-config
+```
+
+## Set up LDAP by using a configuration file
+
+1.  Use the following command to extract the name of the currently active
+    configuration from the `ucp-agent` service.
+
+    ```bash
+    $ CURRENT_CONFIG_NAME=$(docker service inspect --format '{{ range $config := .Spec.TaskTemplate.ContainerSpec.Configs }}{{ $config.ConfigName }}{{ "\n" }}{{ end }}' ucp-agent | grep 'com.docker.ucp.config-')
+    ```
+
+2.  Get the current configuration and save it to a TOML file.
+
+    ```bash
+    $ docker config inspect --format '{{ printf "%s" .Spec.Data }}' $CURRENT_CONFIG_NAME > config.toml
+    ```
+
+3.  Use the output of the `example-config` command as a guide to edit your
+    `config.toml` file. Under the `[auth]` sections, set `backend = "ldap"`
+    and `[auth.ldap]` to configure LDAP integration the way you want.
+
+4.  Once you've finished editing your `config.toml` file, create a new Docker
+    Config object by using the following command.
+
+    ```bash
+    $ NEW_CONFIG_NAME="com.docker.ucp.config-$(( $(cut -d '-' -f 2 <<< "$CURRENT_CONFIG_NAME") + 1 ))"
+    docker config create $NEW_CONFIG_NAME config.toml
+    ```
+
+5.  Update the `ucp-agent` service to remove the reference to the old config
+    and add a reference to the new config.
+
+    ```bash
+    $ docker service update --config-rm "$CURRENT_CONFIG_NAME" --config-add "source=${NEW_CONFIG_NAME},target=/etc/ucp/ucp.toml" ucp-agent
+    ```
+
+6.  Wait a few moments for the `ucp-agent` service tasks to update across
+    your swarm. If you set `jit_user_provisioning = true` in the LDAP
+    configuration, users matching any of your specified search queries will
+    have their accounts created when they log in with their username and LDAP
+    password.
+
+## Where to go next
+
+-  [Create and manage users](../../manage-users/create-and-manage-users.md)
+-  [Create and manage teams](../../manage-users/create-and-manage-teams.md)

datacenter/ucp/2.2/guides/admin/configure/external-auth/index.md

@@ -134,3 +134,4 @@ LDAP directory.
 -  [Create and manage users](../../manage-users/create-and-manage-users.md)
 -  [Create and manage teams](../../manage-users/create-and-manage-teams.md)
 -  [UCP permission levels](../../permission-levels.md)
+-  [Enable LDAP integration by using a configuration file](enable-ldap-config-file.md)

datacenter/ucp/2.2/guides/admin/configure/ucp-configuration-file.md

@@ -1,18 +1,32 @@
 ---
 title: UCP configuration file
 description: Configure UCP deployments.
-keywords: docker enterprise edition, ucp, universal control plane, swarm, cluster configuration, deploy
+keywords: docker enterprise edition, ucp, universal control plane, swarm, configuration, deploy
 ---
 
-Override the default UCP settings by providing a configuration file when you create 
+Override the default UCP settings by providing a configuration file when you
-UCP manager nodes. This is useful for scripted installations.
+create UCP manager nodes. This is useful for scripted installations.
 
-```bash
+## UCP configuration file 
-$ docker config create --name ...  <ucp.cfg>
-```
 
-Specify your configuration settings in a TOML file. For more info, see
+The `ucp-agent` service uses a configuration file to set up UCP.
-[Tom's Obvious, Minimal Language](https://github.com/toml-lang/toml/blob/master/README.md). 
+You can use the configuration file in different ways to set up your UCP
+swarms.
+
+- Install one swarm and use the UCP web UI to configure it as desired,
+  extract the configuration file, edit it as needed, and use the edited
+  config file to make copies to multiple other swarms.
+- Install a UCP swarm, extract and edit the configuration file, and use the 
+  CLI to apply the new configuration to the same swarm.
+- Run the `example-config` command, edit the example configuration file, and
+  apply the file at install time or after installation.
+
+Specify your configuration settings in a TOML file.
+[Learn about Tom's Obvious, Minimal Language](https://github.com/toml-lang/toml/blob/master/README.md). 
+
+The configuration has a versioned naming convention, with a trailing decimal
+number that increases with each version, like `com.docker.ucp.config-1`. The
+`ucp-agent` service maps the configuration to the file at `/etc/ucp/ucp.toml`.
 
 ## Example configuration file
 
@@ -20,7 +34,23 @@ You can see an example TOML config file that shows how to configure UCP
 settings. From the command line, run UCP with the `example-config` option:
 
 ```bash
-$ docker container run --rm docker/ucp:2.2.0-latest example-config
+$ docker container run --rm {{ page.ucp_org }}/{{ page.ucp_repo }}:{{ page.ucp_version }} example-config
+```
+
+## Inspect and create configurations
+
+Use the `docker config inspect` command to view the current settings and emit
+them to a file.
+
+```bash
+$ docker config inspect --format '{{ printf "%s" .Spec.Data }}' $CURRENT_CONFIG_NAME > ucp-config.toml
+```
+
+Use the `docker config create` command to read the settings that are specified
+in a TOML file and create a new configuration.   
+
+```bash
+$ docker config create --name ...  <ucp-config.toml>
 ```
 
 ## Configuration file and web UI