From 494cccf26b13aad4ca98e799c1f620dd9c445842 Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Sun, 20 Aug 2023 07:04:07 +0300 Subject: [PATCH] update --- docs/auth.md | 96 ++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 67 insertions(+), 29 deletions(-) diff --git a/docs/auth.md b/docs/auth.md index d45ffff9..1c522556 100644 --- a/docs/auth.md +++ b/docs/auth.md @@ -1,74 +1,112 @@ # Authentication -PiKVM comes with the following default passwords: +PiKVM OS is based on a regular Linux system, so everything about authorization in this OS is also true for PiKVM. +It comes with the following default passwords: * **Linux admin** (SSH, console, etc.): user `root`, password `root`. * **PiKVM Web Interface, API, VNC...**: user `admin`, password `admin`, no 2FA code. **These are two separate entities with independent accounts.** -To change passwords, you will need to use the terminal access via SSH or Web Terminal. -If you are using the Web Terminal, use the `su -` command to get root access (enter the root user password). + +Also there is another Linux special user: `kvmd-webterm`. +It can't be used for login or remote access to PiKVM OS and has the non-privileged rights in the OS. +Password access and `sudo` is disabled for it. It is used to launch the `Web Terminal` in the Web UI. + +The basic idea is that the Web UI user can access the OS at the level of a regular user, +but cannot control the core functions of PiKVM or break the OS. +----- +## Root access in the Web Terminal + +As mentioned above, the `Web Terminal` runs under user `kvmd-webterm` with disabled `sudo` and password access. +However, most PiKVM administration commands require the `root` access. + +To change the user to root in the `Web Terminal`, type `su -` and then enter the `root` password: + +``` +[kvmd-webterm@pikvm ~]$ su - +... +[root@pikvm kvmd-webterm]# +``` + + +----- ## Changing the Linux password ``` -# rw -# passwd root -# ro +[root@pikvm ~]# rw +[root@pikvm ~]# passwd root +[root@pikvm ~]# ro ``` + +----- ## Changing the KVM password ``` -# rw -# kvmd-htpasswd set admin -# ro +[root@pikvm ~]# rw +[root@pikvm ~]# kvmd-htpasswd set admin +[root@pikvm ~]# ro ``` -Please note that admin is the default user. It is possible to create several different users +Please note that `admin` is a name of a default user. It is possible to create several different users with different passwords to access the Web UI, but keep in mind that they all have the same rights: ``` # kvmd-htpasswd set # Sets a new user with password +# # kvmd-htpasswd del # Removes/deletes a user ``` - +----- ## Two-factor authentication This is a new method of strengthening the protection of PiKVM, available since `KVM >= 3.196`. It is strongly recommended to enable it if you expose the PiKVM in the big and scary Internet. !!! warning - Using 2FA eliminates the possibility of using [IPMI](ipmi) and [VNC with vncauth](vnc) (not used by default). - It also slightly affects the use of API and regular VNC with user/password, read below. + Using 2FA eliminates the possibility of using [IPMI](ipmi) and [VNC with vncauth](vnc) (both disabled by default). + It also slightly affects the use of [API](api.md) and regular VNC with user/password, read below. -Steb-by step to enable 2FA: + Please note that 2FA does not concern the Linux OS access for the `root` user, so take care of a strong password + for it for SSH access (or setup the [key access](https://www.digitalocean.com/community/tutorials/how-to-configure-ssh-key-based-authentication-on-a-linux-server)). -1. Update OS: `rw && pacman -Syu && reboot`. +??? example "Step by step: Enabling 2FA on PiKVM" -2. **Make sure that NTP is running otherwise you will not be able to access** (`timedatectl` command). The timezone doesn't matter. + 1. Update OS and reboot: -3. Install **Google Authenticator** app to your phone ([iOS](https://apps.apple.com/us/app/google-authenticator/id388497605), [Android](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2)). It will generate one-time access codes. + ``` + [root@pikvm ~]# rw + [root@pikvm ~]# pacman -Syu + [root@pikvm ~]# reboot + ``` -4. Create a secret for one-time codes on PiKVM: - ``` - rw - kvmd-totp init - ro - ``` + 2. **Make sure that NTP is running otherwise you will not be able to access** (`timedatectl` command). + The timezone doesn't matter. -5. Run **Google Authenticator** and scan the QR code. + 3. Install the `Google Authenticator` app to your mobile device + ([iOS](https://apps.apple.com/us/app/google-authenticator/id388497605), + [Android](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2)). It will generate one-time access codes. -6. Now, on the PiKVM login page, you will need to add 6 digits to the **2FA code** field. + 4. Create a secret for one-time codes on PiKVM: + ``` + [root@pikvm ~]# rw + [root@pikvm ~]# kvmd-totp init + [root@pikvm ~]# ro + ``` -Now all Web UI users will be required to enter a one-time password. In other words, the secret is the same for all users. + 5. Run the `Google Authenticator` and scan the QR code. + + 6. Now, on the PiKVM login page, you will need to add 6 digits to the `2FA code` field. + +All Web UI users will be required to enter a one-time password on login. +In other words, **the secret is the same for all users**. !!! note - With 2FA for API or VNC authentication, you will need to add the one-time code to the password without spaces. + With 2FA for API or VNC authentication, you will need to append the one-time code to the password without spaces. That is, if the password is `foobar` and the code is `123456`, then you need to use `foobar123456` as the password. -To view the current QR code of the secret use `kvmd-totp show`. +To view the current QR code of the secret use command `kvmd-totp show`. -To disable 2FA, use `kvmd-totp del`. +To disable 2FA and remove the secret, use command `kvmd-totp del`.