diff options
| -rw-r--r-- | docs/services/ssh.rst | 50 | ||||
| -rw-r--r-- | docs/system/user-management.rst | 176 |
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``. |