summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorChristian Poessinger <christian@poessinger.com>2019-12-20 17:55:09 +0100
committerChristian Poessinger <christian@poessinger.com>2019-12-20 17:55:09 +0100
commit4872481ebca1a455339a6c1251c36b2f4938901d (patch)
tree5542e2c54dd08d023c5fd0f0a762a8859d3c59e3 /docs
parent925dc9d5e64a881825653ddd5df13e2672792947 (diff)
downloadvyos-documentation-4872481ebca1a455339a6c1251c36b2f4938901d.tar.gz
vyos-documentation-4872481ebca1a455339a6c1251c36b2f4938901d.zip
user-management: migrate to new clicmd syntax
Diffstat (limited to 'docs')
-rw-r--r--docs/services/ssh.rst50
-rw-r--r--docs/system/user-management.rst176
2 files changed, 105 insertions, 121 deletions
diff --git a/docs/services/ssh.rst b/docs/services/ssh.rst
index 9a1418d3..fde575ea 100644
--- a/docs/services/ssh.rst
+++ b/docs/services/ssh.rst
@@ -101,53 +101,5 @@ This could be used to harden security.
.. note:: VyOS 1.1 supported login as user ``root``. This has been removed due
to tighter security in VyOS 1.2.
-Key Based Authentication
-========================
+.. seealso:: SSH :ref:`ssh_key_based_authentication`
-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``.
-
-Every SSH key comes in three parts:
-
-``ssh-rsa AAAAB3NzaC1yc2EAAAABAA...VBD5lKwEWB username@host.example.com``
-
-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.
-
-.. 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.
-
-Example
--------
-
-In the following example, both User1 and User2 will be able to SSH into VyOS
-as the ``vyos`` user using their own keys.
-
-.. code-block:: none
-
- 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
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``.