From 926a752e3124ed1815d5a32f5c36e4614b83a745 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sat, 30 Jul 2016 16:49:17 -0400 Subject: [PATCH] Clarify user management docs - Add missing "New as of" banner - Ensure we list commands at the top - Add reference to sshcommand - Callout that the NAME must be unique - Add an example for removing keys [ci skip] --- docs/deployment/user-management.md | 55 ++++++++++++++++-------------- 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/docs/deployment/user-management.md b/docs/deployment/user-management.md index d600f45ee..2984cef61 100644 --- a/docs/deployment/user-management.md +++ b/docs/deployment/user-management.md @@ -1,44 +1,47 @@ # User Management +> New as of 0.7.0 + +``` +ssh-keys:add [/path/to/key] # Add a new public key by pipe or path +ssh-keys:list # List of all authorized Dokku public ssh keys +ssh-keys # Manage public ssh keys that are allowed to connect to Dokku +ssh-keys:remove # Remove SSH public key by name +``` + When pushing to Dokku, ssh key based authorization is the preferred authentication method, for ease of use and increased security. Users in Dokku are managed via the `~/dokku/.ssh/authorized_keys` file. It is **highly** recommended that you follow the steps below to manage users on a Dokku server. -## Dokku ssh-keys command - -The `dokku ssh-keys` command(s) allow you to manage ssh keys used to push to the Dokku server. The following is the usage output for `dokku ssh-keys`: - -``` -$ dokku ssh-keys:help -Usage: dokku ssh-keys[:COMMAND] - -Manage public ssh keys that are allowed to connect to Dokku - -Additional commands: - ssh-keys:add [/path/to/key] Add a new public key by pipe or path - ssh-keys:list List of all authorized Dokku public ssh keys - ssh-keys Manage public ssh keys that are allowed to connect to Dokku - ssh-keys:remove Remove SSH public key by name -``` - -Keys are given unique names, which can be used in conjunction with the [user-auth](/dokku/development/plugin-triggers/#user-auth) plugin trigger to handle command authorization. In Dokku's case, the unique _name_ is just for ease of identifying the keys, the ssh (git) user is *always* `dokku`, as this is the system user that the `dokku` binary uses to perform all it's actions. +> Users of older versions of Dokku should use the `sshcommand` binary to manage keys. Please refer to the Dokku documentation for your version for more details. ## Adding deploy users You can add your public key to Dokku with the following command: -`NAME` is the username prefer to use to refer to this particular key. Including the word `admin` in the name will grant the user privileges to add additional keys remotely. - ```shell -$ dokku ssh-keys:add +dokku ssh-keys:add KEY_NAME path/to/id_rsa.pub ``` -Admin users and root can also add keys remotely: -```shell -cat | ssh dokku@dokku.me ssh-keys:add +`KEY_NAME` is the username prefer to use to refer to this particular key. Including the word `admin` in the name will grant the user privileges to add additional keys remotely. + +Key names are unique, and attempting to re-use a name will result in an error. + +> The unique `KEY_NAME` is for ease of identifying the keys. The ssh (git) user is *always* `dokku`, as this is the system user that the `dokku` binary uses to perform all it's actions. + +As key names are unique, they can be used to remove a public ssh key: + +```SHELL +dokku ssh-keys:remove KEY_NAME ``` -If you are using the vagrant installation, you can also use the `make vagrant-acl-add` target to add your public key to dokku (it will use your host username as the `USER`): +Admin users and root can also add keys remotely: + +```shell +cat ~/.ssh/id_rsa.pub | ssh dokku@dokku.me ssh-keys:add KEY_NAME +``` + +Finally, if you are using the vagrant installation, you can also use the `make vagrant-acl-add` target to add your public key to Dokku (it will use your host username as the `USER`): ```shell cat ~/.ssh/id_rsa.pub | make vagrant-acl-add @@ -46,4 +49,4 @@ cat ~/.ssh/id_rsa.pub | make vagrant-acl-add ## Scoping commands to specific users -See the [user auth plugin trigger documentation](/dokku/development/plugin-triggers/#user-auth). +Keys are given unique names, which can be used in conjunction with the [user-auth](/dokku/development/plugin-triggers/#user-auth) plugin trigger to handle command authorization. Please see the documentation on that trigger for more information.