update

docs/auth.md

@@ -2,17 +2,34 @@
 
 !!! warning "PiKVM comes with the following default passwords"
 
-    * **Linux admin** (SSH, console, etc.): user `root`, password `root`.
+    * **Linux OS-level admin** (SSH, console...):
-    * **PiKVM Web Interface** ([API](api.md), [VNC](vnc.md)...): user `admin`, password `admin`, no 2FA code.
+        * Username: `root`
+        * Password: `root`
 
-    **These are two separate entities with independent accounts.**
+    * **KVM user** (Web Interface, [API](api.md), [VNC](vnc.md)...):
+        * Username: `admin`
+        * Password: `admin`
+        * No 2FA code
 
-!!! note "There is another special Linux user: `kvmd-webterm`"
+    **They are two separate entities with independent passwords.**
-    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 only for launching the Web Terminal.
-    These restrictions are set for security reasons.
 
-*Changing the [VNCAuth passkey](vnc.md) and [IPMI password](ipmi.md) described in the relevant documents*.
+!!! danger "Don't forget to change BOTH passwords on the new device"
+
+    This page describes how to do this and enable two-factor authentication.
+
+    The 2FA is also strongly recommended if you plan to expose PiKVM to the internet
+    or use it in untrusted networks.
+
+In addition to the KVM user and Linux root, there are some other auth entities:
+
+* **The OS user `kvmd-webterm`**<br>
+    This is a special user with non-privileged rights in PiKVM OS.
+    It can't be used for login or remote access via SSH. Password access and `sudo` are also disabled.
+    It is used only for the Web Terminal. These restrictions are set for security reasons.
+
+* [**VNCAuth key**](vnc.md) - disabled by default.<br>
+
+* [**IPMI password**](ipmi.md) - disabled by default.<br>
 
 
 -----
@@ -39,7 +56,7 @@ To obtain it in the Web Terminal, type `su -` and then enter the `root` user pas
     [root@pikvm ~]# ro
     ```
 
-    For your own access to PiKVM OS, you will still have SSH.
+    For your own access to PiKVM OS, you still have SSH.
 
 
 -----
@@ -67,8 +84,12 @@ are stored encrypted in the `/etc/kvmd/htpasswd` file. To manage them, there is
 [root@pikvm ~]# ro
 ```
 
-Please note that `admin` is a name of a default user. It is possible to create several different users
+The `admin` is a name of a default user.
-with different passwords to access the Web UI, but keep in mind that they all have the same rights:
+
+??? example "Step by step: Add KVM users"
+
+    It is possible to create several different KVM users with different passwords to access
+    the Web UI and VNC, but keep in mind that they all have the same rights:
 
     ```console
     [root@pikvm ~]# kvmd-htpasswd set <user> # Sets a new user with password
@@ -82,11 +103,11 @@ At the moment there is no way to create any ACL for different KVM users.
 -----
 ## Two-factor authentication
 
-This is a new method of strengthening the protection of PiKVM, available since `KVM >= 3.196`.
+The 2FA 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) (both disabled by default).
+    Using 2FA eliminates the possibility of using [IPMI](ipmi.md) and [VNC with vncauth](vnc.md) (both disabled by default).
     It also slightly affects the use of [API](api.md) and regular VNC with user/password, read below.
 
     Please note that 2FA does not concern the Linux OS access for the `root` user, so take care of a strong password
@@ -106,6 +127,7 @@ It is strongly recommended to enable it if you expose the PiKVM in the big and s
         [Android](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2)). It will generate one-time access codes.
 
     4. Create a secret for one-time codes on PiKVM:
+
        ```console
        [root@pikvm ~]# rw
        [root@pikvm ~]# kvmd-totp init
@@ -129,17 +151,80 @@ To disable 2FA and remove the secret, use command `kvmd-totp del`.
 
 
 ----
-## Disable authentication
+## Session expiration
-If necessary, you can disable authentication for the Web UI.
 
-!!! warning
+Since KVMD 4.53, on the PiKVM Web UI login page, you can choose the maximum duration of the authentication session:
+1 hour, 12 hours or infinite (until PiKVM is rebooted or the `kvmd` system service is restarted).
+The selected session duration is valid for this browser and this user.
+When the time is up, the auth cookie will be revoked.
+It will not affect other sessions for the same user in other browsers.
 
-    Don't do this on untrusted networks and optionally disable the Web Terminal so as not to open the shell access to PiKVM console.
+Note if you click the **Logout** button on the main page, it will log out all sessions of this user in all browsers.
-    You still can use SSH to access to the console.
+
+!!! note "Long-lived connections"
+
+    PiKVM actively uses websockets and long-lived HTTP connections for video streaming.
+
+    If the session has expired, this will cause its authorization cookie to be revoked
+    and new connections with this auth cookie will not be able to be established.
+    However, long-lived connections will not be terminated until the user closes the browser tab.
+    The session expiration feature is primarily intended to "clean up" when the user closes
+    the browser but don't hit the Logout button.
+
+    In the future, we plan to add immediate termination of expired connections.
+
+??? example "Step by step: Set a global session expiration limit"
+
+    You can set the default expiration time to limit the user's ability to create endless sessions.
+    This will be an invisible limit valid on KVM login for Web UI (but **not for VNC**, please note that VNC sessions are always endless).
 
     1. Switch filesystem to read-write mode:
 
+        ```console
+        [root@pikvm ~]# rw
         ```
+
+    2. Edit the file `/etc/kvmd/override.yaml`:
+
+        ```yaml
+        kvmd:
+            auth:
+                expire: 21600  # 21600 seconds is 6 shours
+        ```
+
+    3. Restart the `kvmd` service and make sure that the limit is applied:
+
+        ```console
+        [root@pikvm ~]# systemctl restart kvmd
+        [root@pikvm ~]# journalctl -u kvmd -g 'Maximum user session'
+        ... INFO --- Maximum user session time is limited: 6:00:00
+        ```
+
+    4. Switch filesystem to read-only mode back:
+
+        ```console
+        [root@pikvm ~]# ro
+        ```
+
+
+----
+## Disabling authentication
+
+If necessary, you can disable authentication for KVM access (Web UI, VNC, etc. except SSH).
+
+!!! warning
+
+    Don't do this in untrusted networks, because you can give a potential attacker access to your target machine.
+
+    If you really need this, please consider to disable the Web Terminal so as not to open the shell access to PiKVM console.
+    You still can use SSH to access to the console.
+
+
+??? example "Step by step: Disabling authentication"
+
+    1. Switch filesystem to read-write mode:
+
+        ```console
         [root@pikvm ~]# rw
         ```
 
@@ -153,7 +238,7 @@ If necessary, you can disable authentication for the Web UI.
 
     3. Restart `kvmd`, optionally disable web terminal switch filesystem to read-only mode:
 
-    ```
+        ```console
         [root@pikvm ~]# systemctl restart kvmd
         [root@pikvm ~]# systemctl disable --now kvmd-webterm  # Optional if you have SSH access
         [root@pikvm ~]# ro

docs/ipmi.md

@@ -1,55 +1,68 @@
 # IPMI & Redfish
 
 !!! info
-    This page is about the server-side emulation (if you want to manage PiKVM using ipmitool or so). If you want to use the PiKVM Web UI to manage the server using IPMI (that is, as an IPMI client), see [GPIO functions with IPMI plugin](gpio.md).
+    This page is about the server-side IPMI emulation if you want to manage PiKVM using `ipmitool` or something similar.
-
+    If you want to use the PiKVM Web UI to manage the server using IPMI (that is, as an IPMI client),
-
+    see [GPIO functions with IPMI plugin](gpio.md).
-## IPMI BMC
-
-IPMI is an [old protocol](https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface) for remote server management.
-It can be useful for managing a large number of machines with PiKVM. Its advantage is that it is supported by many enterprise systems.
 
 !!! warning
-    Although PiKVM supports the IPMI protocol, we strongly recommend that you **DO NOT USE IT** outside of trusted networks due to the protocol's [insecurity](https://github.com/NitescuLucian/nliplace.com.blog.drafts). Use Redfish or [KVMD API](api.md) instead of it. Also IPMI can not work with [2FA](auth.md#two-factor-authentication).
+    Although PiKVM supports the IPMI protocol, we strongly recommend that you **DO NOT USE IT** outside of trusted networks
+    due to the protocol's [insecurity](https://github.com/NitescuLucian/nliplace.com.blog.drafts).
 
-To enable IPMI BMC follow these steps:
+    Please consider to using the Redfish or [KVMD API](api.md) instead of it.
+
+    Also, IPMI can not work with [2FA](auth.md#two-factor-authentication).
+
+
+----
+## IPMI BMC
+
+IPMI is a [legacy protocol](https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface) for remote server management.
+It can be useful for managing a large number of machines with PiKVM. Its advantage is that it is supported by many enterprise systems.
+
+??? example "Step by step: Enabling IPMI server on PiKVM"
 
     1. Switch the filesystem to the RW-mode:
 
-    ```
+        ```console
-    # rw
+        [root@pikvm ~]# rw
         ```
 
-2. Setup IPMI account in file `/etc/kvmd/ipmipasswd`.
+    2. Set up IPMI account in file `/etc/kvmd/ipmipasswd` (see the comment inside it).
 
-3. Enable `kvmd-ipmi` daemon:
+    3. Enable the `kvmd-ipmi` daemon:
 
-    ```
+        ```console
-    # systemctl enable --now kvmd-ipmi
+        [root@pikvm ~]# systemctl enable --now kvmd-ipmi
         ```
 
     4. Switch the filesystem back to the RO:
 
-    ```
+        ```console
-    # ro
+        [root@pikvm ~]# ro
         ```
 
-5. Here some examples (on the remote PC):
+    5. Try some commands on the client PC:
 
-    ```
+        ```console
         $ ipmitool -I lanplus -U admin -P admin -H pikvm power status
         $ ipmitool -I lanplus -U admin -P admin -H pikvm power on
         ```
 
 
+----
 ## IPMI SoL
 
-IPMI supports the ability to get console access to the server using Serial-over-LAN. PiKVM can act as a proxy for your server's COM port.
+IPMI supports the ability to get console access to the server using Serial-over-LAN.
+With this feature PiKVM will act as a proxy for your server's COM port.
 
-!!! warning
+To use this feature, you will need a USB-COM adapter that you need to connect to the PiKVM.
-    Although PiKVM supports the IPMI protocol, we strongly recommend that you **DO NOT USE IT** outside of trusted networks due to the protocol's [insecurity](https://github.com/NitescuLucian/nliplace.com.blog.drafts). Use Redfish or [KVMD API](api.md) instead of it.
+The COM port of the adapter need to be connected to the server.
 
-To use this feature, you will need a USB-COM adapter that you need to connect to the PiKVM. The COM port of the adapter need to be connected to the server. As with IPMI BMC, you need to configure `kvmd-vnc` and add the following configuration to `/etc/kvmd/override.yaml`:
+??? example "Step by step: Enabling IPMI SoL for USB-COM adapter"
+
+    As with IPMI BMC, you need to configure `kvmd-ipmi` server (see the previous chapter about IPMI BMC)
+    and add the following configuration to `/etc/kvmd/override.yaml`:
 
     ```yaml
     ipmi:
@@ -58,46 +71,27 @@ ipmi:
             speed: 115200
     ```
 
-After enabling `kvmd-ipmi`, all requests that it receives over the network regarding the COM port will be forwarded to your server. For example:
+    Then restart the `kvmd-ipmi` server: `systemctl restart kvmd-ipmi`.
 
-```
+    All requests that it receives over the network regarding the COM port will be forwarded to your server. For example:
-$ ipmitool -I lanplus -U admin -P admin -H pikvm sol activate
+
+    ```console
+    [root@pikvm ~]$ ipmitool -I lanplus -U admin -P admin -H pikvm sol activate
     ```
 
 
+----
 ## Redfish
 
 [Redfish](https://www.dmtf.org/standards/redfish) is a more modern server management protocol designed to replace IPMI.
 It is based on HTTP and fixes many security issues. If possible, we recommend using it instead of IPMI, or using the [KVMD API](api.md).
 
-There're not special actions required to use Redfish. In addition, Redfish will use regular PiKVM credentials.
+PiKVM supports the Redfish natively and provides a power management handles with it.
-But for systems that have been upgraded to KVMD 2.0 (not a clean image installation), you will probably need to edit
-the `/etc/kvmd/nginx/kvmd.ctx-server.conf` file to add these lines at the end:
 
-```nginx
+To access the Redfish API, use HTTP Basic Auth methods. Also you can use the [redfishtool](https://github.com/DMTF/Redfishtool):
-location /redfish {
+
-      proxy_pass http://kvmd;
+```console
-      include /etc/kvmd/nginx/loc-proxy.conf;
+[root@pikvm ~]$ redfishtool -S Never -r pikvm root
-      auth_request off;
+[root@pikvm ~]$ redfishtool -S Never -u admin -p admin -r pikvm Systems
-}
+[root@pikvm ~]$ redfishtool -S Never -u admin -p admin -r pikvm Systems reset ForceOff
-```
-
-!!! info 
-    Don't be confused by the parameter `auth_request off`. KVMD performs authorization on its own. The only open HTTP entrypoint is `/redfish/v1`, which returns a static document and does not change the state of the PiKVM. It's safe.
-
-If there is a file in your system after the update `/etc/kvmd/nginx/kvmd.ctx-server.conf.pacnew` you can just move it:
-
-```
-# mv /etc/kvmd/nginx/kvmd.ctx-server.conf.pacnew /etc/kvmd/nginx/kvmd.ctx-server.conf
-```
-
-!!! warning
-    Be careful not to lose your local changes if you have done anything with this file before.
-
-To access the Redfish API, use HTTP Basic Auth. Also you can use the [redfishtool](https://github.com/DMTF/Redfishtool):
-
-```
-$ redfishtool -S Never -r pikvm root
-$ redfishtool -S Never -u admin -p admin -r pikvm Systems
-$ redfishtool -S Never -u admin -p admin -r pikvm Systems reset ForceOff
 ```

mkdocs.yml

@@ -76,7 +76,7 @@ nav:
     - "Getting started":
         - "First steps": first_steps.md
         - "Web UI Overview": webui.md
-        - "Authentication": auth.md
+        - "Authentication & 2FA": auth.md
         - "FAQ & Troubleshooting": faq.md
         - "Flashing OS": flashing_os.md
     - "Networking":