From 88f69c9b75156283b5e83b3bc1d02353c99ff7b0 Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Tue, 25 Jul 2023 19:22:41 +0300 Subject: [PATCH] new --- docs/usb_dynamic.md | 107 +++++++++++++++++++++++++++++++++++++++++++ docs/usb_ethernet.md | 4 +- mkdocs.yml | 1 + 3 files changed, 110 insertions(+), 2 deletions(-) create mode 100644 docs/usb_dynamic.md diff --git a/docs/usb_dynamic.md b/docs/usb_dynamic.md new file mode 100644 index 0000000..8ef7d9f --- /dev/null +++ b/docs/usb_dynamic.md @@ -0,0 +1,107 @@ +# Dynamic USB configuration + +PiKVM emulates a number of USB devices to ensure normal operation: keyboards, mouse and mass storage drive. +Also an additional [relative mouse](mouse.md) may be present (like on PiKVM V4 by default), +or a user configured [USB Ethernet](usb_ethernet.md) or [Serial port](usb_serial.md). + +In rare cases, the host BIOS/UEFI may not understand such a large number of emulated devices on single USB port, +so some of them may need to be disabled. USB reconfiguration usually requires a reboot, but it is possible +to temporarily disable already configured existing emulated devices. + +!!! warning + This feature is experimental. Due to the imperfections of the kernel modules, rarely a dynamic configuration change + can lead to a kernel panic and reboot. + + For PiKVM V3 and V4 this is considered more secure because they have two independent watchdog systems + that can bring devices back to life after a timeout of a few minutes. + + +## Command-line utility + +The `kvmd-otgconf` utility allows you to view and modify the USB configuration on the fly. +It requires root permission and can be used for example from a web terminal. + +View the config: +``` +# kvmd-otgconf ++ hid.usb0 # Keyboard ++ hid.usb1 # Absolute Mouse ++ hid.usb2 # Relative Mouse ++ mass_storage.usb0 # Mass Storage Drive +``` +Each line represents a device (function). First comes plus or minus sign (the device on or off), then the name of the device and its description. + +Disabling the device: +``` +[root@pikvm ~]# kvmd-otgconf --disable-function mass_storage.usb0 ++ hid.usb0 # Keyboard ++ hid.usb1 # Absolute Mouse ++ hid.usb2 # Relative Mouse +- mass_storage.usb0 # Mass Storage Drive +``` + +Enabling the device: +``` +[root@pikvm ~]# kvmd-otgconf --enable-function mass_storage.usb0 ++ hid.usb0 # Keyboard ++ hid.usb1 # Absolute Mouse ++ hid.usb2 # Relative Mouse ++ mass_storage.usb0 # Mass Storage Drive +``` + + +## Web UI menu + +Using the pseudo-GPIO driver, you can also control devices via the menu in the web interface. +Read about GPIO basics [here](gpio.md). + +To setup the menu, use `kvmd-otgconf` to generate the configuration, and combine it +with your existing one in `/etc/kvmd/override.yaml` in a usual way. + +```yaml +# kvmd-otgconf --make-gpio-config +kvmd: + gpio: + drivers: + otgconf: + type: otgconf + scheme: + hid.usb0: + driver: otgconf + mode: output + pin: hid.usb0 + pulse: + delay: 0 + hid.usb1: + driver: otgconf + mode: output + pin: hid.usb1 + pulse: + delay: 0 + hid.usb2: + driver: otgconf + mode: output + pin: hid.usb2 + pulse: + delay: 0 + mass_storage.usb0: + driver: otgconf + mode: output + pin: mass_storage.usb0 + pulse: + delay: 0 + view: + table: + - - '#Keyboard' + - '#hid.usb0' + - hid.usb0 + - - '#Absolute Mouse' + - '#hid.usb1' + - hid.usb1 + - - '#Relative Mouse' + - '#hid.usb2' + - hid.usb2 + - - '#Mass Storage Drive' + - '#mass_storage.usb0' + - mass_storage.usb0 +``` diff --git a/docs/usb_ethernet.md b/docs/usb_ethernet.md index bfa1fcf..8226d33 100644 --- a/docs/usb_ethernet.md +++ b/docs/usb_ethernet.md @@ -33,7 +33,7 @@ Specifically to V2+. When combined with configuring a DNS server, FTP, or SMB (f 1: Manual driver installation is required. [Download RNDIS 5 Windows](driver/win/pikvm-rndis5.inf)
2: Automatic driver installation since kvmd-3.53 -2. To automatically configure the USB network on the server recommended using the service `kvmd-otgnet`. It configures the firewall, assigns an address to the local PiKVM interface `usb0` and starts DHCP so the managed server can get the IPv4 address. By default, the address `169.254.0.1/28` to interface `usb0` will be assigned. One of the other addresses from the network `169.254.0.0./28` will be assigned to the server when it requests it via DHCP. For security reasons, all incoming connections from the server to the PiKVM side are blocked (except for ICMP and UDP port 67 which is used for DHCP). If you want to allow access from the server to the PiKVM interface, then you need to add ports 80 and 443 to the whitelist using `/etc/kvmd/override.yaml` file like this: +2. To automatically configure the USB network on the server recommended using the service `kvmd-otgnet`. It configures the firewall, assigns an address to the local PiKVM interface `usb0` and starts DHCP so the managed server can get the IPv4 address. By default, the address `172.30.30.0/24` to interface `usb0` will be assigned. One of the other addresses from the network `172.30.30.0/24` will be assigned to the server when it requests it via DHCP. For security reasons, all incoming connections from the server to the PiKVM side are blocked (except for ICMP and UDP port 67 which is used for DHCP). If you want to allow access from the server to the PiKVM interface, then you need to add ports 80 and 443 to the whitelist using `/etc/kvmd/override.yaml` file like this: ```yaml otgnet: @@ -150,5 +150,5 @@ This has been proven to work with Windows: 14. You're done - the device should now be recognized:
![grafik](https://user-images.githubusercontent.com/100349/149661295-97d8d8f9-5c40-4d80-b3a2-c544ca8c7224.png) -15. Verify the card is working by pinging your PiKVM in a console: `ping 169.254.0.1`:
+15. Verify the card is working by pinging your PiKVM in a console: `ping 172.30.30.1`:
![grafik](https://user-images.githubusercontent.com/100349/149662794-51d34926-a6d4-425a-8cdd-b16d69e458ee.png) diff --git a/mkdocs.yml b/mkdocs.yml index c777c56..fd127e1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -85,6 +85,7 @@ nav: - "Mass Storage Drive": msd.md - "Ethernet-over-USB": usb_ethernet.md - "Serial-over-USB": usb_serial.md + - "Dynamic USB configuration": usb_dynamic.md - "GPIO (pins, relays, lamps, etc)": gpio.md - "Advanced usage": - "Using VNC": vnc.md