github/dokku
0
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Clarify user management docs

Browse Source 
- 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]
This commit is contained in:
Jose Diaz-Gonzalez
2016-07-30 16:49:17 -04:00
parent cc05a64fbe
commit 926a752e31
1 changed files with 29 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
docs/deployment/user-management.md
View File

@@ -1,44 +1,47 @@
# User Management
> New as of 0.7.0
```
ssh-keys:add <name> [/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 <name> # 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 <name> [/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 <name> 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 <NAME> <PATH/TO/KEY>
dokku ssh-keys:add KEY_NAME path/to/id_rsa.pub
```
Admin users and root can also add keys remotely:
```shell
cat <PATH/TO/KEY> | ssh dokku@dokku.me ssh-keys:add <NAME>
`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.