user-management: migrate to new clicmd syntax

1 files changed, 104 insertions, 72 deletions

diff --git a/docs/system/user-management.rst b/docs/system/user-management.rst
index 5c5e46f2..b2dd3d08 100644
--- a/docs/system/user-management.rst
+++ b/docs/system/user-management.rst
@@ -9,121 +9,153 @@ have all capabilities to configure the system. All accounts have sudo
 capabilities and therefore can operate as root on the system. Setting the level
 to `admin` is optional, all accounts on the system will have admin privileges.
 
-Both local administered and remote administered RADIUS (Remote Authentication
-Dial-In User Service) accounts are supported.
+Both local administered and remote administered :abbr:`RADIUS (Remote
+Authentication Dial-In User Service)` accounts are supported.
 
 Local
 =====
 
-Create user account `jsmith` and the password `mypassword`.
+.. cfgcmd:: set system login user '<name>' full-name "<string>"
 
-.. code-block:: none
+   Create new system user with username `<name>` and real-name specified by
+   `<string>`.
 
-  set system login user jsmith full-name "Johan Smith"
-  set system login user jsmith authentication plaintext-password mypassword
+.. cfgcmd:: set system login user '<name>' authentication plaintext-password '<password>'
 
-The command:
+   Specify the plaintext password user by user `<name>` on this system. The
+   plaintext password will be automatically transferred into a secure hashed
+   password and not saved anywhere in plaintext.
 
-.. code-block:: none
+.. cfgcmd:: set system login user '<name>' authentication encrypted-password '<password>'
 
-  show system login
+   Setup encrypted password for given username. This is usefull for
+   transferring a hashed password from system to system.
 
-will show the contents of :code:`system login` configuration node:
+.. cfgcmd:: set system login user '<name>' group '<group>'
 
-.. code-block:: none
+   Specify additional group membership for given username `<name>`.
 
-  user jsmith {
-      authentication {
-          encrypted-password $6$0OQH[...]vViOFPBoFxIi.iqjqrvsQdQ./cfiiPT.
-          plaintext-password ""
-      }
-      full-name "Johan Smith"
-      level admin
-  }
+.. _ssh_key_based_authentication:
 
-SSH with Public Keys
---------------------
+Key Based Authentication
+------------------------
 
-The following command will load the public key `dev.pub` for user `jsmith`
+It is highly recommended to use SSH key authentication. By default there is
+only one user (``vyos``), and you can assign any number of keys to that user.
+You can generate a ssh key with the ``ssh-keygen`` command on your local
+machine, which will (by default) save it as ``~/.ssh/id_rsa.pub``.
 
-.. code-block:: none
+Every SSH key comes in three parts:
 
-  loadkey jsmith dev.pub
+``ssh-rsa AAAAB3NzaC1yc2EAAAABAA...VBD5lKwEWB username@host.example.com``
 
-.. note:: This requires uploading the `dev.pub` public key to the VyOS router
-   first. As an alternative you can also load the SSH public key directly
-   from a remote system:
+Only the type (``ssh-rsa``) and the key (``AAAB3N...``) are used. Note that the
+key will usually be several hundred characters long, and you will need to copy
+and paste it. Some terminal emulators may accidentally split this over several
+lines. Be attentive when you paste it that it only pastes as a single line.
+The third part is simply an identifier, and is for your own reference.
 
-.. code-block:: none
+.. cfgcmd:: set system login user '<username>' authentication public-keys '<identifier>' key '<key>'
+
+   Assign the SSH public key portion `<key>` identified by per-key
+   `<identifier>` to the local user `<username>`.
+
+.. cfgcmd:: set system login user '<username>' authentication public-keys '<identifier>' type '<type>'
+
+   Every SSH public key portion referenced by `<identifier>` requires the
+   configuration of the `<type>` of public-key used. This type can be any of:
+
+   * ``ecdsa-sha2-nistp256``
+   * ``ecdsa-sha2-nistp384``
+   * ``ecdsa-sha2-nistp521``
+   * ``ssh-dss``
+   * ``ssh-ed25519``
+   * ``ssh-rsa``
+
+   .. note:: You can assign multiple keys to the same user by using a unique
+      identifier per SSH key.
+
+.. cfgcmd:: loadkey '<username>' '<location>'
 
-  loadkey jsmith scp://devuser@dev001.vyos.net/home/devuser/.ssh/dev.pub
+   SSH keys can not only be specified on the command-line but also loaded for
+   a given user with `<username>` from a file pointed to by `<location>.` Keys
+   can be either loaded from local filesystem or any given remote location
+   using one of the following :abbr:`URIs (Uniform Resource Identifier)`:
 
-In addition SSH public keys can be fully added using the CLI. Each key can be
-given a unique identifier, `calypso` is used oin the example below to id an SSH
-key.
+   * ``<file>`` - Load from file on local filesystem path
+   * ``scp://<user>@<host>/<file>`` - Load via SCP from remote machine
+   * ``sftp://<user>@<host>/<file>`` - Load via SFTP from remote machine
+   * ``ftp://<user>@<host>/<file>`` - Load via FTP from remote machine
+   * ``http://<host>/<file>`` - Load via HTTP from remote machine
+   * ``tftp://<host>/<file>`` - Load via TFTP from remote machine
+
+Example
+-------
+
+In the following example, both `User1` and `User2` will be able to SSH into
+VyOS as user ``vyos`` using their very own keys.
 
 .. code-block:: none
 
-  set system login user jsmith authentication public-keys callisto key 'AAAABo..Q=='
-  set system login user jsmith authentication public-keys callisto type 'ssh-rsa'
+  set system login user vyos authentication public-keys 'User1' key "AAAAB3Nz...KwEW"
+  set system login user vyos authentication public-keys 'User1' type ssh-rsa
+  set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3"
+  set system login user vyos authentication public-keys 'User2' type ssh-rsa
+
 
 RADIUS
 ======
 
-VyOS supports using one or more RADIUS servers as backend for user authentication.
+In large deployments it is not reasonable to configure each user individually
+on every system. VyOS supports using :abbr:`RADIUS (Remote Authentication
+Dial-In User Service)` servers as backend for user authentication.
 
-The following command sets up two servers for RADIUS authentication, one with a
-discrete timeout of `5` seconds and a discrete port of `1812` and the other using
-a default timeout and port.
+Configuration
+-------------
 
-.. code-block:: none
+.. cfgcmd:: set system login radius server '<address>' secret '<secret>'
 
-  set system login radius server 192.168.1.2 secret 's3cr3t0815'
-  set system login radius server 192.168.1.2 timeout '5'
-  set system login radius server 192.168.1.2 port '1812'
-  set system login radius server 192.168.1.3 secret 's3cr3t0816'
+   Specify the `<address>` of the RADIUS server user with the pre-shared-secret
+   given in `<secret>`. Multiple servers can be specified.
 
-This configuration results in:
+.. cfgcmd:: set system login radius server '<address>' port '<port>'
 
-.. code-block:: none
+   Configure the discrete port under which the RADIUS server can be reached.
+   This defaults to 1812.
+
+.. cfgcmd:: set system login radius server '<address>' timeout '<timeout>'
 
-  show system login
-   radius {
-       server 192.168.1.2 {
-           secret s3cr3t0815
-           timeout 5
-           port 1812
-       }
-       server 192.168.1.3 {
-           secret s3cr3t0816
-       }
-   }
-
-.. note:: If you wan't to have admin users to authenticate via RADIUS it is
+   Setup the `<timeout>` in seconds when querying the RADIUS server.
+
+.. hint:: If you wan't to have admin users to authenticate via RADIUS it is
    essential to sent the ``Cisco-AV-Pair shell:priv-lvl=15`` attribute. Without
    the attribute you will only get regular, non privilegued, system users.
 
-Source Address
---------------
 
-RADIUS servers could be hardened by only allowing certain IP addresses to connect.
-As of this the source address of each RADIUS query can be configured. If this is
-not set incoming connections to the RADIUS server will use the nearest interface
-address pointing towards the RADIUS server - making it error prone on e.g. OSPF
-networks when a link fails.
+.. cfgcmd:: set system login radius source-address '<address>'
 
-.. code-block:: none
+   RADIUS servers could be hardened by only allowing certain IP addresses to
+   connect. As of this the source address of each RADIUS query can be
+   configured. If this is not set, incoming connections to the RADIUS server
+   will use the nearest interface address pointing towards the server - making
+   it error prone on e.g. OSPF networks when a link fails and a backup route is
+   taken.
 
-  set system login radius source-address 192.168.1.254
 
 Login Banner
 ============
 
-You are able to set post-login or pre-login messages with the following lines:
+You are able to set post-login or pre-login banner messages to display certain
+information for this system.
 
-.. code-block:: none
+.. cfgcmd:: set system login banner pre-login '<message>'
+
+   Configure `<message>` which is shown during SSH connect and before a user is
+   logged in.
+
+.. cfgcmd:: set system login banner post-login '<message>'
 
-  set system login banner pre-login "UNAUTHORIZED USE OF THIS SYSTEM IS PROHIBITED\n"
-  set system login banner post-login "Welcome to VyOS"
+   Configure `<message>` which is shown after user has logged in to the system.
 
-**\\n** create a newline.
+.. note:: To create a new line in your login message you need to escape the new
+   line character by using ``\\n``.