From d49ffd68e9858ce02437068858e88b5b9d2bc6fc Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Thu, 1 Oct 2020 02:54:06 +0300 Subject: [PATCH 01/12] Update gpio.md --- pages/gpio.md | 1 + 1 file changed, 1 insertion(+) diff --git a/pages/gpio.md b/pages/gpio.md index 27da7150..8940875c 100644 --- a/pages/gpio.md +++ b/pages/gpio.md @@ -145,6 +145,7 @@ Some rules and customization options: - If the switch mode is disabled, only a button will be displayed. If pulse is disabled, only a switch will be shown. - To change the LED's color specify it after the channel name like `"led1|red"`. Available: `green`, `yellow` and `red`. - To change title of the button, write some its name like `"relay1|My cool relay"`. +- Buttons and switches can request confirmation on acting. To do this write its name like `"relay1|confirm|My cool relay"`. The third argument Title is required in this case. # Hardware modules From 5d6248c96e00b4402af61042be2dfec326739ae5 Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Thu, 1 Oct 2020 03:11:44 +0300 Subject: [PATCH 02/12] Update cookbook.md --- pages/cookbook.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pages/cookbook.md b/pages/cookbook.md index adadb05f..c2987104 100644 --- a/pages/cookbook.md +++ b/pages/cookbook.md @@ -28,8 +28,9 @@ 1. Edit `/etc/kvmd/override.yaml` (Remove `{}` if this your first configuration entry) and add these lines: ``` yaml otg: - acm: - enabled: true + devices: + serial: + enabled: true ``` 2. Run the following command: ``` From 2f5d5967501ca23a76695033232c6ba79f2044bd Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Thu, 1 Oct 2020 03:34:34 +0300 Subject: [PATCH 03/12] Update README.md --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 725a24db..e6750610 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ The website: [pikvm.org](https://pikvm.org). Also join to the [Discord Community * Bootable **Virtual CD-ROM** and **Flash Drive**; * USB **Keyboard** and **mouse** (with leds and the wheel), PS/2 keyboard; * **Control the server power** using ATX functions; -* Access via **Web UI** or **VNC**, ability to use **IPMI BMC** and **Wake-on-LAN** to control the server; +* Access via **Web UI** or **VNC**, ability to use **IPMI BMC**, **Redfish** and **Wake-on-LAN** to control the server; * **The ready-made OS** with read-only filesystem; * **Extensible authorization** and SSL encryption; * **Health monitoring** of the Pi; @@ -60,8 +60,8 @@ The website: [pikvm.org](https://pikvm.org). Also join to the [Discord Community By default the OS runs in read-only mode, as an embedded system should. This prevents damage to the memory card due to a sudden power outage. * **VNC server** The managed server and its BIOS can be accessed using a regular VNC client which supports JPEG compression. -* **IPMI BMC** - Use `ipmitool`, `ipmiutil` or any existing network infrastructure that supports IPMI to monitor and manage the server's power. +* **IPMI BMC and Redfish** + Use `ipmitool`, `ipmiutil` or any existing network infrastructure that supports IPMI to monitor and manage the server's power. Redfish and `redfishtool` supported too. * **Wake-on-LAN** Pi-KVM can be configured to power up a managed server using WoL. This will be available in the Web menu. * **Extensible authorization methods** @@ -314,10 +314,10 @@ Our future [v3 platform](#the-future-v3-platform-work-in-progress) will contain ip: 192.168.0.100 # port: 9 # By default ``` - -* To use IPMI BMC you need to set up an appropriate account and run the `kvmd-ipmi` daemon (`systemctl enable --now kvmd-ipmi`). Although Pi-KVM 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). Refer to the file `/etc/kvmd/ipmipasswd` to configure IPMI account. + +* [Using IPMI and Redfish](pages/ipmi.md). -* [Enabling VNC](pages/vnc.md). +* [Using VNC](pages/vnc.md). * [Using Arduino HID (for USB or PS/2) with v2 platform](pages/arduino_hid.md). From 04f7e3012ffb6904b2a2717d001a51b68364237c Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Thu, 1 Oct 2020 03:50:39 +0300 Subject: [PATCH 04/12] Update cookbook.md --- pages/cookbook.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/pages/cookbook.md b/pages/cookbook.md index c2987104..f478d7e0 100644 --- a/pages/cookbook.md +++ b/pages/cookbook.md @@ -25,7 +25,9 @@ ``` ## Enable serial console on Pi-KVM -1. Edit `/etc/kvmd/override.yaml` (Remove `{}` if this your first configuration entry) and add these lines: +This can be used for terminal access from the managed server to the pikvm, or for any other purpose that requires a serial connection. In the last case, you only need to perform step 1 and reboot. + +1. Edit `/etc/kvmd/override.yaml` (remove `{}` if this your first configuration entry) and add these lines: ``` yaml otg: devices: @@ -49,3 +51,21 @@ # reboot ``` 5. Once Pi-KVM is rebooted you will have access to a virtual serial port on the server that the USB is connected to. Use mingetty, screen, putty, or something like this to access the kvm from the server. The port is called `/dev/ttyAMA0`. + +## Enable Ethernet-over-USB connection between the server and Pi-KVM +When combined with configuring a DNS server, FTP, or SMB (for example), this is a powerful way to extend the capabilities of Pi-KVM. + +1. Edit `/etc/kvmd/override.yaml` (remove `{}` if this your first configuration entry) and add these lines: + ``` yaml + otg: + devices: + ethernet: + enabled: true + driver: ecm + host_mac: 48:6f:73:74:50:43 + kvm_mac: 42:61:64:55:53:42 + ``` + The `host_mac` address will be used on the server's network interface. The `kvm_mac` means the address that will be assigned to the local interface on the Pi-KVM. The KVM interface will be called `usb0`.r's network interface. If the `host_mac` or `kvm_mac` is not specified, a random value will be used. The `driver` parameter means the protocol that will be used for the USB network. The default value is `ecm` so it can be passed it this example. Other possible values are `eem`, `ncm` and `rndis`. +2. Perform `reboot`. + +:exclamation: When this feature is activated, the Pi-KVM interface and other ports will be available to the host. Use iptables for restrictions. From 57407e9936d04527dbd28086bf6b5c574feac16b Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Thu, 1 Oct 2020 03:51:28 +0300 Subject: [PATCH 05/12] Update cookbook.md --- pages/cookbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cookbook.md b/pages/cookbook.md index f478d7e0..244ddace 100644 --- a/pages/cookbook.md +++ b/pages/cookbook.md @@ -24,7 +24,7 @@ # kvmd-helper-otgmsd-remount ro ``` -## Enable serial console on Pi-KVM +## Enable Serial-over-USB connection/console between the server and Pi-KVM This can be used for terminal access from the managed server to the pikvm, or for any other purpose that requires a serial connection. In the last case, you only need to perform step 1 and reboot. 1. Edit `/etc/kvmd/override.yaml` (remove `{}` if this your first configuration entry) and add these lines: From 4dad35497321e8a1bccc6cc3ba30e63375203b08 Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Thu, 1 Oct 2020 03:52:05 +0300 Subject: [PATCH 06/12] Update cookbook.md --- pages/cookbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cookbook.md b/pages/cookbook.md index 244ddace..6fcd2eef 100644 --- a/pages/cookbook.md +++ b/pages/cookbook.md @@ -1,4 +1,4 @@ -# This Pi-KVM cookbook has some undocumented recipes for your Pi-KVM +# Some random and useful recipes ## Take a HDMI screenshot via console on Pi-KVM ``` # curl --unix-socket /run/kvmd/ustreamer.sock http://localhost/snapshot -o screen.jpg From e3cfbb518ec8acec6208789f69d2ee51a0f85e50 Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Thu, 1 Oct 2020 04:13:46 +0300 Subject: [PATCH 07/12] Create ipmi.md --- pages/ipmi.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 pages/ipmi.md diff --git a/pages/ipmi.md b/pages/ipmi.md new file mode 100644 index 00000000..61b7439f --- /dev/null +++ b/pages/ipmi.md @@ -0,0 +1,50 @@ +# 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 Pi-KVM. Its advantage is that it is supported by many enterprise systems. + +:exclamation: Although Pi-KVM 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 enable ipmi IPMI BMC follow these steps: +1. Switch the filesystem to the RW-mode: + ``` + # rw + ``` +2. Setup IPMI account in file `/etc/kvmd/ipmipasswd`. +3. Enable `kvmd-ipmi` daemon: + ``` + # systemctl enable --now kvmd-ipmi + ``` +4. Switch the filesystem back to the RO: + ``` + # ro + ``` + +# 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 Pi-KVM 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: + +```nginx +location /redfish { + proxy_pass http://kvmd; + include /etc/kvmd/nginx/loc-proxy.conf; + auth_request off; +} +``` + +:exclamation: 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 Pi-KVM. 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 +``` + +:exclamation: 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. From 6eed7d6e97c7a3a53bd0510588f60b37f53b7053 Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Sat, 3 Oct 2020 11:24:25 +0300 Subject: [PATCH 08/12] Update gpio.md --- pages/gpio.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/gpio.md b/pages/gpio.md index 8940875c..32fffcdf 100644 --- a/pages/gpio.md +++ b/pages/gpio.md @@ -145,7 +145,7 @@ Some rules and customization options: - If the switch mode is disabled, only a button will be displayed. If pulse is disabled, only a switch will be shown. - To change the LED's color specify it after the channel name like `"led1|red"`. Available: `green`, `yellow` and `red`. - To change title of the button, write some its name like `"relay1|My cool relay"`. -- Buttons and switches can request confirmation on acting. To do this write its name like `"relay1|confirm|My cool relay"`. The third argument Title is required in this case. +- Buttons and switches can request confirmation on acting. To do this write its name like `"relay1|confirm|My cool relay"`. The third argument with a title is required in this case. # Hardware modules From 529303a52ddea6a22f2713b3b93b1b340b45fd75 Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Sat, 3 Oct 2020 11:35:35 +0300 Subject: [PATCH 09/12] Update cookbook.md --- pages/cookbook.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pages/cookbook.md b/pages/cookbook.md index 6fcd2eef..228cb56d 100644 --- a/pages/cookbook.md +++ b/pages/cookbook.md @@ -24,8 +24,8 @@ # kvmd-helper-otgmsd-remount ro ``` -## Enable Serial-over-USB connection/console between the server and Pi-KVM -This can be used for terminal access from the managed server to the pikvm, or for any other purpose that requires a serial connection. In the last case, you only need to perform step 1 and reboot. +## Enable Serial-over-USB connection +Specifically to v2. This can be used for terminal access from the managed server to the Pi-KVM, or for any other purpose that requires a serial connection. In the last case, you only need to perform step 1 and reboot. 1. Edit `/etc/kvmd/override.yaml` (remove `{}` if this your first configuration entry) and add these lines: ``` yaml @@ -52,8 +52,8 @@ This can be used for terminal access from the managed server to the pikvm, or fo ``` 5. Once Pi-KVM is rebooted you will have access to a virtual serial port on the server that the USB is connected to. Use mingetty, screen, putty, or something like this to access the kvm from the server. The port is called `/dev/ttyAMA0`. -## Enable Ethernet-over-USB connection between the server and Pi-KVM -When combined with configuring a DNS server, FTP, or SMB (for example), this is a powerful way to extend the capabilities of Pi-KVM. +## Enable Ethernet-over-USB network +Specifically to v2. When combined with configuring a DNS server, FTP, or SMB (for example), this is a powerful way to extend the capabilities of Pi-KVM. 1. Edit `/etc/kvmd/override.yaml` (remove `{}` if this your first configuration entry) and add these lines: ``` yaml From 729de3ab0ea15fb892184f1cf8192eee65594e15 Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Sat, 3 Oct 2020 11:38:57 +0300 Subject: [PATCH 10/12] Update README.md --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index e6750610..8315c1a6 100644 --- a/README.md +++ b/README.md @@ -330,6 +330,11 @@ Our future [v3 platform](#the-future-v3-platform-work-in-progress) will contain * [Centralized authorization for multiple Pi-KVMs](https://github.com/pikvm/kvmd-auth-server). * [Cookbook](pages/cookbook.md). + - [Take a HDMI screenshot via console on Pi-KVM](pages/cookbook.md#take-a-hdmi-screenshot-via-console-on-pi-kvm). + - [Get installed KVMD version via console](pages/cookbook.md#get-installed-kvmd-version-via-console). + - [Upload .ISO images manually](pages/cookbook.md#upload-iso-images-manually). + - [Enable Serial-over-USB connection](pages/cookbook.md#enable-serial-over-usb-connection). + - [Enable Ethernet-over-USB network](pages/cookbook.md#enable-ethernet-over-usb-network). ----- From 0b50b708c27f92bd5cf370f47059a92874e7851e Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Sat, 3 Oct 2020 11:56:13 +0300 Subject: [PATCH 11/12] Update ipmi.md --- pages/ipmi.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/pages/ipmi.md b/pages/ipmi.md index 61b7439f..01dbc3af 100644 --- a/pages/ipmi.md +++ b/pages/ipmi.md @@ -19,6 +19,11 @@ To enable ipmi IPMI BMC follow these steps: ``` # ro ``` +5. Here some examples (on a remote PC: + ``` + $ ipmitool -I lanplus -U admin -P admin -H pikvm power status + $ ipmitool -I lanplus -U admin -P admin -H pikvm power on + ``` # Redfish [Redfish](https://www.dmtf.org/standards/redfish) is a more modern server management protocol designed to replace IPMI. @@ -47,4 +52,10 @@ If there is a file in your system after the update `/etc/kvmd/nginx/kvmd.ctx-ser :exclamation: 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. +To access the Redfish API, use HTTP Basic Auth. Also you can use the [redfishtool](https://github.com/DMTF/Redfishtool): + +``` +$ redfishtool -S Never -r pikvm2 root +$ redfishtool -S Never -u admin -p admin -r pikvm Systems +$ redfishtool -S Never -u admin -p admin -r pikvm Systems reset ForceOff +``` From 213b3fc80338251cccf7df1b6828c328133ea8cf Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Sun, 4 Oct 2020 04:38:52 +0300 Subject: [PATCH 12/12] Update ipmi.md --- pages/ipmi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/ipmi.md b/pages/ipmi.md index 01dbc3af..655dc043 100644 --- a/pages/ipmi.md +++ b/pages/ipmi.md @@ -55,7 +55,7 @@ If there is a file in your system after the update `/etc/kvmd/nginx/kvmd.ctx-ser To access the Redfish API, use HTTP Basic Auth. Also you can use the [redfishtool](https://github.com/DMTF/Redfishtool): ``` -$ redfishtool -S Never -r pikvm2 root +$ 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 ```