mirror of https://github.com/pikvm/pikvm.git
update
This commit is contained in:
Maxim Devaev
parent
8c962a33eb
commit
dceeebc2f9
161
docs/auth.md
161
docs/auth.md
|
|
@ -2,17 +2,34 @@
|
|||
|
||||
!!! warning "PiKVM comes with the following default passwords"
|
||||
|
||||
* **Linux admin** (SSH, console, etc.): user `root`, password `root`.
|
||||
* **PiKVM Web Interface** ([API](api.md), [VNC](vnc.md)...): user `admin`, password `admin`, no 2FA code.
|
||||
* **Linux OS-level admin** (SSH, console...):
|
||||
* 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`"
|
||||
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.
|
||||
**They are two separate entities with independent passwords.**
|
||||
|
||||
*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,26 +84,30 @@ 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
|
||||
with different passwords to access the Web UI, but keep in mind that they all have the same rights:
|
||||
The `admin` is a name of a default user.
|
||||
|
||||
```console
|
||||
[root@pikvm ~]# kvmd-htpasswd set <user> # Sets a new user with password
|
||||
[root@pikvm ~]# kvmd-htpasswd list # Show the list of users
|
||||
[root@pikvm ~]# kvmd-htpasswd del <user> # Removes/deletes a user
|
||||
```
|
||||
??? example "Step by step: Add KVM users"
|
||||
|
||||
At the moment there is no way to create any ACL for different 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
|
||||
[root@pikvm ~]# kvmd-htpasswd list # Show the list of users
|
||||
[root@pikvm ~]# kvmd-htpasswd del <user> # Removes/deletes a user
|
||||
```
|
||||
|
||||
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,32 +151,95 @@ To disable 2FA and remove the secret, use command `kvmd-totp del`.
|
|||
|
||||
|
||||
----
|
||||
## Disable authentication
|
||||
If necessary, you can disable authentication for the Web UI.
|
||||
## Session expiration
|
||||
|
||||
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.
|
||||
|
||||
Note if you click the **Logout** button on the main page, it will log out all sessions of this user in all browsers.
|
||||
|
||||
!!! 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 on untrusted networks and optionally disable the Web Terminal so as not to open the shell access to PiKVM console.
|
||||
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.
|
||||
|
||||
1. Switch filesystem to read-write mode:
|
||||
|
||||
```
|
||||
[root@pikvm ~]# rw
|
||||
```
|
||||
??? example "Step by step: Disabling authentication"
|
||||
|
||||
2. Edit the file `/etc/kvmd/override.yaml`:
|
||||
1. Switch filesystem to read-write mode:
|
||||
|
||||
```yaml
|
||||
kvmd:
|
||||
auth:
|
||||
enabled: false
|
||||
```
|
||||
```console
|
||||
[root@pikvm ~]# rw
|
||||
```
|
||||
|
||||
3. Restart `kvmd`, optionally disable web terminal switch filesystem to read-only mode:
|
||||
2. Edit the file `/etc/kvmd/override.yaml`:
|
||||
|
||||
```
|
||||
[root@pikvm ~]# systemctl restart kvmd
|
||||
[root@pikvm ~]# systemctl disable --now kvmd-webterm # Optional if you have SSH access
|
||||
[root@pikvm ~]# ro
|
||||
```
|
||||
```yaml
|
||||
kvmd:
|
||||
auth:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
|
|
|||
128
docs/ipmi.md
128
docs/ipmi.md
|
|
@ -1,103 +1,97 @@
|
|||
# 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).
|
||||
|
||||
!!! 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).
|
||||
|
||||
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 an [old protocol](https://en.wikipedia.org/wiki/Intelligent_Platform_Management_Interface) for remote server management.
|
||||
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.
|
||||
|
||||
!!! 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).
|
||||
??? example "Step by step: Enabling IPMI server on PiKVM"
|
||||
|
||||
To enable IPMI BMC follow these steps:
|
||||
1. Switch the filesystem to the RW-mode:
|
||||
|
||||
1. Switch the filesystem to the RW-mode:
|
||||
```console
|
||||
[root@pikvm ~]# rw
|
||||
```
|
||||
|
||||
```
|
||||
# rw
|
||||
```
|
||||
2. Set up IPMI account in file `/etc/kvmd/ipmipasswd` (see the comment inside it).
|
||||
|
||||
2. Setup IPMI account in file `/etc/kvmd/ipmipasswd`.
|
||||
3. Enable the `kvmd-ipmi` daemon:
|
||||
|
||||
3. Enable `kvmd-ipmi` daemon:
|
||||
```console
|
||||
[root@pikvm ~]# systemctl enable --now kvmd-ipmi
|
||||
```
|
||||
|
||||
```
|
||||
# systemctl enable --now kvmd-ipmi
|
||||
```
|
||||
4. Switch the filesystem back to the RO:
|
||||
|
||||
4. Switch the filesystem back to the RO:
|
||||
```console
|
||||
[root@pikvm ~]# ro
|
||||
```
|
||||
|
||||
```
|
||||
# ro
|
||||
```
|
||||
5. Try some commands on the client PC:
|
||||
|
||||
5. Here some examples (on the remote PC):
|
||||
|
||||
```
|
||||
$ ipmitool -I lanplus -U admin -P admin -H pikvm power status
|
||||
$ ipmitool -I lanplus -U admin -P admin -H pikvm power on
|
||||
```
|
||||
```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
|
||||
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.
|
||||
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.
|
||||
|
||||
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"
|
||||
|
||||
```yaml
|
||||
ipmi:
|
||||
sol:
|
||||
device: /dev/ttyUSB0 # Path of your USB-COM adapter
|
||||
speed: 115200
|
||||
```
|
||||
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`:
|
||||
|
||||
After enabling `kvmd-ipmi`, all requests that it receives over the network regarding the COM port will be forwarded to your server. For example:
|
||||
```yaml
|
||||
ipmi:
|
||||
sol:
|
||||
device: /dev/ttyUSB0 # Path of your USB-COM adapter
|
||||
speed: 115200
|
||||
```
|
||||
|
||||
```
|
||||
$ ipmitool -I lanplus -U admin -P admin -H pikvm sol activate
|
||||
```
|
||||
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:
|
||||
|
||||
```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.
|
||||
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:
|
||||
PiKVM supports the Redfish natively and provides a power management handles with it.
|
||||
|
||||
```nginx
|
||||
location /redfish {
|
||||
proxy_pass http://kvmd;
|
||||
include /etc/kvmd/nginx/loc-proxy.conf;
|
||||
auth_request off;
|
||||
}
|
||||
```
|
||||
|
||||
!!! 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
|
||||
To access the Redfish API, use HTTP Basic Auth methods. Also you can use the [redfishtool](https://github.com/DMTF/Redfishtool):
|
||||
|
||||
```console
|
||||
[root@pikvm ~]$ redfishtool -S Never -r pikvm root
|
||||
[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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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":
|
||||
|
|
|
|||
Loading…
Reference in New Issue