mirror of https://github.com/pikvm/pikvm.git
1 line
644 KiB
JSON
1 line
644 KiB
JSON
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"PiKVM Handbook","text":"<p>Welcome to the PiKVM Handbook\u2014a complete documentation of the Open-Source KVM-over-IP on Raspberry Pi!</p> <p>Here you will find comprehensive information about all aspects of the operation of PiKVM, get answers to your most difficult questions and be able to solve the problems that have arisen.</p>"},{"location":"#where-to-start","title":"Where to start?","text":"<ul> <li> <p>Check out the device instructions:</p> <p>PiKVM V4 Mini & Plus</p> <p>PiKVM V3</p> <p>DIY PiKVM V2</p> <p>DIY PiKVM V1</p> </li> <li> <p>Learn about the basics of working with PiKVM.</p> </li> <li> <p>Explore the features of PiKVM using the site's table of contents.</p> </li> <li> <p>If you encounter a problem, take a look at the FAQ, but if nothing helped, feel free to contact our Support - many of experienced users and the PiKVM team will definitely help you.</p> </li> </ul>"},{"location":"#links","title":"Links","text":"<ul> <li>Website: https://pikvm.org</li> <li>GitHub: https://github.com/pikvm</li> <li>Discord: </li> <li>Reddit: </li> <li>Forum</li> </ul>"},{"location":"3d_printing/","title":"Cases for 3D printing","text":""},{"location":"3d_printing/#pikvm-v3-hat-cases","title":"PiKVM V3 HAT cases","text":"<ul> <li>v3.3 model (Kickstarter, Store)</li> <li>Unofficial but great v3.3 case mod for Noctua fan</li> <li>v3.2 model (Pre-release)</li> </ul>"},{"location":"3d_printing/#diy-cases","title":"DIY cases","text":"Model Notes https://www.thingiverse.com/thing:4799094 Case for the USB-C/PWR Splitter without Barrel jack https://www.thingiverse.com/thing:4931970 Raspberry Pi 4 Pi-KVM Case https://www.thingiverse.com/thing:4862304 Case for PiKVM (LCD + ATX) https://www.thingiverse.com/thing:4868258 R4C3R - Low Profile PCIe bracket for PiKVM based on Raspberry Pi Zero + Lusya + ATX controls https://www.thingiverse.com/thing:4866005 R4C3R - Full Profile PCIe bracket for PiKVM based on Raspberry Pi Zero + Lusya + ATX controls https://www.thingiverse.com/thing:4832248 Case for the USB-C/PWR Splitter without Barrel jack and HDMI-CSI bridge https://www.thingiverse.com/thing:4916230 A very compact case without internal power splitter https://www.thingiverse.com/thing:4915627 ZeroW + CSI case https://www.thingiverse.com/thing:4950281 PiKVM RETRO Case for CSI-2 C779 Bridge w/ OLED Display Screen https://www.thingiverse.com/thing:4950280 USB Power Blocker Case https://www.thingiverse.com/thing:4642116 Conix's PI-KVM case for v2 https://www.thingiverse.com/thing:7148243 Wall mount for PiKVM v3"},{"location":"api/","title":"HTTP API reference","text":"<p>This document describes the PiKVM API. Since the system consists of microservices, here is a common API with a common entry point provided by Nginx. The below examples use <code>curl</code> and <code>websocat</code> with the <code>-k</code> option disables SSL certificate verification, since the self-signed certificateis are used in the default installation.</p> <p>There is a third-party library for using the PiKVM API. Please note that this is an unofficial library, so use it carefully.</p>"},{"location":"api/#authentication","title":"Authentication","text":"<p>All APIs are restricted to authentication. To make requests, you either need to auth each request individually, or get a token and pass it as a cookie with each request.</p> <p>With enabled 2FA, you will need to add the one-time code to the password without spaces. That is, if the password is <code>foobar</code> and the code is <code>123456</code>, then you need to use <code>foobar123456</code> as the password.</p> <p>The code can be generated using any TOTP library, for example in Python:</p> <pre><code>import requests\nimport pyotp\n\nuser = \"admin\"\npasswd = \"admin\"\nsecret = \"3OBBOGSJRYRBZH35PGXURM4CMWTH3WSU\" # Can be found in /etc/kvmd/totp.secret\n\nprint(requests.get(\n url=\"https://pikvm/api/info\",\n verify=False, # For self-signed SSL certificate\n headers={\n \"X-KVMD-User\": user,\n \"X-KVMD-Passwd\": passwd + pyotp.TOTP(secret).now(),\n },\n).text)\n</code></pre> <p>Since in the borderline case of the 2FA code lifetime, the code may be invalid, it makes sense to either handle error 403 by repeating the request in seconds.</p> <p>A more correct way is to combine this method and check the remaining lifetime and postpone the request if there is a second or so left. You can find out how much time is left in this way:</p> <pre><code>totp = pyotp.TOTP(secret)\nnow = int(time.time())\nremaining = now - (now % totp.interval)\n</code></pre>"},{"location":"api/#single-request-authentication","title":"Single-request authentication","text":"<p>There are two options here:</p> <ul> <li> <p>Using X-headers. Just pass <code>X-KVMD-User</code> and <code>X-KVMD-Passwd</code> with the request:</p> <pre><code>$ curl -k -H X-KVMD-User:admin -H X-KVMD-Passwd:admin https://<pikvm-ip>/api/auth/check\n</code></pre> </li> <li> <p>Using HTTP Basic Auth. Please note: contrary to the standard, this method DOES NOT use the <code>WWW-Authenticate</code> header. HTTP Basic Auth in this implementation is intended only for compatibility with other systems, such as Prometheus.</p> <pre><code>$ curl -k -u admin:admin https://<pikvm-ip>/api/auth/check\n</code></pre> </li> </ul>"},{"location":"api/#session-based-cookie-auth","title":"Session-based cookie auth","text":"<ol> <li> <p>Get the access token for the user using <code>POST /api/auth/login</code>:</p> <pre><code>$ curl -k -v -X POST --data user=admin --data passwd=admin https://pikvm/api/auth/login\n...\n< Set-Cookie: auth_token=796cb83b11de4fcb749bc1bad14a91fb06dede84672b2f847fef1e988e6900de; Path=/\n...\n</code></pre> <p>On success the cookie <code>auth_token</code> will be received with <code>200 OK</code>. On invalid user or password you will get <code>403 Forbidden</code>.</p> </li> <li> <p>The handle <code>GET /api/auth/check</code> can be used for check the auth status. Return of <code>200 OK</code> will signal that user is authenticated. If the token or any of the single-request auth methods are missing, <code>401 Unauthorized</code> will be returned. In case of incorrect credentials or token, <code>403 Forbidden</code> will be returned.</p> </li> <li> <p>The handle <code>POST /api/auth/logout</code> can be used to invalidate session token. The response codes will be similar to the previous handle.</p> </li> </ol>"},{"location":"api/#session-based-login-using-html-form","title":"Session-based login using HTML form","text":"<p>You can submit PiKVM credentials from another site and go directly to the KVM page by passing the redirect parameter as follows:</p> <pre><code><html>\n<body>\n <form method=\"POST\" action=\"https://pikvm/api/auth/login\">\n <input name=\"user\" value=\"admin\">\n <input name=\"passwd\" value=\"admin\">\n <input name=\"expire\" value=\"0\">\n <input name=\"redirect\" value=\"/kvm/\"> <!-- Available since KVMD 4.108 -->\n <button type=\"submit\">Open PiKVM</button>\n </form>\n</body>\n<html>\n</code></pre>"},{"location":"api/#websocket-events","title":"WebSocket events","text":"<p>Most of the data during the user's work with PiKVM is transmitted over WebSocket. This includes mouse events, keyboard input, and changing the state of the various subsystems (such as ATX and Mass Storage Drive). Each event type will be described in the corresponding paragraph for its component. When connecting via WebSocket, the client receives current states as separate events. Then, as the states change, it will receive new events.</p> <p>In a normal situation, opening a socket session triggers the video streamer to start. The streamer works as long as there is at least one client connected via WebSocket. After the last connection is closed and the client timeout expires, the streamer will also be terminated.</p> <p>It is possible create a session that will not start the streamer and will not be counted when counting clients to stop the streamer. To do this, use the URL parameter <code>stream=0</code>:</p> <pre><code>$ websocat -k wss://<pikvm-ip>/api/ws?stream=0 -H X-KVMD-User:admin -H X-KVMD-Passwd:admin\n</code></pre> Output with initial events <pre><code>{\"event_type\": \"gpio_model_state\", \"event\": {\"scheme\": {\"inputs\": {\"led1\": {\"hw\": {\"driver\": \"__gpio__\", \"pin\": 19}}, \"led2\": {\"hw\": {\"driver\": \"__gpio__\", \"pin\": 16}}}, \"outputs\": {\"button1\": {\"switch\": false, \"pulse\": {\"delay\": 0.1, \"min_delay\": 0.1, \"max_delay\": 0.1}, \"hw\": {\"driver\": \"__gpio__\", \"pin\": 26}}, \"button2\": {\"switch\": false, \"pulse\": {\"delay\": 0.1, \"min_delay\": 0.1, \"max_delay\": 0.1}, \"hw\": {\"driver\": \"__gpio__\", \"pin\": 20}}, \"relay1\": {\"switch\": true, \"pulse\": {\"delay\": 0.1, \"min_delay\": 0.1, \"max_delay\": 0.1}, \"hw\": {\"driver\": \"relay\", \"pin\": 0}}, \"relay2\": {\"switch\": true, \"pulse\": {\"delay\": 2.0, \"min_delay\": 0.1, \"max_delay\": 5.0}, \"hw\": {\"driver\": \"relay\", \"pin\": 1}}}}, \"view\": {\"header\": {\"title\": \"Switches\"}, \"table\": [[{\"type\": \"label\", \"text\": \"Generic GPIO leds\"}], null, [{\"type\": \"label\", \"text\": \"Test 1:\"}, {\"type\": \"input\", \"channel\": \"led1\", \"color\": \"green\"}, {\"type\": \"output\", \"channel\": \"button1\", \"text\": \"Click\"}], [{\"type\": \"label\", \"text\": \"Test 2:\"}, {\"type\": \"input\", \"channel\": \"led2\", \"color\": \"green\"}, {\"type\": \"output\", \"channel\": \"button2\", \"text\": \"Click\"}], null, [{\"type\": \"label\", \"text\": \"HID Relays /dev/hidraw0\"}], null, [{\"type\": \"label\", \"text\": \"Relay #1:\"}, {\"type\": \"output\", \"channel\": \"relay1\", \"text\": \"Boop 0.1\"}], [{\"type\": \"label\", \"text\": \"Relay #2:\"}, {\"type\": \"output\", \"channel\": \"relay2\", \"text\": \"Boop 2.0\"}]]}}}\n{\"event_type\": \"info_extras_state\", \"event\": {\"vnc\": {\"name\": \"VNC\", \"description\": \"Show VNC information\", \"icon\": \"share/svg/vnc.svg\", \"path\": \"vnc\", \"keyboard_cap\": false, \"daemon\": \"kvmd-vnc\", \"port\": 5900, \"place\": 20, \"enabled\": true}, \"ipmi\": {\"name\": \"IPMI\", \"description\": \"Show IPMI information\", \"icon\": \"share/svg/ipmi.svg\", \"path\": \"ipmi\", \"keyboard_cap\": false, \"daemon\": \"kvmd-ipmi\", \"port\": 623, \"place\": 21, \"enabled\": true}}}\n{\"event_type\": \"info_hw_state\", \"event\": {\"platform\": {\"type\": \"rpi\", \"base\": \"Virtual Raspberry Pi\"}, \"health\": {\"temp\": {\"cpu\": 36.511, \"gpu\": 35.0}, \"throttling\": {\"raw_flags\": 0, \"parsed_flags\": {\"undervoltage\": {\"now\": false, \"past\": false}, \"freq_capped\": {\"now\": false, \"past\": false}, \"throttled\": {\"now\": false, \"past\": false}}}}}}\n{\"event_type\": \"info_meta_state\", \"event\": {\"server\": {\"host\": \"localhost.localdomain\"}, \"kvm\": {}}}\n{\"event_type\": \"info_system_state\", \"event\": {\"kvmd\": {\"version\": \"1.102\"}, \"streamer\": {\"app\": \"ustreamer\", \"version\": \"1.25\", \"features\": {\"WITH_OMX\": false, \"WITH_GPIO\": false, \"WITH_PTHREAD_NP\": true, \"WITH_SETPROCTITLE\": true, \"HAS_PDEATHSIG\": true}}, \"kernel\": {\"system\": \"Linux\", \"release\": \"5.8.10-arch1-1\", \"version\": \"#1 SMP PREEMPT Thu, 17 Sep 2020 18:01:06 +0000\", \"machine\": \"x86_64\"}}}\n{\"event_type\": \"wol_state\", \"event\": {\"enabled\": false, \"target\": {\"ip\": \"255.255.255.255\", \"port\": 9, \"mac\": \"\"}}}\n{\"event_type\": \"gpio_state\", \"event\": {\"inputs\": {\"led1\": {\"online\": true, \"state\": false}, \"led2\": {\"online\": true, \"state\": false}}, \"outputs\": {\"button1\": {\"online\": true, \"state\": false, \"busy\": false}, \"button2\": {\"online\": true, \"state\": false, \"busy\": false}, \"relay1\": {\"online\": false, \"state\": false, \"busy\": false}, \"relay2\": {\"online\": false, \"state\": false, \"busy\": false}}}}\n{\"event_type\": \"hid_state\", \"event\": {\"online\": true, \"keyboard\": {\"online\": true, \"leds\": {\"caps\": false, \"scroll\": false, \"num\": false}}, \"mouse\": {\"online\": true}}}\n{\"event_type\": \"atx_state\", \"event\": {\"enabled\": true, \"busy\": false, \"leds\": {\"power\": false, \"hdd\": false}}}\n{\"event_type\": \"msd_state\", \"event\": {\"enabled\": true, \"online\": true, \"busy\": false, \"storage\": {\"size\": 234950152192, \"free\": 23514271744, \"images\": {}, \"uploading\": false}, \"drive\": {\"image\": null, \"connected\": false, \"cdrom\": true}, \"features\": {\"multi\": true, \"cdrom\": true}}}\n{\"event_type\": \"streamer_state\", \"event\": {\"limits\": {\"max_fps\": 40}, \"params\": {\"desired_fps\": 30, \"quality\": 80}, \"snapshot\": {\"saved\": null}, \"streamer\": null, \"features\": {\"quality\": true, \"resolution\": false}}}\n{\"event_type\": \"loop\", \"event\": {}}\n</code></pre> <p>After connecting the client receives a bundle of states of all KVMD subsystems. After the batch is completed, it sends a <code>loop</code> event, which means that the websocket has entered event loop mode. Now it will send new states and respond to client's requests.</p> <p>Another type of event is <code>ping</code>, which can be sent by the client: <code>{\"event_type\": \"ping\", \"event\": {}}</code>. If the server is running, it will respond with pong: <code>{\"event_type\": \"pong\", \"event\": {}}</code>.</p> Sending key events using Python <p>For keypresses, set <code>event_type</code> to <code>key</code> and fill in the <code>event</code> structure with <code>key</code> and <code>state</code>, where <code>key</code> is the key from mapping and <code>state</code> is boolean that determines if the key is pressed or released: </p> <pre><code># python, install websocket-client\nimport websocket\nimport ssl, time\nuri = \"wss://10.0.0.7/api/ws?stream=0\"\nheaders = {\"X-KVMD-User\": \"admin\", \"X-KVMD-Passwd\": \"admin\"}\nws = websocket.WebSocket(sslopt={\"cert_reqs\": ssl.CERT_NONE})\nws.connect(uri, header=headers)\n# Key codes: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values\nws.send('{\"event_type\": \"key\", \"event\": {\"key\": \"Enter\", \"state\": true}}')\ntime.sleep(0.05)\nws.send('{\"event_type\": \"key\", \"event\": {\"key\": \"Enter\", \"state\": false}}')\nws.close()\n</code></pre>"},{"location":"api/#system-functions","title":"System functions","text":""},{"location":"api/#get-system-info","title":"Get system info","text":"<p>Method: <code>GET</code></p> <p>Route: <code>/api/info</code></p> <p>Description: Returns the general information about the PiKVM device.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>fields</code> string optional Return only specified categories <code>auth</code>, <code>extras</code>, <code>fan</code>, <code>hw</code>, <code>meta</code>, <code>system</code> <p>Example of use:</p> <pre><code>$ curl -k -u admin:admin https://<pikvm-ip>/api/info?fields=hw\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {\n \"hw\": {\n \"health\": {\n \"cpu\": {\n \"percent\": 2\n },\n \"mem\": {\n \"available\": 1568993280,\n \"percent\": 14.6,\n \"total\": 1836331008\n },\n \"temp\": {\n \"cpu\": 45.277\n },\n \"throttling\": {\n \"ignore_past\": false,\n \"parsed_flags\": {\n \"freq_capped\": {\n \"now\": false,\n \"past\": false\n },\n \"throttled\": {\n \"now\": false,\n \"past\": false\n },\n \"undervoltage\": {\n \"now\": false,\n \"past\": false\n }\n },\n \"raw_flags\": 0\n }\n },\n \"platform\": {\n \"base\": \"Raspberry Pi 4 Model B Rev 1.5\",\n \"board\": \"rpi4\",\n \"model\": \"v3\",\n \"serial\": \"10000000C8DA432D\",\n \"type\": \"rpi\",\n \"video\": \"hdmi\"\n }\n }\n }\n}\u23ce \n</code></pre> <p>Each category is represented by its own event in the websocket (<code>info_hw_state</code>, <code>info_system_state</code>, etc). The event content has the same format as the category content in the API.</p>"},{"location":"api/#get-system-log","title":"Get system log","text":"<p>Method: <code>GET</code></p> <p>Route: <code>/api/log</code></p> <p>Description: Displays logs from all KVMD services as plain text.</p> Parameter Type Optionality Description Acceptable values <code>follow</code> boolean optional Turns the request into long-polling mode and follow log messages in real time Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <code>seek</code> integer optional Runs the log for the specified time in seconds <code>\u22650</code> <p>Example of use: the following query returns commit messages for the last 1 hour and enables the long-polling mode:</p> <pre><code>$ curl -k -u admin:admin 'https://<pikvm-ip>/api/log?follow=1&seek=3600'\n</code></pre> Example output <pre><code>[2025-06-10 22:38:07 kvmd.service] --- kvmd.apps.kvmd.auth INFO --- Authorized user 'admin' via auth service 'htpasswd'\n[2025-06-10 22:38:15 kvmd.service] --- kvmd.apps.kvmd.auth INFO --- Authorized user 'admin' via auth service 'htpasswd'\n</code></pre>"},{"location":"api/#hid","title":"HID","text":"<p>The PiKVM HID (Human Interface Device) API provides remote control capabilities for keyboard and mouse input devices. It allows users to perform the following operations:</p> <ul> <li>Get the device state and set/reset parameters.</li> <li>Send keyboard shortcuts and text to be typed in the host system.</li> <li>Send various mouse events: move to absolute coordinates and relatively, click virtual mouse buttons, and scroll the virtual mouse wheel.</li> </ul>"},{"location":"api/#get-devices-state","title":"Get devices state","text":"<p>Method: <code>GET</code></p> <p>Route: <code>/api/hid</code></p> <p>Description: Gets the current HID devices state.</p> <p>Query parameters: none.</p> <p>Example of use:</p> <pre><code>$ curl -k -u admin:admin https://<pikvm-ip>/api/hid\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {\n \"busy\": false,\n \"connected\": null,\n \"enabled\": true,\n \"jiggler\": {\n \"active\": false,\n \"enabled\": true,\n \"interval\": 60\n },\n \"keyboard\": {\n \"leds\": {\n \"caps\": false,\n \"num\": false,\n \"scroll\": false\n },\n \"online\": false,\n \"outputs\": {\n \"active\": \"\",\n \"available\": []\n }\n },\n \"mouse\": {\n \"absolute\": true,\n \"online\": false,\n \"outputs\": {\n \"active\": \"usb\",\n \"available\": [\n \"usb\",\n \"usb_rel\"\n ]\n }\n },\n \"online\": true\n }\n}\u23ce\n</code></pre>"},{"location":"api/#set-parameters","title":"Set parameters","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/hid/set_params</code></p> <p>Description: Configures HID device parameters, such as the type of emulated keyboard and mouse.</p> <p>Query parameters:</p> Parameter Type Optionality Description Acceptable values <code>keyboard_output</code> string optional Sets the type of the emulated keyboard <code>usb</code>, <code>ps2</code>, <code>disabled</code> <code>mouse_output</code> string optional Sets the type of the emulated mouse <code>usb</code>, <code>usb_win98</code>, <code>usb_rel</code>, <code>ps2</code>, <code>disabled</code> <code>jiggler</code> boolean optional Enable/disable mouse jiggler functionality <code>true</code> <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n https://<pikvm-ip>/api/hid/set_params?jiggler=0\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {}\n}\u23ce \n</code></pre>"},{"location":"api/#set-the-connected-state","title":"Set the connected state","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/hid/set_connected</code></p> <p>Description: Sets the HID devices connection state.</p> <p>Query parameters:</p> Parameter Type Optionality Description Acceptable values <code>connected</code> boolean required Sets the connection state Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n https://<pikvm-ip>/api/hid/set_connected?connected=0\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {}\n}\u23ce \n</code></pre>"},{"location":"api/#reset-devices-state","title":"Reset devices' state","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/hid/reset</code></p> <p>Description: Resets HID devices to their initial state.</p> <p>Query parameters: none</p> <p>Example of use:</p> <pre><code>$ curl -k -X POST -u admin:admin https://<pikvm-ip>/api/hid/reset\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {}\n}\u23ce \n</code></pre>"},{"location":"api/#get-keyboard-layouts","title":"Get keyboard layouts","text":"<p>Method: <code>GET</code></p> <p>Route: <code>/api/hid/keymaps</code></p> <p>Description: Gets available keyboard layouts and the current defaults for use with <code>POST /api/hid/print</code>.</p> <p>Query parameters: none</p> <p>Example of use:</p> <pre><code>$ curl -k -u admin:admin https://<pikvm-ip>/api/hid/keymaps\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {\n \"keymaps\": {\n \"available\": [\n \"ar\",\n \"bepo\",\n \"cz\",\n \"da\",\n \"de\",\n \"de-ch\",\n \"en-gb\",\n \"en-us\",\n \"en-us-altgr-intl\",\n \"en-us-colemak\",\n \"es\",\n \"et\",\n \"fi\",\n \"fo\",\n \"fr\",\n \"fr-be\",\n \"fr-ca\",\n \"fr-ch\",\n \"hr\",\n \"hu\",\n \"is\",\n \"it\",\n \"ja\",\n \"lt\",\n \"lv\",\n \"mk\",\n \"nl\",\n \"no\",\n \"pl\",\n \"pt\",\n \"pt-br\",\n \"ru\",\n \"sl\",\n \"sv\",\n \"th\",\n \"tr\"\n ],\n \"default\": \"de\"\n }\n }\n}\u23ce \n</code></pre>"},{"location":"api/#type-text-remotely","title":"Type text remotely","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/hid/print</code></p> <p>Description: Transmits user-defined text to emulate typing it on the PiKVM by sequencing key presses.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>limit</code> integer optional Maximum characters to process 0 = no limit. No maximum value. Default: 1024 <code>keymap</code> string optional Keymap to use (defaults to system default) Any keymap listed in the output of <code>GET /hid/keymaps</code> <code>slow</code> boolean optional Enables slow typing mode (regular large intervals between key presses), <code>false</code> by default Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <code>delay</code> float optional How many seconds to delay the transmission of keys by in the <code>slow</code> mode. Defaults to <code>0.02</code> when <code>slow</code> is enabled, otherwise defaults to <code>0</code> <code>0..5.0</code> <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n -d \"Einige Worte\" \\\n https://<pikvm-ip>/api/hid/print?keymap=de\n</code></pre> Example output <pre><code>{\n\"ok\": true,\n\"result\": {}\n}\u23ce \n</code></pre>"},{"location":"api/#send-a-keyboard-shortcut","title":"Send a keyboard shortcut","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/hid/events/send_shortcut</code></p> <p>Description: Sends a keyboard shortcut, or key combination, to be typed on the PiKVM.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>keys</code> string required Comma-separated list of key names For a full list of supported values, please see here. Use values from the <code>web_name</code> column <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n https://<pikvm-ip>/api/hid/events/send_shortcut?keys=ControlLeft,KeyL\n</code></pre> Example output <pre><code>{\n\"ok\": true,\n\"result\": {}\n}\u23ce\n</code></pre>"},{"location":"api/#send-a-single-key-event","title":"Send a single key event","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/hid/events/send_key</code></p> <p>Description: Transmits a command to emulate a single key press on the PiKVM.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>key</code> string required Key identifier to send For a full list of supported values, please see here <code>state</code> boolean optional Key state: <code>true</code> for press, <code>false</code> for release Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <code>finish</code> boolean optional Releases non-modifier keys right after pressing them so that they don't get stuck when the connection is not stable. Defaults to <code>false</code> Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n https://<pikvm-ip>/api/hid/events/send_key?key=Delete\n</code></pre> Example output <pre><code>{\n\"ok\": true,\n\"result\": {}\n}\u23ce\n</code></pre>"},{"location":"api/#send-mouse-button-events","title":"Send mouse button events","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/hid/events/send_mouse_button</code></p> <p>Description: Sends mouse button press/release events.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>button</code> string required Mouse button identifier <code>left</code>, <code>middle</code>, <code>right</code>, <code>up</code>, <code>down</code> <code>state</code> boolean optional Mouse button state: <code>true</code> for press, <code>false</code> for release Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n https://<pikvm-ip>/api/hid/events/send_mouse_button?button=left\n</code></pre> Example output <pre><code>{\n\"ok\": true,\n\"result\": {}\n}\u23ce\n</code></pre>"},{"location":"api/#move-the-mouse-pointer","title":"Move the mouse pointer","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/hid/events/send_mouse_move</code></p> <p>Description: Sends a command to move the mouse pointer to user-defined coordinates where 0,0 is the center of the screen. Only works if the mouse mode is set to <code>absolute</code> in the configuration.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>to_x</code> integer required Target X coordinate Any negative or positive integer value <code>to_y</code> integer required Target Y coordinate Any negative or positive integer value <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n 'https://<pikvm-ip>/api/hid/send_mouse_move?to_x=0&to_y=50'\n</code></pre> Example output <pre><code>{\n\"ok\": true,\n\"result\": {}\n}\u23ce \n</code></pre>"},{"location":"api/#move-the-mouse-ppinter-relatively","title":"Move the mouse ppinter relatively","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/hid/events/send_mouse_relative</code></p> <p>Description: Sends a command to move the mouse pointer by a relative offset in pixels. Only works if the mouse mode is set to <code>absolute</code> in the configuration.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>delta_x</code> integer required Horizontal movement delta Any negative or positive integer value <code>delta_y</code> integer required Vertical movement delta Any negative or positive integer value <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n 'https://<pikvm-ip>/api/hid/send_mouse_relative?delta_x=20&delta_y=200'\n</code></pre> Example output <pre><code>{\n\"ok\": true,\n\"result\": {}\n}\u23ce \n</code></pre>"},{"location":"api/#send-mouse-wheel-scroll-events","title":"Send mouse wheel scroll events","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/hid/events/send_mouse_wheel</code></p> <p>Description: Sends mouse wheel scroll events to be emulated on the host by PiKVM.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>delta_x</code> integer required Horizontal scroll delta Any negative or positive integer value <code>delta_y</code> integer required Vertical scroll delta Any negative or positive integer value <p>Example of use: Sends mouse wheel scroll events.</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n 'https://<pikvm-ip>/api/hid/send_mouse_wheel?delta_x=0&delta_y=200'\n</code></pre> Example output <pre><code>{\n\"ok\": true,\n\"result\": {}\n}\u23ce \n</code></pre>"},{"location":"api/#atx-power-management","title":"ATX power management","text":"<p>The PiKVM ATX API provides control over ATX (Advanced Technology eXtended) power management functions. It allows users perform the following operations:</p> <ul> <li>Get the current ATX state.</li> <li>Change the ATX state.</li> <li>Send an ATX button press event.</li> </ul>"},{"location":"api/#get-atx-state","title":"Get ATX state","text":"<p>Method: <code>GET</code></p> <p>Route: <code>/api/atx</code></p> <p>Description: Shows the current ATX state</p> <p>Query parameters: None.</p> <p>Example of use:</p> <pre><code>$ curl -k -u admin:admin https://<pikvm-ip>/api/atx\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {\n \"busy\": false, // True if ATX is busy performing an operation and does not accept commands\n \"enabled\": true,\n \"leds\": {\n \"hdd\": false,\n \"power\": false\n }\n }\n}\n</code></pre>"},{"location":"api/#set-atx-power","title":"Set ATX power","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/atx/power</code></p> <p>Description: Changes the ATX power state to desired.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>action</code> string optional Specifies desired state <code>on</code> - Turn on (do nothing in case PSU is already on). <code>off</code> - Turn off (aka soft-off), emulates click on the power button. <code>off_hard</code> - Perform long press on the power button (5+ seconds). <code>reset_hard</code> - Emulate pressing reset button (hardware hot reset) <code>wait</code> boolean optional Says if call should return immediately or just after finishing operation. Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n https://<pikvm-ip>/api/atx/power?action=on\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {}\n}\u23ce\n</code></pre>"},{"location":"api/#click-atx-button","title":"Click ATX button","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/atx/click</code></p> <p>Description: Sends the ATX button press event.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>button</code> string optional Specifies the desired PC case button <code>power</code> - Short click on the power button. <code>power_long</code> - Long press on the power button (5+ seconds). <code>reset</code> - Short click on the reset button. <code>wait</code> boolean optional Says if call should return immediately or just after finishing operation. Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n https://<pikvm-ip>/api/atx/click?button=power\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {}\n}\u23ce \n</code></pre>"},{"location":"api/#mass-storage-drive","title":"Mass Storage Drive","text":"<p>The PiKVM Mass Storage Drive API provides controls for remote management of disk images that can be mounted as virtual storage devices. It allows users perform the following operations:</p> <ul> <li>Get current MSD status and configuration</li> <li>Upload, download, and delete disk images</li> <li>Fetch disk images directly from URLs with progress streaming</li> <li>Connect/disconnect virtual storages, enable CD-ROM and read-write modes</li> <li>Set image names, access modes, and device type settings</li> </ul>"},{"location":"api/#get-msd-state","title":"Get MSD state","text":"<p>Method: <code>GET</code></p> <p>Route: <code>/api/msd</code></p> <p>Description: Retrieves the current state of the Mass Storage Device.</p> <p>Query parameters: None.</p> <p>Example of use:</p> <pre><code>$ curl -k -u admin:admin https://<pikvm-ip>/api/msd\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {\n \"busy\": false,\n \"drive\": {\n \"cdrom\": true,\n \"connected\": false,\n \"image\": null,\n \"rw\": false\n },\n \"enabled\": true,\n \"online\": true,\n \"storage\": {\n \"downloading\": null,\n \"images\": {},\n \"parts\": {\n \"\": {\n \"free\": 24358789120,\n \"size\": 24375590912,\n \"writable\": true\n }\n },\n \"uploading\": null\n }\n }\n}\u23ce\n</code></pre>"},{"location":"api/#upload-msd-image","title":"Upload MSD image","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/msd/write</code></p> <p>Description: uploads an ISO to the Mass Storage Device.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>image</code> string required Specifies the name of the image. Binary data should be passed to the POST body <code>filename.iso</code> <p>Example of use:</p> <pre><code>$ # create a test image\n$ dd if=/dev/zero of=test.iso bs=1M count=1\n\n$ # upload it to pikvm\n$ curl -v -X POST --data-binary @test.iso -k \\\n -u admin:admin \\\n https://<pikvm-ip>/api/msd/write?image=test.iso\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {}\n}\u23ce \n</code></pre>"},{"location":"api/#upload-msd-image-by-url","title":"Upload MSD image by URL","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/msd/write_remote</code></p> <p>Description: Downloads an image from HTTP(S) URL to the MSD.</p> <p>Note</p> <p>This is a long-polling request. Do not interrupt the request until the download is complete, otherwise the download will stop.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>url</code> string required Image URL Any URL using HTTP(S) <code>image</code> string optional Image name Any alphanumeric name like <code>image321.iso</code> <code>timeout</code> integer optional Remote request timeout, 10 seconds by default <code>\u22650</code> <p>Example of use:</p> <pre><code>$ # create test image\n$ dd if=/dev/zero of=test.iso bs=1M count=1\n\n$ # upload it to pikvm\n$ curl -v -X POST -k \\\n -u admin:admin \\\n https://<pikvm-ip>/api/msd/write_remote?url=http://example.com/test.iso\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {}\n}\u23ce \n</code></pre>"},{"location":"api/#set-msd-parameters","title":"Set MSD parameters","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/msd/set_params</code></p> <p>Description: Changes the current image and/or set drive parameters.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>image</code> string optional Change the current image <code>filename.iso</code> <code>cdrom</code> boolean optional Change the media type to the CD-ROM or Flash. <code>1</code> (CD-ROM) or <code>0</code> (Flash) <code>rw</code> boolean optional Sets read-write or read-only mode. Ignored (always read-only) when <code>cdrom=1</code> <code>1</code> (read-write) or <code>0</code> (read-only) <p>Example of use:</p> <pre><code>$ curl -X POST -k \\\n -u admin:admin \\\n 'https://<pikvm-ip>/api/msd/set_params?image=test.iso&cdrom=1'\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {}\n}\u23ce \n</code></pre>"},{"location":"api/#control-msd","title":"Control MSD","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/msd/set_connected</code></p> <p>Description: Connects or disconnects the MSD to/from the host.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>connected</code> boolean required Changes the state <code>1</code> connects the MSD, <code>0</code> disconnects it <p>Example of use:</p> <pre><code>$ curl -X POST -k \\\n -u admin:admin \\\n https://<pikvm-ip>/api/msd/set_connected?connected=1\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {}\n}\u23ce \n</code></pre>"},{"location":"api/#remove-msd-image","title":"Remove MSD image","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/msd/remove</code></p> <p>Description: Removes the specified image.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>image</code> string required Name of the image to remove <code>filename.iso</code> <p>Example of use:</p> <pre><code>$ curl -X POST -k \\\n -u admin:admin \\\n https://<pikvm-ip>/api/msd/remove?image=test.iso\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {}\n}\u23ce \n</code></pre>"},{"location":"api/#reset-msd","title":"Reset MSD","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/msd/reset</code></p> <p>Description: Drops all the custom parameters you set before and resets the Mass Storage Device to its default state.</p> <p>Query parameters: None.</p> <p>Example of use:</p> <pre><code>$ curl -X POST -k \\\n -u admin:admin \\\n https://<pikvm-ip>/api/msd/reset\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {}\n}\u23ce \n</code></pre>"},{"location":"api/#gpio","title":"GPIO","text":"<p>This is a PiKVP API for controlling User GPIO (General Purpose Input/Output) pins. It allows users perform the following operations:</p> <ul> <li>Read GPIO states.</li> <li>Switch pins on/off.</li> <li>Send pulses to GPIO channels.</li> </ul>"},{"location":"api/#get-gpio-state","title":"Get GPIO state","text":"<p>Method: <code>GET</code></p> <p>Route: <code>/api/gpio</code></p> <p>Description: Retrieves the current state of all GPIO channels.</p> <p>Query parameters: None.</p> <p>Example of use:</p> <pre><code>$ curl -k -u admin:admin https://<pikvm-ip>/api/gpio\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {\n \"model\": {\n \"scheme\": {\n \"inputs\": {},\n \"outputs\": {\n \"__v3_usb_breaker__\": {\n \"hw\": {\n \"driver\": \"__gpio__\",\n \"pin\": \"5\"\n },\n \"pulse\": {\n \"delay\": 0.0,\n \"max_delay\": 0.0,\n \"min_delay\": 0.0\n },\n \"switch\": true\n }\n }\n },\n \"view\": {\n \"header\": {\n \"title\": [\n {\n \"text\": \"GPIO\",\n \"type\": \"label\"\n }\n ]\n },\n \"table\": []\n }\n },\n \"state\": {\n \"inputs\": {},\n \"outputs\": {\n \"__v3_usb_breaker__\": {\n \"busy\": false,\n \"online\": true,\n \"state\": true\n }\n }\n }\n }\n}\u23ce \n</code></pre>"},{"location":"api/#switch-gpio-channel","title":"Switch GPIO channel","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/gpio/switch</code></p> <p>Description: Sets a GPIO channel to a specific state (on/off).</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>channel</code> string required The GPIO driver channel Alphanumeric channel name, e.g., <code>__v3_usb_breaker__</code> <code>state</code> boolean required The new switch state <code>1</code> to switch on, <code>0</code> to switch off <code>wait</code> boolean optional Defines when a call should return <code>1</code> return immediately, <code>0</code> return after finishing operation <p>Example of use:</p> <pre><code># Switch GPIO channel led1 to OFF state without waiting\n$ curl -k -X POST \\\n -u admin:admin \\\n https://<pikvm-ip>/api/gpio/switch?channel=led1&state=0&wait=0\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {}\n}\u23ce\n</code></pre>"},{"location":"api/#pulse-gpio-channel","title":"Pulse GPIO channel","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/gpio/pulse</code></p> <p>Description: Sends a pulse signal to a GPIO channel (briefly activates then deactivates). Only works for channels that support the pulse mode.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>channel</code> string required The GPIO driver channel Alphanumeric channel name, e.g., <code>led1</code> <code>delay</code> float optional The pulse time in seconds Any float number, <code>0</code> for default delay <code>wait</code> boolean optional Defines when a call should return <code>1</code> return immediately, <code>0</code> return after finishing operation <p>Example of use:</p> <pre><code># Send a pulse to GPIO channel led1 with 2 sec delay without waiting\n$ curl -k -X POST \\\n -u admin:admin \\\n 'https://<pikvm-ip>/api/gpio/pulse?channel=led1&delay=2.0&wait=0'\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {}\n}\u23ce\n</code></pre>"},{"location":"api/#streamer","title":"Streamer","text":"<p>The PiKVM Streamer API provides remote access to video stream capture and management functionality of PiKVM devices. It allows users perform the following operations:</p> <ul> <li>Capture screenshots.</li> <li>Perform optical character recognition (OCR) on captured images.</li> <li>Monitor the streamer's operational status.</li> </ul>"},{"location":"api/#get-streamer-state","title":"Get streamer state","text":"<p>Method: <code>GET</code></p> <p>Route: <code>/api/streamer</code></p> <p>Description: Retrieves the current state of the streamer.</p> <p>Query parameters: None</p> <p>Example of use:</p> <pre><code>$ curl -k -u admin:admin https://<pikvm-ip>/api/streamer\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {\n \"features\": {\n \"h264\": true,\n \"quality\": true,\n \"resolution\": false\n },\n \"limits\": {\n \"desired_fps\": {\n \"max\": 70,\n \"min\": 0\n },\n \"h264_bitrate\": {\n \"max\": 20000,\n \"min\": 25\n },\n \"h264_gop\": {\n \"max\": 60,\n \"min\": 0\n }\n },\n \"params\": {\n \"desired_fps\": 40,\n \"h264_bitrate\": 5000,\n \"h264_gop\": 30,\n \"quality\": 80\n },\n \"snapshot\": {\n \"saved\": null\n },\n \"streamer\": {\n \"encoder\": {\n \"quality\": 80,\n \"type\": \"M2M-IMAGE\"\n },\n \"h264\": {\n \"bitrate\": 5000,\n \"fps\": 60,\n \"gop\": 30,\n \"online\": true\n },\n \"instance_id\": \"\",\n \"sinks\": {\n \"h264\": {\n \"has_clients\": true\n },\n \"jpeg\": {\n \"has_clients\": false\n }\n },\n \"source\": {\n \"captured_fps\": 59,\n \"desired_fps\": 40,\n \"online\": true,\n \"resolution\": {\n \"height\": 720,\n \"width\": 1280\n }\n },\n \"stream\": {\n \"clients\": 0,\n \"clients_stat\": {},\n \"queued_fps\": 0\n }\n }\n }\n}\u23ce \n</code></pre>"},{"location":"api/#take-snapshot","title":"Take snapshot","text":"<p>Method: <code>GET</code></p> <p>Route: <code>/api/streamer/snapshot</code></p> <p>Description: Captures a snapshot from the video stream. Can optionally perform OCR text recognition or generate a preview image. For optical character recognition, the coordinates origin starts at top left.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>save</code> boolean optional Whether to save the snapshot, default: <code>false</code> Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <code>load</code> boolean optional Whether to load an existing snapshot, default: <code>false</code> Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <code>allow_offline</code> boolean optional Whether to allow taking snapshots when offline, default: <code>false</code> Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <code>ocr</code> boolean optional Whether to perform OCR text recognition on the snapshot, default: <code>false</code> Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <code>ocr_langs</code> string optional Comma-separated list of language codes for OCR recognition Typically, a 3-letter code, such as <code>eng</code> for English or <code>deu</code> for German. Run <code>pacman -Ss tesseract-data</code> on PiKVM to get the full list <code>ocr_left</code> integer optional X coordinate of the top left corner of the OCR region, default: <code>-1</code> <code>\u22650</code> <code>ocr_top</code> integer optional Y coordinate of the top left corner of the OCR region, default: <code>-1</code> <code>\u22650</code> <code>ocr_right</code> integer optional Width of the OCR region, default: <code>-1</code> <code>\u22650</code> <code>ocr_bottom</code> integer optional Height of the OCR region, default: <code>-1</code> <code>\u22650</code> <code>preview</code> boolean optional Whether to generate a preview image, default: <code>false</code> Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <code>preview_max_width</code> integer optional Maximum width for preview image, default: <code>0</code> Any positive integer value <code>preview_max_height</code> integer optional Maximum height for preview image, default: <code>0</code> Any positive integer value <code>preview_quality</code> integer optional JPEG quality for preview (valid stream quality value), default: <code>80</code> Any integer value in the 0..100 range <p>Example of use: the following command will capture a snapshot of the current video stream and save it to a JPEG file.</p> <pre><code>$ curl -k \\\n -u admin:admin \\\n 'https://<pikvm-ip>/api/streamer/snapshot?save=1&preview_quality=95' \\\n --output=file.jpg\n</code></pre> Example output <pre><code> % Total % Received % Xferd Average Speed Time Time Time Current\n Dload Upload Total Spent Left Speed\n100 107k 100 107k 0 0 619k 0 --:--:-- --:--:-- --:--:-- 619k\n</code></pre> <p>Example of use: the following command will capture a region of the current video stream (left corner starts at the top left, extends 1000px to the right and 150px to the bottom), run it through Tesseract for optical character recognition (language defined as English), and output the recognized text into the console.</p> <pre><code>$ curl -k \\\n -u admin:admin \\\n 'https://<pikvm-ip>/api/streamer/snapshot?ocr=true&ocr_left=0&ocr_top=0&ocr_right=1000&ocr_bottom=150&ocr_langs=eng'\n</code></pre> <p>Responses:</p> <ul> <li>When <code>ocr=true</code>:<ul> <li>Content-Type: <code>text/plain</code></li> <li>Body: Recognized text from the image</li> </ul> </li> <li>When <code>preview=true</code> or default:<ul> <li>Content-Type: <code>image/jpeg</code></li> <li>Body: JPEG image data (either preview or full snapshot)</li> </ul> </li> <li>When snapshot unavailable:<ul> <li>Status: 503 Service Unavailable</li> <li>Error: UnavailableError</li> </ul> </li> </ul>"},{"location":"api/#remove-snapshot","title":"Remove snapshot","text":"<p>Method: <code>DELETE</code></p> <p>Route: <code>/api/streamer/snapshot</code></p> <p>Description: Removes/deletes the current snapshot from memory.</p> <p>Query parameters: None</p> <p>Example of use:</p> <pre><code>$ curl -k -X DELETE \\\n -u admin:admin \\\n https://<pikvm-ip>/api/streamer/snapshot\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {}\n}\u23ce \n</code></pre>"},{"location":"api/#get-ocr-state","title":"Get OCR state","text":"<p>Method: GET</p> <p>Route: <code>/api/streamer/ocr</code></p> <p>Description: Retrieves the current state and configuration of the optical character recognition (OCR) service.</p> <p>Query parameters: None</p> <p>Example of use:</p> <pre><code>$ curl -k -u admin:admin https://<pikvm-ip>/api/streamer/ocr\n</code></pre> Example output <pre><code>{\n \"ok\": true,\n \"result\": {\n \"ocr\": {\n \"enabled\": true,\n \"langs\": {\n \"available\": [\n \"eng\",\n \"osd\"\n ],\n \"default\": [\n \"eng\"\n ]\n }\n }\n }\n}\u23ce\n</code></pre>"},{"location":"api/#switch","title":"Switch","text":"<p>The PiKVM Switch API provides handles to control the PiKVM Switch: get information, set active ports, and control beacons.</p> <p>The API heavily relies on specifying ports on the PiKVM Switch. There are two ways to do that: with continuous numbering or with float numbers. Both options are equally valid and supported.</p> <ol> <li>With continuous numbering, ports enumeration starts at 0 and ends at 19, because you can create up to 20 ports by adding more PiKVM Switch devices to the first Switch's downlink.</li> <li>If you use a float value, the integer part specifies the number of the unit in the downlink, while the fractional part specifies the number of the port on that unit.</li> </ol>"},{"location":"api/#get-switch-state","title":"Get Switch state","text":"<p>Method: <code>GET</code></p> <p>Route: <code>/api/switch</code></p> <p>Description: Returns the information about the PiKVM Switch state.</p> <p>Query parameters: None.</p> <p>Example of use:</p> <pre><code>$ curl -k -u admin:admin https://<pikvm-ip>/api/switch\n</code></pre> Example output <pre><code>FIXME\n</code></pre>"},{"location":"api/#set-active-port-previous","title":"Set active port (previous)","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/switch/set_active_prev</code></p> <p>Description: Switches to the previous active port.</p> <p>Query parameters: None.</p> <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n https://<pikvm-ip>/api/switch/set_active_prev\n</code></pre> Example output <pre><code>FIXME\n</code></pre>"},{"location":"api/#set-active-port-next","title":"Set active port (next)","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/switch/set_active_next</code></p> <p>Description: Switches to the next active port.</p> <p>Query parameters: None.</p> <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n https://<pikvm-ip>/api/switch/set_active_next\n</code></pre> Example output <pre><code>FIXME\n</code></pre>"},{"location":"api/#set-active-port-specific","title":"Set active port (specific)","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/switch/set_active</code></p> <p>Description: Switches to a specific port.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>port</code> float required Specifies the port number Integer in the 0..19 range or float (0,0 through 4,3) <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n https://<pikvm-ip>/api/switch/set_active?port=2,2\n</code></pre> Example output <pre><code>FIXME\n</code></pre>"},{"location":"api/#set-beacon","title":"Set beacon","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/switch/set_beacon</code></p> <p>Description: Controls beacon lights on ports or uplink/downlink units.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>state</code> boolean required Turn beacon on/off Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <code>port</code> float optional Specify the port beacon Integer in the 0..19 range or float (0,0 through 4,3) <code>uplink</code> integer optional Number of the uplink beacon, same as the port Integer in the 0..19 range or float (0,0 through 4,3) <code>downlink</code> integer optional Number of the downlink beacon, same as the port Integer in the 0..19 range or float (0,0 through 4,3) <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n https://<pikvm-ip>/api/switch/set_beacon\n</code></pre> Example output <pre><code>FIXME\n</code></pre>"},{"location":"api/#set-port-parameters","title":"Set port parameters","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/switch/set_port_params</code></p> <p>Description: Configures parameters for a specific port.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>port</code> float required Specifies the port number <code>0..19</code> <code>edid_id</code> string optional EDID identifier (allows default value) Alphanumeric string like <code>ca3d7114-79ca-47fc-80b4-b80ac63fc329</code> <code>dummy</code> boolean optional When enabled, the switch will pretend the host has a display attached Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <code>name</code> string optional String port name, none set by default Any combination of ASCII letters and numbers <code>atx_click_power_delay</code> float optional ATX power click delay value <code>0..10</code> <code>atx_click_power_long_delay</code> float optional ATX long power click delay value <code>0..10</code> <code>atx_click_reset_delay</code> float optional ATX reset click delay value <code>0..10</code> <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n 'https://<pikvm-ip>/api/switch/set_port_params?port=2&name=PORT3'\n</code></pre> Example output <pre><code>FIXME\n</code></pre>"},{"location":"api/#set-beacon-color","title":"Set beacon color","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/switch/set_colors</code></p> <p>Description: Sets the beacon color for the PiKVM Switch and all switches in the downlink (where applicable).</p> <p>Query parameters:</p> Parameter Type Optionality Description Acceptable values <code>beacon</code> hex required Sets color, brightness, and blink interval (ms) A valid hex value (see example below) <p>Example of use: Let's set the beacon to be orange at 75% of full brightness, blinking with an interval of 40ms.</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n -d \"FFA500:BF:0028\" \\\n https://<pikvm-ip>/api/switch/set_colors\n</code></pre> Example output <pre><code>FIXME\n</code></pre>"},{"location":"api/#reboot-the-device","title":"Reboot the device","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/switch/reset</code></p> <p>Description: Reboots the PiKVM Switch with an option to enter the reflashing mode after the reboot.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>unit</code> integer required Specifies the unit number <code>0..4</code> <code>bootloader</code> boolean optional Whether to enter the reflashing mode after rebooting, defaults to <code>false</code> Enable: <code>1</code>, <code>true</code>, or <code>yes</code>. Disable: <code>0</code>, <code>false</code>, or <code>no</code> <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n 'https://<pikvm-ip>/api/switch/reset?unit=0&bootloader=1'\n</code></pre> Example output <pre><code>FIXME\n</code></pre>"},{"location":"api/#create-a-new-edid-configuration","title":"Create a new EDID configuration","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/switch/edids/create</code></p> <p>Description: Creates a new EDID configuration from user-specified EDID name and data.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>name</code> string required EDID name Alphanumeric name (see example below) <code>data</code> string required EDID data Hexadecimal string (see example below) <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n 'https://<pikvm-ip>/api/switch/edids/create?name=Gigabyte-GA-H77-DS3H&data=00FFFFFFFFFFFF0052628888008888881C150103800000780AEE91A3544C99260F505425400001000100010001000100010001010101D51B0050500019400820B80080001000001EEC2C80A070381A403020350040442100001E000000FC0050492D4B564D20566964656F0A000000FD00323D0F2E0F0000000000000000014D02030400DE0D20A03058122030203400F0B400000018E01500A04000163030203400000000000018B41400A050D011203020350080D810000018AB22A0A050841A3030203600B00E1100001800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000045'\n</code></pre> Example output <pre><code>FIXME\n</code></pre>"},{"location":"api/#change-edid-configuration","title":"Change EDID configuration","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/switch/edids/change</code></p> <p>Description: Modifies an existing EDID configuration.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>id</code> string required EDID identifier Alphanumeric id (see example below) <code>name</code> string optional New EDID name Alphanumeric name (see example below) <code>data</code> string optional New EDID data Hexadecimal string (see example below) <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n 'https://<pikvm-ip>/api/switch/edids/change?id=ca3d7114-79ca-47fc-80b4-b80ac63fc329&name=Gigabyte-GA-H77-DS3H&data=00FFFFFFFFFFFF0052628888008888881C150103800000780AEE91A3544C99260F505425400001000100010001000100010001010101D51B0050500019400820B80080001000001EEC2C80A070381A403020350040442100001E000000FC0050492D4B564D20566964656F0A000000FD00323D0F2E0F0000000000000000014D02030400DE0D20A03058122030203400F0B400000018E01500A04000163030203400000000000018B41400A050D011203020350080D810000018AB22A0A050841A3030203600B00E1100001800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000045'\n</code></pre> Example output <pre><code>FIXME\n</code></pre>"},{"location":"api/#remove-edid-configuration","title":"Remove EDID configuration","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/switch/edids/remove</code></p> <p>Description: Deletes an EDID configuration.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>id</code> string required EDID identifier Alphanumeric id (see example below) <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n https://<pikvm-ip>/api/switch/edids/remove?id=ca3d7114-79ca-47fc-80b4-b80ac63fc329\n</code></pre> Example output <pre><code>FIXME\n</code></pre>"},{"location":"api/#atx-power-control","title":"ATX Power Control","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/switch/atx/power</code></p> <p>Description: Controls ATX power states for a specific port.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>port</code> float required Specifies the port number 0..19 <code>action</code> string required Power action <code>on</code> - Power on, <code>off</code> - Power off, <code>off_hard</code> - Hard power off, <code>reset_hard</code> - Hard reset <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n 'https://<pikvm-ip>/api/switch/atx/power?port=0&action=reset_hard'\n</code></pre> Example output <pre><code>FIXME\n</code></pre>"},{"location":"api/#atx-button-click","title":"ATX Button Click","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/switch/atx/click</code></p> <p>Description: Simulates ATX button clicks for a specific port.</p> <p>Query parameters: </p> Parameter Type Optionality Description Acceptable values <code>port</code> float required Specifies the port number <code>0..19</code> <code>button</code> string required Power action <code>power</code> - Power button click, <code>power_long</code> - Long power button press, <code>reset</code> - Reset button click <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -u admin:admin \\\n 'https://<pikvm-ip>/api/switch/atx/click?port=0&button=power_long'\n</code></pre> Example output <pre><code>FIXME\n</code></pre>"},{"location":"api/#redfish","title":"Redfish","text":"<p>The PiKVM Redfish API implements the industry-standard DMTF Redfish specification for remote server control. It allows you to monitor and control the power of the target system.</p> <p>Most endpoints require authentication using your PiKVM credentials. You can interact with the API using standard HTTP clients, <code>curl</code>, or the specialized Redfish tools.</p>"},{"location":"api/#root-service-discovery","title":"Root service discovery","text":"<p>Method: <code>GET</code></p> <p>Route: <code>/api/redfish/v1</code></p> <p>Description: Returns the basic Redfish service information and links to available resources. Doesn't require authentication.</p> <p>Query parameters: None.</p> <p>Example of use:</p> <pre><code>$ curl -k https://<pikvm-ip>/api/redfish/v1\n</code></pre> Example output <pre><code>{\n \"@odata.id\": \"/redfish/v1\",\n \"@odata.type\": \"#ServiceRoot.v1_6_0.ServiceRoot\",\n \"Id\": \"RootService\",\n \"Name\": \"Root Service\",\n \"RedfishVersion\": \"1.6.0\",\n \"Systems\": {\n \"@odata.id\": \"/redfish/v1/Systems\"\n }\n}\u23ce\n</code></pre>"},{"location":"api/#systems-collection","title":"Systems collection","text":"<p>Method: <code>GET</code></p> <p>Route: <code>/api/redfish/v1/Systems</code></p> <p>Description: Returns collection of available computer systems.</p> <p>Query parameters: None.</p> <p>Example of use:</p> <pre><code>$ curl -k -u admin:admin https://<pikvm-ip>/api/redfish/v1/Systems\n</code></pre> Example output <pre><code>{\n \"@odata.id\": \"/redfish/v1/Systems\",\n \"@odata.type\": \"#ComputerSystemCollection.ComputerSystemCollection\",\n \"Members\": [\n {\n \"@odata.id\": \"/redfish/v1/Systems/0\"\n }\n ],\n \"Members@odata.count\": 1,\n \"Name\": \"Computer System Collection\"\n}\u23ce\n</code></pre>"},{"location":"api/#individual-system-information","title":"Individual system information","text":"<p>Method: <code>GET</code></p> <p>Route: <code>/api/redfish/v1/Systems/0</code></p> <p>Description: Returns detailed information about the specific system, including power state, hostname, and available actions.</p> <p>Query parameters: None.</p> <p>Example of use:</p> <pre><code>$ curl -k -u admin:admin https://<pikvm-ip>/api/redfish/v1/Systems/0\n</code></pre> Example output <pre><code>{\n \"@odata.id\": \"/redfish/v1/Systems/0\",\n \"@odata.type\": \"#ComputerSystem.v1_10_0.ComputerSystem\",\n \"Actions\": {\n \"#ComputerSystem.Reset\": {\n \"ResetType@Redfish.AllowableValues\": [\n \"On\",\n \"ForceOff\",\n \"GracefulShutdown\",\n \"ForceRestart\",\n \"ForceOn\",\n \"PushPowerButton\"\n ],\n \"target\": \"/redfish/v1/Systems/0/Actions/ComputerSystem.Reset\"\n },\n \"#ComputerSystem.SetDefaultBootOrder\": {\n \"target\": \"/redfish/v1/Systems/0/Actions/ComputerSystem.SetDefaultBootOrder\"\n }\n },\n \"Boot\": {\n \"BootSourceOverrideEnabled\": \"Disabled\",\n \"BootSourceOverrideTarget\": null\n },\n \"HostName\": \"pikvm\",\n \"Id\": \"0\",\n \"PowerState\": \"Off\"\n}\u23ce\n</code></pre>"},{"location":"api/#system-configuration-update","title":"System configuration update","text":"<p>Method: <code>PATCH</code></p> <p>Route: <code>/api/redfish/v1/Systems/0</code></p> <p>Description: This handle was added to aid in scenarios where installing OKD (Kubernetes) using installer-provisioned infrastructure involves expecting two fields to be returned and the patch request to return a 204. Hence, this handle is currently a no-op that just returns success.</p> <p>Query parameters: None</p> <p>Example of use:</p> <pre><code>$ curl -k -X PATCH -u admin:admin https://<pikvm-ip>/api/redfish/v1/Systems/0\n</code></pre> <p>There will be zero output for this command by design.</p> <p>Responses:</p> Code Description 204 Returns success"},{"location":"api/#system-power-control","title":"System power control","text":"<p>Method: <code>POST</code></p> <p>Route: <code>/api/redfish/v1/Systems/0/Actions/ComputerSystem.Reset</code></p> <p>Description: Performs power control actions on the system.</p> <p>Query parameters: This handles expects JSON with <code>ResetType</code> in the request body and one of the following values:</p> <ul> <li><code>On</code> - Power on</li> <li><code>ForceOff</code> - Hard power off</li> <li><code>GracefulShutdown</code> - Graceful power off</li> <li><code>ForceRestart</code> - Hard reset</li> <li><code>ForceOn</code> - Force power on</li> <li><code>PushPowerButton</code> - Simulate power button press</li> </ul> <p>Example of use:</p> <pre><code>$ curl -k -X POST \\\n -H \"Content-Type: application/json\" \\\n -u admin:admin \\\n -d '{\"ResetType\": \"ForceRestart\"}' \\\n https://<pikvm-ip>/api/redfish/v1/Systems/0/Actions/ComputerSystem.Reset\n</code></pre> <p>There will be zero output for this command by design.</p> <p>Responses:</p> Code Description 204 Success 400 Invalid or missing ResetType"},{"location":"api/#misc","title":"Misc","text":""},{"location":"api/#get-prometheus-metrics","title":"Get Prometheus metrics","text":"<p>The <code>GET /api/export/prometheus/metrics</code> handle returns the Prometheus metrics. Also see here for details.</p> <pre><code>$ curl -k -u admin:admin https://<pikvm-ip>/api/export/prometheus/metrics\n</code></pre>"},{"location":"api/#video","title":"Video","text":"<p>PiKVM has 3 different ways to receive video and audio, depending on the device. This is also reflected in the web interface.</p> <p>| Mode |</p>"},{"location":"api/#get-raw-h264-video-stream","title":"Get raw H.264 video stream","text":""},{"location":"arduino_hid/","title":"Arduino HID","text":"<p>Legacy warning</p> <p>This page describes the legacy keyboard and mouse emulator used in old DIY builds. There is no point using it today because there is a more modern and better replacement for the new Pico HID. This one can also serve as an in-place compatible replacement for the Arduino HID in the old build.</p>"},{"location":"arduino_hid/#serial-hid","title":"Serial HID","text":"<p>PiKVM V3 note</p> <p>Use the SPI HID for V3. Otherwise, you won't be able to use the Serial console.</p>"},{"location":"arduino_hid/#usb-keyboard-and-mouse","title":"USB keyboard and mouse","text":"<ol> <li> Get some parts <ul> <li>Arduino Pro Micro (based on an ATMega32u4).</li> <li>Logic level shifter.</li> <li>1x NPN transistor (almost any NPN transistor: 2n2222 or similar).</li> <li>1x 390 Ohm resistor.</li> <li>A breadboard and wires.</li> </ul> </li> <li> Build the Arduino HID according to the scheme </li> <li> <p>Power up PiKVM and switch it to RW-mode using command <code>rw</code>.</p> </li> <li> <p>Add these lines to <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>kvmd:\n hid:\n type: serial\n reset_pin: 4\n device: /dev/kvmd-hid\n</code></pre> </li> <li> <p>Create file <code>/etc/udev/rules.d/99-kvmd-extra.rules</code>:</p> <pre><code>KERNEL==\"ttyAMA0\", SYMLINK+=\"kvmd-hid\"\n</code></pre> </li> <li> <p>Run <code>systemctl disable getty@ttyAMA0.service</code>.</p> </li> <li> <p>Remove <code>console=ttyAMA0,115200</code>or <code>console=serial0,115200</code> and <code>kgdboc=ttyAMA0,115200</code> or <code>kgdboc=serial0,115200</code> from <code>/boot/cmdline.txt</code>.</p> </li> <li> <p>Flash the Arduino HID.</p> </li> <li> <p>Perform <code>reboot</code>.</p> </li> </ol>"},{"location":"arduino_hid/#ps2-keyboard","title":"PS/2 keyboard","text":"<p>Using the PS/2 firmware currently have some limitations:</p> <ul> <li>The possibility of using the switchable USB HID is excluded.</li> <li>PS/2 mouse is not supported right now (but it will).</li> </ul> <p>Both of these problems will be solved in the nearest future and the two different firmware versions will be combined into one universal one.</p> <p>To select the PS/2 firmware, follow the instructions for the USB, but with one exception:</p> Before <code>make</code> you will need to edit file <code>platformio-avr.ini</code> <p>Open the file and find these lines:</p> <pre><code>[_common]\nbuild_flags =\n -DHID_PS2_KBD_CLOCK_PIN=7\n -DHID_PS2_KBD_DATA_PIN=5\n -DHID_USB_CHECK_ENDPOINT\n# ----- The default config with dynamic switching -----\n -DHID_DYNAMIC\n -DHID_WITH_USB\n -DHID_SET_USB_KBD\n -DHID_SET_USB_MOUSE_ABS\n# ----- PS2 keyboard only -----\n# -DHID_WITH_PS2\n# -DHID_SET_PS2_KBD\n# ----- PS2 keyboard + USB absolute mouse -----\n# -DHID_WITH_USB\n# -DHID_WITH_PS2\n# -DHID_SET_PS2_KBD\n# -DHID_SET_USB_MOUSE_ABS\n# ----- PS2 keyboard + USB relative mouse -----\n# -DHID_WITH_USB\n# -DHID_WITH_PS2\n# -DHID_SET_PS2_KBD\n# -DHID_SET_USB_MOUSE_REL\n</code></pre> <p>By default, the firmware works with USB HID and supports dynamic mode switching. You can choose one of the other modes by commenting some lines and uncommenting others. This example to use a USB mouse and PS/2 keyboard:</p> <pre><code>...\n# ----- The default config with dynamic switching -----\n# -DHID_DYNAMIC\n# -DHID_WITH_USB\n# -DHID_SET_USB_KBD\n# -DHID_SET_USB_MOUSE_ABS\n# ----- PS2 keyboard only -----\n...\n# ----- PS2 keyboard + USB absolute mouse -----\n -DHID_WITH_USB\n -DHID_WITH_PS2\n -DHID_SET_PS2_KBD\n -DHID_SET_USB_MOUSE_ABS\n# ----- PS2 keyboard + USB relative mouse -----\n...\n</code></pre> <p>Next, connect Arduino pins to the female PS/2 port of your motherboard. Choose the purple port. If your motherboard only have one port, it's probably universal and can be used either for the keyboard or for the mouse. Most likely, it is painted in two colors: green and purple. You can use it either.</p> Follow the diagram Female PS/2 port (front view) Pinout Arduino pin 7 <-> PS/2 CLOCKArduino pin 5 <-> PS/2 DATAArduino GND pin <-> PS/2 GND <p>Warning</p> <p>Connect VIN pin of Arduino to any Raspberry's 5v pin for PS/2 only device. But you don't need to connect the Arduino VIN pin if you connected USB (Arduino will get power through it).</p>"},{"location":"arduino_hid/#spi-hid","title":"SPI HID","text":"<p>Using an SPI connection, an Arduino Micro (not Pro) or compatible can be flashed from the Pi and used as an HID keyboard and mouse. Unlike UART, SPI does not share pins with Bluetooth on the Raspberry Pi so the Bluetooth radio does not need to be disabled.</p> <p></p> <p>Before powering either device, double-check the connections. The following should be wired from the Pi to either the level shifter or the Arduino. While the Arduino tolerates 3.3V logic input, 5V outputs from the Arduino can damage or destroy the Raspberry Pi and must not be connected directly to 3.3V GPIO pins directly.</p>"},{"location":"arduino_hid/#parts-list","title":"Parts list","text":"<p>There are very few parts needed besides the Raspberry Pi to build the solution. Some parts may be purchased with or without headers, if headers are not pre-soldered, it may be necessary to order some breakaway header strips and solder them to the boards prior to assembly unless the wires will be soldered directly to the boards.</p> <ul> <li>Raspberry Pi Zero W or Pi 4 are the most popular boards for this solution, pre-soldered headers recommended</li> <li>Arduino Micro (or compatible) microcontroller board with pre-soldered headers recommended</li> <li>Logic Level Converter. This may be RX/TX, Bidirectional, or Single Supply</li> <li>1x PNP transistor (2n2907 or equivalent). Note this is different from the one suggested in the Serial HID docs above, that is an NPN while this is a PNP.</li> <li>1x 390 ohm resistor</li> <li>Dupont wires (female to male pin) recommended for breadboard or other suitable means of making the connections</li> <li>Optional: Breakaway headers for the logic level converter</li> <li>Optional: Breadboard large enough to accommodate the parts</li> <li>Optional: Header pins for connection to a breadboard</li> </ul> <p>Note</p> <p>A smaller \"Pro Micro\" board is available in a 3.3V model but the SS connection (RX_LED) is not available as a separate pin or solderable hole. If using this board, a jumper wire can be soldered to the resistor for the RX_LED but there is risk of burning the resistor, the LED, the board, or other components in the process. Advantages of this board include not requiring a logic level converter and reduced breadboard or board space for building the solution.</p>"},{"location":"arduino_hid/#list-of-connections-to-be-made","title":"List of connections to be made","text":"<p>For the primary functionality, most connections are made using a 4-channel bidirectional level shifter</p> <ul> <li>Pi 3v3 to LV on the level shifter</li> <li>Pi Ground to LV GND</li> <li>Arduino GND to HV GND</li> <li>GPIO10 (MOSI) via the level shifter to MOSI on the Arduino</li> <li>GPIO9 (MISO) via the level shifter to MISO on the Arduino</li> <li>GPIO11 (SPIO_SCLK) via the level shifter to SCK on the Arduino</li> <li>GPIO7 (SPIO_CE1_N) via the level shifter to SS (or RX_LED) on the Arduino</li> </ul> <p>An additional circuit is used with a transistor to reset the HID for mode changes and for SPI programming as follows:</p> <ul> <li>GPIO25 to PNP base on transistor</li> <li>PNP emitter to ground</li> <li>PNP collector to RST on the Arduino</li> </ul> <p>Pictures of this setup are also available in full resolution for download to assist for both the Raspberry Pi and the Arduino board. A smaller version of the images has been included on this page and can be downloaded.</p> Raspberry Pi Closeup Breadboard with Arduino <p>Programming assumes the Arduino is powered via USB, either from the connected host or the Pi itself. If the USB is not connected, 5 V may be provided by the Raspberry Pi GPIO but should be disconnected prior to connecting USB to the Arduino's USB port. The Raspberry Pi does not have backcurrent protection, a circuit using one or more Schottky diodes can be built to OR power from multiple sources but it's easier and more cost effective to avoid conflict and voltage differences between power supplies by leaving the 5 V wire disconnected.</p>"},{"location":"arduino_hid/#preparing-the-installation-for-spi-devices-and-programming","title":"Preparing the installation for SPI devices and programming","text":"<p>As of the latest package release, the kvmd service supports SPI. It should be sufficient to ensure the packages are up-to-date with the latest release, the programmer is installed, and the SPI device overlay is loaded at boot.</p> <ul> <li>Switch the filesystem to read-write mode with <code>rw</code></li> <li>Add <code>dtoverlay=spi0-1cs</code> to <code>/boot/config.txt</code></li> <li>Perform <code>reboot</code>.</li> </ul>"},{"location":"arduino_hid/#flashing-the-arduino","title":"Flashing the Arduino","text":"<p>Instructions on flashing the Arduino can be found on the page Flash the Arduino HID.</p> <p>If programming fails, ensure the Arduino is powered and check the wiring again. If there is a misconfiguration, power off the Pi and the Arduino, correct the wiring, and try again. Note it is not recommended or required to supply 5V power from the Raspberry Pi if the Arduino is USB powered, if the issue appears to be power related it may be removed from the solution and replaced with a powered USB connection if it will aid in troubleshooting but check all other wires first to ensure there are no shorts.</p> <p>After you have double and triple-checked your wiring (in particular make sure the pins you are using on the Pi are correct, the documentation uses the GPIO pin labels, NOT the sequential pin numbers from 1-40. A good pinout reference is @Gadgetoid's version, you might try flashing the Arduino by holding down the RESET button on the chip while running <code>make install</code>. If this works, then at least you know your SPI wiring is correct.</p> <p>Wiring problems are a common issue but there could be other reasons for programming not to complete. While it is not possible to list every possible problem and solution here, there is an active user community with others familiar with the solution and willing to help.</p>"},{"location":"arduino_hid/#enable-the-spi-configuration-and-restart-kvmd","title":"Enable the SPI configuration and restart kvmd","text":"<p>Once the installation has completed, all that should remain is to add the following configuration to <code>/etc/kvmd/override.yaml</code> and restart the kvmd service. If the first line exists due to existing overrides, omit that line and either add or update the hid section as appropriate.</p> <pre><code>kvmd:\n hid:\n type: spi\n chip: 0\n bus: 0\n sw_cs_pin: 7\n reset_pin: 25\n reset_inverted: true\n</code></pre> <p>After saving the changes to <code>/etc/kvmd/override.yaml</code>, restart <code>kvmd</code> and clear your browser cache. The command to restart <code>kvmd</code> is</p> <pre><code># systemctl restart kvmd\n</code></pre> <p>If your device is still in read-write mode, <code>ro</code> will put the SD back in read-only mode.</p>"},{"location":"arduino_hid/#fixing-the-usb-absolute-mouse-on-windows-98","title":"Fixing the USB absolute mouse on Windows 98","text":"<p>Due to an ancient buggy driver, the USB absolute mouse on Windows 98 moves only within the upper-left quarter of the screen. To fix this, just recompile the firmware with uncommented flag <code>-DHID_WITH_USB_WIN98</code> in <code>platformio-avr.ini</code>.</p>"},{"location":"atx_board/","title":"ATX control board","text":"<p>To manage the power of your computer, you will need to install an ATX adapter board inside the case and connect it to the motherboard. There is a female to female ribbon cable that goes from the motherboard to the ATX adapter board and a male to female ribbon cable that goes from the adapter board to the front panel ribbon cable. There are two rows of pins on the ATX adapter board, it does not matter which ribbon cable is attached to which row. The columns must line up from the front panel through the ATX adapter to the motherboard.</p> <p>Apple's Mac computers are not ATX compatible as they lack the needed ATX headers, this is ONLY compatible with PC servers and desktops.</p>"},{"location":"atx_board/#detailed-instructions","title":"Detailed instructions","text":"<ol> <li> <p>Connect the rainbow wires to the board, one row to the front panel, one row to the motherboard. You can use either row for either cable. To secure the ATX board in the case you can optionally print the mounting plate for the PCI slot on a 3D-printer. Assemble everything like the pictures below. Secure wires in any convenient way (we used soft ties).</p> Example <p></p> <p></p> <p></p> </li> <li> <p>Find the pins on the motherboard responsible for connecting the buttons and LEDs of the front panel of the case. Usually wires and connectors on the motherboard have designations. If you're not sure, check the documentation on your motherboard.</p> Example <p></p> <p></p> </li> <li> <p>Place the ATX board nearby and, focusing on the labels and polarity (+ or -), connect the male pins to the female pin of the front panel wires. Be sure to align the labels and polarity (the polarity is indicated on the ATX board).</p> Example <p></p> </li> <li> <p>Repeat the procedure with the female pin of the ATX board by connecting them to the motherboard connector. Check the documentation on your motherboard to find out which pin on the motherboard goes to which pin on the ATX adapter. Sometimes it is printed on the motherboard.</p> Example <p></p> </li> <li> <p>Install the ATX board into the PCI slot of the case and fix it with a screw, or use a different mounting method at your discretion.</p> Example <p></p> <p></p> </li> <li> <p>Arrange the wires in a way that is convenient for you and fix them if necessary. Ensure the cables do not come into contact with any fans in your case.</p> Example <p></p> </li> <li> <p>Connect the ATX board to PiKVM using a straight Ethernet cable with 8 wires.</p> Example <p></p> </li> </ol>"},{"location":"atx_board/#pinout","title":"Pinout","text":"ATX RJ-45 pinout <p>The pinout of the RJ-45 connector is the same on the AT and ATX adapter.</p> <p></p> ATX LED wiring example <p></p>"},{"location":"audio/","title":"PiKVM V3+ two-way audio","text":"<p>Official PiKVM V3 and PiKVM V4 Mini/Plus devices have an exclusive audio transmission feature, including two-way communication with microphone directly in the browser.</p> <p>The incoming stream is captured from the target host via HDMI, the outgoing stream is transmitted to an emulated USB microphone. This brings the user experience of working with voice applications on the remote host even closer to the local one.</p> <p>Note</p> <ul> <li> <p>Audio does not work with DIY devices, either CSI or USB video dongles.</p> </li> <li> <p>VNC does not support audio, it only works in the Web UI in WebRTC mode.</p> </li> </ul>"},{"location":"audio/#speakers-incoming-audio","title":"Speakers (incoming audio)","text":"<ul> <li> <p>On PiKVM V4 Mini and Plus, this feature is enabled by default, unless you didn't disable it with custom EDID.</p> </li> <li> <p>On PiKVM V3, this is disabled for historical reasons so as not to break old user's configurations that was created before audio support was introduced.</p> Enabling audio on PiKVM V3 <ol> <li> <p>Make sure that you have not removed the audio jumpers (4) on the V3 HAT board and have not deleted or commented the <code>dtoverlay=tc358743-audio</code> line in <code>/boot/config.txt</code>. Return everything as it was, if you changed it.</p> </li> <li> <p>Update OS and reboot:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> </li> <li> <p>Enable the Basic Audio support in the EDID in the <code>/etc/kvmd/tc358743-edid.hex</code> and reboot the device again:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# kvmd-edidconf --set-audio=yes\n[root@pikvm ~]# reboot\n</code></pre> </li> </ol> </li> </ul> <p>The target host determines whether it is possible to output audio via HDMI. Each OS does this in its own way. In general, make sure that the audio output is HDMI in the mixer. PiKVM supports stereo mode with any standard bits and frequencies like 32/44.1/48 kHz with 16/24 bit.</p> <ul> <li> <p>Mac OS usually understands the priority of HDMI for audio output on its own, but you can specify this explicitly in the settings.</p> </li> <li> <p>Windows requires explicit specifying of the audio output device.</p> </li> <li> <p>In Linux, everything depends on the distribution you use. In ancient times, the audio required performing a ritual dance under the full Moon. For now, a working Pipewire or Pulseaudio most likely be enough. Just specify HDMI as the audio sink in the mixer.</p> </li> </ul> <p>To receive audio in the PiKVM Web UI, go to the System menu and switch the video mode to <code>WebRTC</code>. If everything is in order, the volume slider will appear. Set the volume to a non-zero value. The video stream will restart and you should start hearing sounds from the target host.</p> <p></p> <p>If the volume slider is set to zero, then PiKVM does not accept the audio stream to save traffic, while the target host will still assume that the audio output to HDMI is available.</p> <p>Besides, when the page is reloaded, the volume slider will be reset to zero. Saving this setting is not possible due to browser limitation that do not allow web pages to play audio immediately after opening without user activity to protect against annoying ads.</p>"},{"location":"audio/#microphone-outgoing-audio","title":"Microphone (outgoing audio)","text":"<p>PiKVM is able to emulate a USB microphone on the target host to transmit your speech from the browser to the host. This feature is disabled by default for backward compatibility reasons.</p> <p>USB limitations</p> <p>Each emulated USB device consumes a limited hardware resource called endpoints.</p> <p>Short info: by default, you can add only one additional USB device.</p> <p>To get more information about the endpoints, add more devices, and flexibly manage the configuration on the fly, see here.</p> Enabling USB Microphone <ol> <li> <p>Microphone requires speakers support so check the previous paragraph. Also perform OS updating and reboot if you didn't:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> </li> <li> <p>Switch filesystem to RW-mode:</p> <pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Add a config to <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>otg:\n devices:\n audio:\n enabled: true\n</code></pre> </li> <li> <p>Perform reboot:</p> <pre><code>[root@pikvm ~]# reboot\n</code></pre> </li> </ol> <p>To receive and transmit audio in the PiKVM Web UI, go to the System menu and switch the video mode to <code>WebRTC</code>. If everything is in order, the volume slider will appear with additional Microphone switch. Set the volume to a non-zero value, next switch the mic switch. Your browser will ask for permission to use the microphone, allow it.</p> <p></p> <p>The switch state will be saved in the browser's local settings. The microphone signal will not be transmitted if the volume level is zero.</p> <p>USB compatibility</p> <p>This feature is very new, so we don't know how much it affects the ability to interact with the BIOS and UEFI.</p> <p>Please try this and let us know if you have lost the ability to access the BIOS or boot OS from PiKVM Mass Storage after turning on the USB microphone.</p> <p>But even if this happens, don't worry. You can use the dynamic USB device control to temporarily turn off the microphone emulation.</p>"},{"location":"audio/#troubleshooting","title":"Troubleshooting","text":"<ul> <li> <p>If the browser does not play sound or does not show audio slider, try a different browser and/or incognito mode without extensions. Google Chrome works best.</p> </li> <li> <p>Check the log: <code>journalctl -u kvmd-janus</code>.</p> </li> <li> <p>If nothing helped, please report about the problem to our support</p> </li> </ul>"},{"location":"auth/","title":"Authentication","text":"<p>Info</p> <p>PiKVM supports additional authentication methods commonly used on enterprise networks. See here for detailed documentation.</p> <p>PiKVM comes with the following default passwords</p> <ul> <li> <p>Linux OS-level admin (SSH, console...):</p> <ul> <li>Username: <code>root</code></li> <li>Password: <code>root</code></li> </ul> </li> <li> <p>KVM user (Web Interface, API, VNC...):</p> <ul> <li>Username: <code>admin</code></li> <li>Password: <code>admin</code></li> <li>No 2FA code</li> </ul> </li> </ul> <p>They are two separate accounts with independent passwords.</p> <p>Don't forget to change BOTH passwords on the new device</p> <p>This page describes how to do this and enable two-factor authentication.</p> <p>The 2FA is also strongly recommended if you plan to expose PiKVM to the internet or use it in untrusted networks.</p> <p>In addition to the KVM user and Linux root, there are some other auth entities:</p> <ul> <li> <p>The OS user <code>kvmd-webterm</code> 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 <code>sudo</code> are also disabled. It is used only for the Web Terminal. These restrictions are set for security reasons.</p> </li> <li> <p>VNCAuth key - disabled by default.</p> </li> <li> <p>IPMI password - disabled by default.</p> </li> </ul>"},{"location":"auth/#root-access-in-the-web-terminal","title":"Root access in the Web Terminal","text":"<p>As mentioned above, the Web Terminal runs under user <code>kvmd-webterm</code> with disabled <code>sudo</code> and password access. However, most PiKVM administration commands require the <code>root</code> access. To obtain it in the Web Terminal, type <code>su -</code> and then enter the <code>root</code> user password:</p> <pre><code>[kvmd-webterm@pikvm ~]$ su -\n...\n[root@pikvm kvmd-webterm]#\n</code></pre> Step by step: Disabling the Web Terminal <p>Sometimes the actual owner of a PiKVM device and the user who is allowed to use it are different people. So you may want to disable console access from the Web UI. To do this, use the following:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# systemctl disable --now kvmd-webterm\n[root@pikvm ~]# ro\n</code></pre> <p>For your own access to PiKVM OS, you still have SSH.</p>"},{"location":"auth/#changing-the-linux-password","title":"Changing the Linux password","text":"<pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# passwd root\n[root@pikvm ~]# ro\n</code></pre>"},{"location":"auth/#changing-the-kvm-password","title":"Changing the KVM password","text":"<p>This password is used, among the Web UI login, to access the API, VNC (if enabled) and other functions that do not concern the OS shell.</p> <p>By default, an authentication method similar to Apache Server is configured: users and passwords are stored encrypted in the <code>/etc/kvmd/htpasswd</code> file. To manage them, there is a utility <code>kvmd-htpasswd</code>.</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# kvmd-htpasswd set admin\n[root@pikvm ~]# ro\n</code></pre> <p>The <code>admin</code> is a name of a default user.</p> Step by step: Add KVM users <p>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:</p> <pre><code>[root@pikvm ~]# kvmd-htpasswd add <user> # Add a new user with password\n[root@pikvm ~]# kvmd-htpasswd list # Show the list of users\n[root@pikvm ~]# kvmd-htpasswd del <user> # Removes/deletes a user\n</code></pre> <p>At the moment there is no way to create any ACL for different KVM users.</p>"},{"location":"auth/#two-factor-authentication","title":"Two-factor authentication","text":"<p>Two-factor authentication (2FA) is a new method of strengthening the protection of PiKVM, available since <code>KVM >= 3.196</code>. It is strongly recommended to enable it if you expose the PiKVM in the big and scary Internet.</p> <p>Warning</p> <p>Please note that 2FA does not concern the Linux OS access for the <code>root</code> user, so take care of a strong password for it for SSH access (or setup the key access).</p> Step by step: Enabling 2FA on PiKVM <ol> <li> <p>Update OS and reboot:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> </li> <li> <p>Make sure that NTP is running otherwise you will not be able to access (<code>timedatectl</code> command). The timezone doesn't matter.</p> </li> <li> <p>Install the Google Authenticator app to your mobile device (iOS, Android). It will generate one-time access codes.</p> </li> <li> <p>Create a secret for one-time codes on PiKVM:</p> </li> </ol> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# kvmd-totp init\n[root@pikvm ~]# ro\n</code></pre> <ol> <li> <p>Run the Google Authenticator and scan the QR code.</p> </li> <li> <p>Now, on the PiKVM login page, you will need to add 6 digits to the <code>2FA code</code> field.</p> </li> </ol> <p>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.</p> <p>Note</p> <p>With 2FA for API or VNC authentication (except VNCAuth mode), you will need to append the one-time code to the password without spaces. That is, if the password is <code>foobar</code> and the code is <code>123456</code>, then you need to use <code>foobar123456</code> as the password.</p> <p>To view the current QR code of the secret use command <code>kvmd-totp show</code>.</p> <p>To disable 2FA and remove the secret, use command <code>kvmd-totp del</code>.</p>"},{"location":"auth/#session-expiration","title":"Session expiration","text":"<p>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 <code>kvmd</code> 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.</p> <p>Note if you click the Logout button on the main page, it will log out all sessions of this user in all browsers.</p> <p>Long-lived connections</p> <p>PiKVM actively uses websockets and long-lived HTTP connections for video streaming.</p> <p>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.</p> <p>In the future, we plan to add immediate termination of expired connections.</p> Step by step: Set a global session expiration limit <p>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).</p> <ol> <li> <p>Switch filesystem to read-write mode:</p> <pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Edit the file <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>kvmd:\n auth:\n expire: 21600 # 21600 seconds is 6 shours\n</code></pre> </li> <li> <p>Restart the <code>kvmd</code> service and make sure that the limit is applied:</p> <pre><code>[root@pikvm ~]# systemctl restart kvmd\n[root@pikvm ~]# journalctl -u kvmd -g 'Maximum user session'\n... INFO --- Maximum user session time is limited: 6:00:00\n</code></pre> </li> <li> <p>Switch filesystem to read-only mode back:</p> <pre><code>[root@pikvm ~]# ro\n</code></pre> </li> </ol>"},{"location":"auth/#disabling-authentication","title":"Disabling authentication","text":"<p>If necessary, you can disable authentication for KVM access (Web UI, VNC, etc. except SSH).</p> <p>Warning</p> <p>Don't do this in untrusted networks, because you can give a potential attacker access to your target machine.</p> <p>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.</p> Step by step: Disabling authentication <ol> <li> <p>Switch filesystem to read-write mode:</p> <pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Edit the file <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>kvmd:\n auth:\n enabled: false\n</code></pre> </li> <li> <p>Restart <code>kvmd</code>, optionally disable web terminal switch filesystem to read-only mode:</p> <pre><code>[root@pikvm ~]# systemctl restart kvmd\n[root@pikvm ~]# systemctl disable --now kvmd-webterm # Optional if you have SSH access\n[root@pikvm ~]# ro\n</code></pre> </li> </ol>"},{"location":"auth_advanced/","title":"Advanced authentication","text":""},{"location":"auth_advanced/#advanced-authentication-methods","title":"Advanced authentication methods","text":"<p>PiKVM provides flexible authentication options to integrate with your existing security infrastructure. By default, PiKVM uses a simple file-based authentication system (htpasswd), but it can be configured to authenticate users against external systems for enterprise environments.</p> <p>This guide covers the configuration of PiKVM's authentication methods. All external authentication servers (LDAP, RADIUS, HTTP auth servers) are assumed to be already configured and accessible from your PiKVM device.</p> <p>Warning</p> <p>This is advanced material. Before you try setting this up, we recommend (re)familirizing yourself with the documentation on configuration and taking another look at the cheat sheet.</p> <p>Whenever you customize authentication, restart kvmd:</p> <pre><code>$ systemctl restart kvmd\n</code></pre>"},{"location":"auth_advanced/#overview","title":"Overview","text":"<p>PiKVM supports the following authentication methods through its pluggable authentication system:</p> <ul> <li>HTTP Authentication: External HTTP-based authentication service integration. PiKVM forwards authentication requests to a custom HTTP API endpoint.</li> <li>PAM (Pluggable Authentication Modules): Integration with Linux PAM system, allowing authentication against system users, LDAP, Active Directory, and other PAM-supported backends.</li> <li>LDAP (Lightweight Directory Access Protocol): Direct LDAP authentication against directory servers like Active Directory, OpenLDAP, or other LDAP-compatible systems.</li> <li>RADIUS (Remote Authentication Dial-In User Service): Authentication against RADIUS servers, commonly used in enterprise networks with support for multi-factor authentication.</li> <li>Unix Socket Credentials: Process-based authentication using Unix domain sockets with credential passing for local system integration.</li> </ul>"},{"location":"auth_advanced/#authentication-methods-comparison","title":"Authentication methods comparison","text":"Method Best For Complexity External Dependencies HTTP Auth Custom authentication systems, microservices Low HTTP auth server PAM System integration, existing PAM setups Medium PAM modules LDAP Active Directory, directory services Medium LDAP server RADIUS Enterprise networks, centralized auth Medium RADIUS server Unix Socket Credentials Local process integration, containers Low Local processes <p>2FA/TOTP is always available works locally and is compatible with all the methods listed here.</p>"},{"location":"auth_advanced/#basic-configuration","title":"Basic configuration","text":"<p>You can customize authentication and authorization with <code>/etc/kvmd/override.yaml</code>. If you want to keep the configuration modular, create and edit <code>/etc/kvmd/override.d/9999-auth.yaml</code> instead. You can use any 4-digit number prepending the filename.</p> <p>Here are the keys you need to know about.</p>"},{"location":"auth_advanced/#enabled","title":"<code>enabled</code>","text":"<p>This is a global authentication switch, enabled by default:</p> <pre><code>kvmd:\n auth:\n enabled: true\n</code></pre> <p>Setting it to <code>false</code> will disable all authentication, regardless of the methods you configured.</p>"},{"location":"auth_advanced/#expire","title":"<code>expire</code>","text":"<p>This key sets the cookie expiration time measured in seconds. Please see this part of the documentation for details.</p> <p>In this example, the cookie will expire in 10 minutes:</p> <pre><code>kvmd:\n auth:\n expire: 600\n</code></pre>"},{"location":"auth_advanced/#usc","title":"<code>usc</code>","text":"<p>This group of keys is in charge for basic configuration of Unix Socket Credentials:</p> <ul> <li><code>users</code>: this key is for listing valid usernames</li> <li><code>groups</code>: this key is for listing valid user groups</li> </ul> <p>Here is a configuration example:</p> <pre><code>kvmd:\n auth:\n usc:\n users: [cyril,jane,mike,sheryl]\n</code></pre>"},{"location":"auth_advanced/#internal-and-external","title":"<code>internal</code> and <code>external</code>","text":"<p><code>internal</code> is the authentication method that is applied first, <code>external</code> is used for external services. Note that there is no fallback from <code>external</code> to <code>internal</code>.</p> <p><code>kvmd</code> defaults to using <code>htpasswd</code> as the internal method and doesn't set the external one:</p> <pre><code>kvmd:\n auth:\n internal:\n type: htpasswd\n force_users: []\n file: /etc/kvmd/htpasswd\n\n external:\n type: ''\n</code></pre> <p>The recommended configuration is either <code>htpasswd</code> or <code>pam</code> as the internal authentication method and any other method as the external one. In that case, do the following:</p> <ol> <li>Keep the default <code>admin</code> user.</li> <li>Change its password to a random 30 characters long one (e.g., use <code>pwgen -y 30</code>).</li> <li>Keep <code>htpasswd</code> as the internal method.</li> <li>Use <code>ldap</code> or any other method as the external one, depending on your use case.</li> </ol> <p>Here is a configuration example:</p> <pre><code>kvmd:\n auth:\n internal:\n #type: htpasswd\n force_users: [admin]\n #file: /etc/kvmd/htpasswd\n\n external:\n type: ldap\n ...\n</code></pre> <p>Type and file are defaults in the above example.</p> <p>However, if your LDAP server has a guaranteed high availability, you can use <code>ldap</code> as an internal authentication method and discard the external authentication method entirely.</p>"},{"location":"auth_advanced/#totp","title":"<code>totp</code>","text":"<p>You can pass the secret file along with the password. The secret file location defaults to <code>/etc/kvmd/totp.secret</code>. See here for more information on 2FA authenticaion on PiKVM.</p>"},{"location":"auth_advanced/#http-authentication","title":"HTTP authentication","text":"<p>The HTTP authentication plugin delegates credential validation to an external HTTP/HTTPS endpoint. This enables integration with custom authentication services and third-party identity providers.</p> <p>The plugin sends authentication requests as JSON POST requests to a configurable URL and grants access when the endpoint returns <code>HTTP 200 OK</code>. This approach allows you to implement complex authentication logic without modifying PiKVM's core code.</p> <p>For an example of using HTTP authentication, please see this GitHub repository.</p>"},{"location":"auth_advanced/#parameters","title":"Parameters","text":""},{"location":"auth_advanced/#url","title":"<code>url</code>","text":"<p>The URL of the external HTTP authentication endpoint. PiKVM will send POST requests to this URL to authenticate users.</p> <ul> <li>Type: String (URL)</li> <li>Default value: <code>\"http://localhost/auth\"</code></li> <li>Examples:<ul> <li><code>http://localhost:8080/api/auth</code> - Local authentication service</li> <li><code>https://auth.example.com/validate</code> - Remote HTTPS endpoint</li> <li><code>http://10.0.0.100/auth</code> - Internal network service</li> </ul> </li> <li>Note: The endpoint must accept POST requests with JSON payload.</li> </ul>"},{"location":"auth_advanced/#verify","title":"<code>verify</code>","text":"<p>Controls SSL/TLS certificate verification when using HTTPS URLs.</p> <ul> <li>Type: Boolean</li> <li>Default value: <code>true</code></li> <li>Acceptable values: <code>true</code> and <code>false</code></li> <li>Behavior:<ul> <li><code>true</code>: Verifies the server's SSL/TLS certificate (recommended for production)</li> <li><code>false</code>: Disables certificate verification (useful for self-signed certificates or testing)</li> </ul> </li> <li>Note: Only applies when using <code>https://</code> URLs. When set to <code>false</code>, SSL is completely disabled.</li> </ul>"},{"location":"auth_advanced/#secret","title":"<code>secret</code>","text":"<p>An optional shared secret token sent in the authentication request JSON payload. This can be used by the authentication endpoint to verify that requests are coming from an authorized PiKVM instance.</p> <ul> <li>Type: String</li> <li>Default value: <code>\"\"</code> (empty string)</li> <li>Use Case: Provides an additional layer of security to prevent unauthorized services from using your authentication endpoint.</li> <li>Note: The secret is sent as part of the JSON body, not as a header.</li> </ul>"},{"location":"auth_advanced/#user","title":"<code>user</code>","text":"<p>Optional username for HTTP basic authentication to the authentication endpoint itself. Used when the authentication service requires its own authentication.</p> <ul> <li>Type: String</li> <li>Default value: <code>\"\"</code> (empty string)</li> <li>Note: Works in combination with the <code>passwd</code> parameter. If <code>user</code> is empty, Basic Auth is not used.</li> </ul>"},{"location":"auth_advanced/#passwd","title":"<code>passwd</code>","text":"<p>Optional password for HTTP basic authentication to the authentication endpoint. Used in combination with the <code>user</code> parameter.</p> <ul> <li>Type: String</li> <li>Default value: <code>\"\"</code> (empty string)</li> <li>Note: Only used when <code>user</code> is configured.</li> </ul>"},{"location":"auth_advanced/#timeout","title":"<code>timeout</code>","text":"<p>The total timeout for the HTTP authentication request. If the authentication endpoint doesn't respond within this time, the authentication attempt fails.</p> <ul> <li>Type: Float (\u2265 0.1)</li> <li>Default value: <code>5.0</code></li> <li>Unit: Seconds</li> <li>Considerations:</li> <li>Network latency to the authentication endpoint</li> <li>Processing time on the authentication server</li> <li>Balance between security (shorter timeout) and reliability (longer timeout)</li> </ul>"},{"location":"auth_advanced/#authentication-flow","title":"Authentication flow","text":"<ol> <li>Session Creation: Create or reuse an HTTP client session configured with:</li> <li>SSL verification settings (based on <code>verify</code> parameter)</li> <li> <p>Basic Authentication credentials (if <code>user</code> is configured)</p> </li> <li> <p>Request Construction: Create a POST request to the configured <code>url</code> with:</p> <ul> <li>Method: POST</li> <li>Content-Type: application/json</li> <li>Headers:<ul> <li><code>User-Agent</code>: \"KVMD\" with version information</li> <li><code>X-KVMD-User</code>: The username being authenticated</li> </ul> </li> <li>JSON Body: <pre><code> {\n \"user\": \"username\",\n \"passwd\": \"password\",\n \"secret\": \"shared_secret\"\n }\n</code></pre></li> </ul> </li> <li> <p>Request Transmission: Send the HTTP request to the authentication endpoint</p> </li> <li> <p>Response Processing: Wait for response (up to timeout period)</p> </li> <li> <p>Authorization Decision: Grant access if:</p> <ul> <li>The response is received within the timeout</li> <li>The HTTP status code is 200 (OK)</li> <li>Any other status code (including 401, 403, 404, etc.) results in authentication failure</li> </ul> </li> </ol>"},{"location":"auth_advanced/#authentication-endpoint-requirements","title":"Authentication endpoint requirements","text":"<ol> <li> <p>Accept POST requests with JSON payload</p> </li> <li> <p>Parse the JSON body containing:</p> <ul> <li><code>user</code>: The username attempting to authenticate</li> <li><code>passwd</code>: The password provided by the user</li> <li><code>secret</code>: The shared secret (if configured)</li> </ul> </li> <li> <p>Validate credentials according to your authentication logic</p> </li> <li> <p>Return appropriate HTTP status codes:</p> <ul> <li><code>200 OK</code>: Authentication successful</li> <li><code>401 Unauthorized</code>: Invalid credentials</li> <li><code>403 Forbidden</code>: User not authorized</li> <li>Any other status code: Authentication failure</li> </ul> </li> </ol>"},{"location":"auth_advanced/#basic-configuration-example","title":"Basic configuration example","text":"<pre><code>kvmd:\n auth:\n internal:\n type: http\n url: http://localhost:8080/api/auth\n verify: true\n secret: \"\"\n user: \"\"\n passwd: \"\"\n timeout: 5.0\n</code></pre>"},{"location":"auth_advanced/#pam-plugin-configuration","title":"PAM plugin configuration","text":"<p>The PAM authentication plugin leverages Linux's Pluggable Authentication Modules framework to authenticate users against the same mechanisms used by the underlying operating system. </p> <p>This plugin supports any authentication backend configured through PAM, including local user accounts, SSSD for Active Directory, LDAP, Kerberos, or any other PAM-compatible service.</p> <p>It also includes access control features such as username whitelists/blacklists and UID-based filtering to prevent system accounts from authenticating.</p>"},{"location":"auth_advanced/#parameters_1","title":"Parameters","text":""},{"location":"auth_advanced/#service","title":"<code>service</code>","text":"<p>Specifies the PAM service name to use for authentication. This corresponds to a configuration file in <code>/etc/pam.d/</code> on the system. The default value <code>login</code> uses the standard PAM login service configuration.</p> <ul> <li>Type: String</li> <li>Default: <code>\"login\"</code></li> </ul>"},{"location":"auth_advanced/#allow_users","title":"<code>allow_users</code>","text":"<p>A whitelist of usernames that are explicitly allowed to authenticate. If the list is empty, this check is bypassed, all users are allowed and are subject to other checks.</p> <ul> <li>Type: List of strings</li> <li>Default: <code>[]</code> (empty list)</li> <li>Behavior: When a user attempts to authenticate:<ul> <li>If the list is not empty and the user is not in the list, authentication fails with an error message.</li> </ul> </li> </ul>"},{"location":"auth_advanced/#deny_users","title":"<code>deny_users</code>","text":"<p>A blacklist of usernames that are explicitly denied authentication. Users in this list cannot authenticate regardless of their credentials.</p> <ul> <li>Type: List of strings</li> <li>Default: <code>[]</code> (empty list)</li> <li>Behavior: When a user attempts to authenticate:<ul> <li>If the user is in the deny list, authentication fails with an error message.</li> </ul> </li> </ul>"},{"location":"auth_advanced/#allow_uids_at","title":"<code>allow_uids_at</code>","text":"<p>Specifies a minimum UID (User ID) threshold for authentication. Only users with UIDs greater than or equal to this value are allowed to authenticate. A value of <code>0</code> disables this check.</p> <ul> <li>Type: Integer (\u2265 0)</li> <li>Default: <code>0</code></li> <li>Behavior: When set to a value greater than 0:<ul> <li>The plugin retrieves the UID of the authenticating user from the system</li> <li>If the user's UID is less than the configured threshold, authentication fails</li> <li>This is useful for preventing system users (typically UIDs < 1000) from authenticating</li> </ul> </li> <li>Use case: Commonly used to restrict authentication to regular user accounts and prevent service accounts or system users from accessing the interface.</li> </ul>"},{"location":"auth_advanced/#authentication-flow_1","title":"Authentication flow","text":"<p>The authentication process follows the steps in the following order:</p> <ol> <li>Allow list check: If <code>allow_users</code> is configured, verify the user is in the list</li> <li>Deny list check: If <code>deny_users</code> is configured, verify the user is not in the list</li> <li>UID threshold check: If <code>allow_uids_at</code> > 0, verify the user's UID meets the minimum threshold</li> <li>PAM authentication: Finally, authenticate the user credentials against the specified PAM service</li> </ol> <p>All checks must pass for authentication to succeed.</p>"},{"location":"auth_advanced/#basic-configuration-example_1","title":"Basic configuration example","text":"<pre><code>kvmd:\n auth:\n internal:\n type: pam\n service: login\n allow_users: [admin, operator, viewer]\n deny_users: [guest, test]\n allow_uids_at: 1000\n</code></pre> <p>This configuration would:</p> <ul> <li>Use the standard \"login\" PAM service</li> <li>Only allow users named <code>admin</code>, <code>operator</code>, or <code>viewer</code></li> <li>Explicitly deny users named <code>guest</code> or <code>test</code></li> <li>Only allow users with UID \u2265 1000 (excluding most system accounts)</li> </ul>"},{"location":"auth_advanced/#advanced-pam-configuration-examples","title":"Advanced PAM configuration examples","text":"<ul> <li>Multiple PAM modules (stacking)</li> <li>Time-based restrictions (pam_time)</li> <li>Access control lists (pam_access)</li> <li>Account lockout policies</li> </ul>"},{"location":"auth_advanced/#ldap-plugin-configuration","title":"LDAP plugin configuration","text":"<p>The LDAP authentication plugin integrates with LDAP directories and Active Directory environments for centralized user management.</p> <p>The plugin authenticates users through LDAP bind operations and validates group membership to enforce authorization policies, so that only users in specified security groups can access the KVM interface.</p> <p>It supports both standard LDAP and secure LDAPS connections with configurable certificate verification, optional domain suffix auto-appending, and timeout settings.</p>"},{"location":"auth_advanced/#parameters_2","title":"Parameters","text":""},{"location":"auth_advanced/#url_1","title":"<code>url</code>","text":"<p>The LDAP server URL, should be in either <code>ldap://hostname:port</code> or the <code>ldaps://hostname:port</code> format.</p> <ul> <li>Type: String (non-empty)</li> <li>Default: <code>\"\"</code> (empty string, must be configured)</li> <li>Required: Yes</li> <li>Examples:</li> <li><code>ldap://dc.example.com:389</code> - Standard LDAP</li> <li><code>ldaps://dc.example.com:636</code> - LDAP over SSL/TLS</li> <li>Note: When using <code>ldaps://</code>, the plugin automatically configures TLS options.</li> </ul>"},{"location":"auth_advanced/#verify_1","title":"<code>verify</code>","text":"<p>Controls SSL/TLS certificate verification when using LDAPS connections.</p> <ul> <li>Type: Boolean</li> <li>Default: <code>True</code></li> <li>Behavior:</li> <li><code>true</code>: Verifies the server's SSL/TLS certificate (recommended for production)</li> <li><code>false</code>: Disables certificate verification (useful for self-signed certificates or testing)</li> <li>Note: Only applies when using <code>ldaps://</code> URLs.</li> </ul>"},{"location":"auth_advanced/#base","title":"<code>base</code>","text":"<p>The LDAP base DN (Distinguished Name) where user searches will start. This defines the starting point in the directory tree for user lookups.</p> <ul> <li>Type: String (non-empty)</li> <li>Default: <code>\"\"</code> (empty string, must be configured)</li> <li>Required: Yes</li> <li>Example: <code>DC=example,DC=com</code> or <code>OU=Users,DC=example,DC=com</code></li> </ul>"},{"location":"auth_advanced/#group","title":"<code>group</code>","text":"<p>The full DN of the LDAP/Active Directory group that users must be members of to authenticate successfully. Only users who are members of this group will be granted access.</p> <ul> <li>Type: String (non-empty)</li> <li>Default: <code>\"\"</code> (empty string, must be configured)</li> <li>Required: Yes</li> <li>Example: <code>CN=PiKVM-Users,OU=Groups,DC=example,DC=com</code></li> <li>Note: The plugin checks for exact group membership using the <code>memberOf</code> attribute.</li> </ul>"},{"location":"auth_advanced/#user_domain","title":"<code>user_domain</code>","text":"<p>An optional domain suffix to append to usernames during authentication. When configured, the username will be transformed to <code>username@user_domain</code> format (User Principal Name format).</p> <ul> <li>Type: String</li> <li>Default: <code>\"\"</code> (empty string)</li> <li>Examples:</li> <li>If set to <code>example.com</code> and user enters <code>john</code>, the plugin authenticates as <code>john@example.com</code></li> <li>If empty, the username is used as-is</li> <li>Use Case: Simplifies login by allowing users to enter just their username instead of the full UPN.</li> </ul>"},{"location":"auth_advanced/#timeout_1","title":"<code>timeout</code>","text":"<p>Timeout value for LDAP operations (bind and search). If the LDAP server doesn't respond within this time, the operation fails.</p> <ul> <li>Type: Integer (\u2265 1)</li> <li>Default: <code>5</code></li> <li>Unit: Seconds</li> <li>Recommendation: Adjust based on network latency and LDAP server performance.</li> </ul>"},{"location":"auth_advanced/#authentication-flow_2","title":"Authentication flow","text":"<p>The authentication process works as follows:</p> <ol> <li> <p>Username transformation: If <code>user_domain</code> is configured, append it to the username (e.g., <code>user</code> > <code>user@example.com</code>).</p> </li> <li> <p>Connection initialization: Connect to the LDAP server specified in <code>url</code>.</p> </li> <li> <p>TLS configuration: If using <code>ldaps://</code>, configure TLS settings based on the <code>verify</code> parameter.</p> </li> <li> <p>Bind attempt: Attempt to bind (authenticate) to the LDAP server using the username and password.</p> </li> <li> <p>Group membership search: Search for the user in the directory and verify they are a member of the specified <code>group</code>.</p> </li> <li> <p>Authorization decision: Grant access only if:</p> <ul> <li>The bind (authentication) succeeds</li> <li>The user is found in the directory under the specified <code>base</code></li> <li>The user is a member of the specified <code>group</code></li> </ul> </li> </ol>"},{"location":"auth_advanced/#basic-configuration-example_2","title":"Basic configuration example","text":"<pre><code>kvmd:\n auth:\n internal:\n type: ldap:\n url: ldaps://dc.example.com:636\n verify: true\n base: DC=example,DC=com\n group: CN=PiKVM-Admins,OU=Security Groups,DC=example,DC=com\n user_domain: example.com\n timeout: 5\n</code></pre>"},{"location":"auth_advanced/#configuration-with-a-self-signed-certificate","title":"Configuration with a self-signed certificate","text":"<pre><code>kvmd:\n auth:\n internal:\n type: ldap:\n url: ldaps://dc.internal.local:636\n verify: false\n base: OU=Users,DC=internal,DC=local\n group: CN=KVM-Users,OU=Groups,DC=internal,DC=local\n user_domain: internal.local\n timeout: 10\n</code></pre>"},{"location":"auth_advanced/#configuration-for-standard-ldap-non-ssl","title":"Configuration for standard LDAP (non-SSL)","text":"<pre><code>kvmd:\n auth:\n internal:\n type: ldap\n url: ldap://ldap.example.com:389\n verify: true\n base: DC=example,DC=com\n group: CN=RemoteAccess,DC=example,DC=com\n user_domain: \"\"\n timeout: 5\n</code></pre>"},{"location":"auth_advanced/#radius-plugin-configuration","title":"RADIUS plugin configuration","text":"<p>This plugin enables authentication against RADIUS (Remote Authentication Dial-In User Service) servers. Supported features:</p> <ul> <li>Standard RADIUS Access-Request/Access-Accept protocol over UDP.</li> <li>Password encryption using the RADIUS shared secret mechanism.</li> <li>Supports any RFC 2865-compliant server (FreeRADIUS, Microsoft NPS, Cisco ISE).</li> </ul>"},{"location":"auth_advanced/#parameters_3","title":"Parameters","text":""},{"location":"auth_advanced/#host","title":"<code>host</code>","text":"<p>The hostname or IP address of the RADIUS authentication server.</p> <ul> <li>Type: String (IP address or hostname)</li> <li>Default: <code>\"localhost\"</code></li> <li>Examples:<ul> <li><code>192.168.1.100</code> - IP address</li> <li><code>radius.example.com</code> - Hostname</li> <li><code>localhost</code> - Local RADIUS server</li> </ul> </li> </ul>"},{"location":"auth_advanced/#port","title":"<code>port</code>","text":"<p>The UDP port number on which the RADIUS server is listening for authentication requests.</p> <ul> <li>Type: Integer (valid port number: 1-65535)</li> <li>Default: <code>1812</code></li> <li>Standard ports:<ul> <li><code>1812</code> - Standard RADIUS authentication port (recommended, RFC 2865)</li> <li><code>1645</code> - Legacy RADIUS authentication port (deprecated but sometimes still used)</li> </ul> </li> </ul>"},{"location":"auth_advanced/#secret_1","title":"<code>secret</code>","text":"<p>The shared secret (password) used to encrypt communication between the PiKVM client and the RADIUS server. This must match the shared secret configured on the RADIUS server for this client.</p> <ul> <li>Type: String</li> <li>Default: <code>\"\"</code> (empty string, must be configured)</li> <li>Required: Yes</li> <li>Security: <ul> <li>This value should be kept confidential and stored securely</li> <li>Use a strong, random secret</li> <li>The secret is used for encrypting user passwords in transit and authenticating packets</li> </ul> </li> <li>Note: The secret is encoded as ASCII before use.</li> </ul>"},{"location":"auth_advanced/#timeout_2","title":"<code>timeout</code>","text":"<p>The timeout value for RADIUS authentication requests. If the RADIUS server doesn't respond within this time, the authentication attempt fails.</p> <ul> <li>Type: Integer (\u2265 1)</li> <li>Default: <code>5</code></li> <li>Unit: Seconds</li> <li>Considerations:<ul> <li>Network latency between PiKVM and RADIUS server</li> <li>RADIUS server load and response time</li> <li>Consider increasing for servers on slow or distant networks</li> </ul> </li> </ul>"},{"location":"auth_advanced/#authentication-flow_3","title":"Authentication flow","text":"<p>The authentication process works as follows:</p> <ol> <li> <p>Dictionary loading: Load the RADIUS attribute dictionary (embedded FreeRADIUS dictionary format)</p> </li> <li> <p>Client creation: Create a RADIUS client configured with:</p> <ul> <li>Server hostname/IP</li> <li>Authentication port</li> <li>Shared secret (encrypted)</li> <li>Timeout value</li> </ul> </li> <li> <p>Packet creation: Create a RADIUS Access-Request packet containing:</p> <ul> <li>Username (<code>User-Name</code> attribute)</li> <li>Encrypted password (<code>User-Password</code> attribute, encrypted using the shared secret)</li> </ul> </li> <li> <p>Request transmission: Send the authentication packet to the RADIUS server via UDP</p> </li> <li> <p>Response processing: Wait for response (up to timeout period)</p> </li> <li> <p>Authorization decision: Grant access if:</p> <ul> <li>A response is received within the timeout</li> <li>The response code is <code>AccessAccept</code> (code 2)</li> </ul> </li> </ol>"},{"location":"auth_advanced/#basic-configuration-example_3","title":"Basic Configuration Example","text":"<pre><code>kvmd:\n auth:\n radius:\n host: radius.example.com\n port: 1812\n secret: \"MySharedSecret123\"\n timeout: 5\n</code></pre>"},{"location":"auth_advanced/#unix-socket-credentials-configuration","title":"Unix Socket Credentials configuration","text":"<p>USC is a built-in mehanism that is primarily used for authorizing local PiKVM microservices, such as VNC \u0438 IPMI. You can use this method to execute scripts that use the local KVMD API. </p> <p>For example, the following command will authenticate a script with a unix socket and return PiKVM status:</p> <pre><code>[root@pikvm ~]# sudo -u monitoring curl --unix-socket /run/kvmd/kvmd.sock http://localhost/info\n</code></pre> <p>Note that there is no <code>api</code> prefix used when accessing the API. The prefix is added by KVMD-Nginx when exposing the socket on ports 80 and 443.</p> <p>For scheduling the execution, you can use either systemd-timers (available by default and recommended) or cron (not installed by default).</p> <p>Here are some best practices:</p> <ul> <li>Never add system users (start with <code>kvmd-*</code>) to any of the lists below, unless you are 100% sure you know what you are doing.</li> <li>Adding the <code>root</code> user to the <code>users</code> list is a really bad idea. We srongly recommed against doing that.</li> <li><code>kvmd-webterm</code> is the only KVMD user we can recommend adding to the <code>users</code> list. Once you've done it, you can use <code>/run/kvmd/kvmd.sock</code> from the web terminal without authentication.</li> <li>It's best to create a per-script user, add it to the <code>users</code> list, and then schedule the script execution.</li> </ul>"},{"location":"auth_advanced/#parameters_4","title":"Parameters","text":""},{"location":"auth_advanced/#users","title":"<code>users</code>","text":"<p>List of Unix usernames that are allowed to authenticate via Unix Socket Credentials. Any user in this list can connect to KVMD's Unix socket and be automatically authenticated.</p> <ul> <li>Type: List of strings</li> <li>Default: <code>[]</code> (empty list)</li> </ul>"},{"location":"auth_advanced/#groups","title":"<code>groups</code>","text":"<p>List of Unix group names whose members are allowed to authenticate via Unix Socket Credentials. Any user who is a member of one of these groups can connect to KVMD's Unix socket and be automatically authenticated.</p> <ul> <li>Type: List of strings</li> <li>Default: <code>[]</code> (empty list)</li> </ul>"},{"location":"auth_advanced/#kvmd_users-and-kvmd_groups","title":"<code>kvmd_users</code> and <code>kvmd_groups</code>","text":"<p>These two lists are reserved for system users and groups. They should never be customized. </p>"},{"location":"auth_advanced/#authentication-flow_4","title":"Authentication flow","text":"<p>When a client connects to KVMD through its Unix socket (<code>/run/kvmd/kvmd.sock</code>), the following authentication process occurs:</p> <ol> <li> <p>Connection establishment. The client process opens a connection to the Unix socket: <code>/run/kvmd/kvmd.sock</code></p> </li> <li> <p>Kernel credential passing. The Linux kernel automatically attaches the connecting process's credentials to the socket connection:</p> <ul> <li>UID (User ID) - The numeric user ID of the process</li> <li>GID (Group ID) - The primary group ID of the process</li> <li>Supplementary groups - Additional groups the user belongs to</li> </ul> <p>This happens transparently at the kernel level using the <code>SO_PEERCRED</code> socket option.</p> </li> <li> <p>Credential retrieval.. KVMD receives the connection and extracts the peer credentials from the socket. It obtains:</p> <ul> <li>The username (resolved from UID)</li> <li>The primary group name (resolved from GID)</li> <li>All supplementary group names the user is a member of .</li> </ul> </li> <li> <p>Authorization check. KVMD compares the credentials against the user whitelist and the group whitelist. If the connecting user is a member of ANY group in the groups list (primary or supplementary), authentication succeeds.</p> </li> <li> <p>Access decision.</p> <ul> <li>Success: If either the user check or group check passes, the connection is authenticated and the client gains full API access.</li> <li>Failure: If neither check passes, the connection is rejected and must use standard HTTP authentication instead.</li> </ul> </li> </ol>"},{"location":"auth_advanced/#basic-configuration-example_4","title":"Basic configuration example","text":"<p>In the following example, processes run from users <code>monitoring</code> and <code>backup-service</code> are allowed to authenticate:</p> <pre><code>kvmd:\n auth:\n usc:\n users: [\"monitoring\", \"backup-service\"]\n</code></pre> <p>Both users should exist prior to listing them in configuration. You can use <code>useradd</code> to create these users.</p>"},{"location":"auto_snapshots/","title":"Automatic snapshots","text":"<p>You can configure PiKVM to automatically take screenshots of the server screen and save them into the memory, so that you retrieve it with the HTTP API.</p>"},{"location":"auto_snapshots/#enabling-snapshots","title":"Enabling snapshots","text":"<p>Automatic snapshots are disabled by default, you need to enable and configure this feature. Switch to the read-write mode (<code>rw</code>), then open <code>/etc/kvmd/override.yaml</code> and add the following lines:</p> <pre><code>kvmd:\n snapshot:\n idle_interval: 3600\n live_interval: 60\n wakeup_key: ShiftLeft\n wakeup_move: 1000\n</code></pre> <p>Here is what these parameters do:</p> <ul> <li><code>idle_interval=3600</code> means that every hour the PiKVM must turn on the streamer, take a screenshot, and save it, if there are no users on the PiKVM.</li> <li><code>live_interval=60</code> means that KVM must take a screenshot every minute as long as there are users working on the PiKVM.</li> <li><code>wakeup_key=ShiftLeft</code> means that if there are no users on KVM, before taking a screenshot, KVM must wake up the server so that it turns on the \"screen\" from power-saving mode. To do this, it clicks and releases the left shift, simulating the user's actions.</li> <li><code>wakeup_move=1000</code> is another simulator of user actions. It moves the mouse to the position 0x0, and then to 1000x1000 (units, not pixels, but it doesn't matter, just write a large number), and then returns it back.</li> </ul> <p>Although the last two options work, PiKVM may not know if you are using the server to bypass it with a monitor and keyboard, and PiKVM input may be mix with your own. So if the PiKVM is not the only way to work with the server, we recommend not using the wakeup options. INstead, disable the power saving mode for HDMI.</p>"},{"location":"auto_snapshots/#retrieving-snapshots","title":"Retrieving snapshots","text":"<p>As soon as you have snapshots, you can retrieve them from the PiKVM using Streamer API as follows:</p> <pre><code>$ curl -k \\\n -u admin:admin \\\n 'https://<pikvm-ip>/api/streamer/snapshot?load=1' \\\n --output=file.jpg\n</code></pre> <p>You can also ask PiKVM to give you a small preview of the screenshot:</p> <pre><code>$ curl -k \\\n -u admin:admin \\\n 'https://<pikvm-ip>/api/streamer/snapshot?load=1&preview=1' \\\n --output=preview.jpg\n</code></pre> <p>Additional parameters can be used to configure the preview: <code>preview_max_width=100</code>, <code>preview_max_height=100</code>, <code>preview_quality=75</code>. </p>"},{"location":"bluetooth_hid/","title":"Bluetooth HID","text":"<p>PiKVM is able to emulate a Bluetooth keyboard & mouse. This is not the main case of using PiKVM since you still need it to pair with a remote host, but can be used for something like mobile KVM.</p> <p>Warning</p> <p>Using Bluetooth HID requires additional configuration of the operating system. For v2+, this means losing the UART port, since it will be used by Bluetooth. Also, Bluetooth operation was tested only on RPi4 and v2+ platform. Other boards may require different system service settings. Making the required changes for BT to work will also disable normal KB/MOUSE functionality therefor this will need to be disabled before normal operation can occur.</p> <p>Note</p> <p>Bluetooth mouse can work only in relative mode. The reason is that many Bluetooth host drivers do not correctly implement HID descriptors. Horizontal scrolling is not supported for the same reason.</p>"},{"location":"bluetooth_hid/#configuring-the-os","title":"Configuring the OS","text":"<ol> <li> <p>Switch filesystem to RW-mode and install some packages:</p> <pre><code># rw\n# pacman -Syy \n# pacman -Su bluez bluez-utils raspberrypi-bluetooth\n</code></pre> </li> <li> <p>Edit <code>/boot/config.txt</code> and comment these lines:</p> <pre><code>#enable_uart=1\n#dtoverlay=disable-bt\n</code></pre> </li> <li> <p>Create an empty directory <code>/var/lib/bluetooth</code> and add mountpoint to <code>/etc/fstab</code>:</p> <pre><code># mkdir /var/lib/bluetooth\n# echo 'tmpfs /var/lib/bluetooth tmpfs nodev,nosuid,mode=0755 0 0' >> /etc/fstab\n</code></pre> </li> <li> <p>Override and enable the services:</p> <pre><code># mkdir /etc/systemd/system/bluetooth.service.d\n# cat << EOF > /etc/systemd/system/bluetooth.service.d/override.conf\n[Service]\nExecStart=\nExecStart=/usr/lib/bluetooth/bluetoothd --noplugin=*\nEOF\n# systemctl enable bluetooth\n# systemctl enable raspberrypi-btuart\n</code></pre> </li> <li> <p>Override <code>kvmd</code> service:</p> <pre><code># mkdir /etc/systemd/system/kvmd.service.d\n# cat << EOF > /etc/systemd/system/kvmd.service.d/override.conf\n[Service]\nAmbientCapabilities=CAP_NET_RAW CAP_NET_BIND_SERVICE CAP_SYS_ADMIN CAP_SETUID CAP_SETGID CAP_CHOWN\nCapabilityBoundingSet=CAP_NET_RAW CAP_NET_BIND_SERVICE CAP_SYS_ADMIN CAP_SETUID CAP_SETGID CAP_CHOWN\nEOF\n</code></pre> </li> <li> <p>Add following lines to <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>kvmd:\n hid:\n type: bt\n</code></pre> </li> <li> <p>Perform <code>reboot</code>.</p> </li> <li> <p>To reverse, uncomment lines from Step 2 and remove lines in Step 6, and <code>reboot</code>.</p> </li> </ol>"},{"location":"bluetooth_hid/#using-bluetooth-hid","title":"Using Bluetooth HID","text":"<ul> <li> <p>After a reboot, the PiKVM will be ready for detection and pairing with no auth. You will see the <code>PiKVM HID</code> device.</p> </li> <li> <p>Once the server is connected, PiKVM will no longer be discoverable and pairable to other clients until you unpair the server.</p> </li> <li> <p>If something went wrong, use the web menu <code>System -> Reset keyboard & mouse</code>. This will cause unpair the device and switch the PiKVM to public mode before the first client is connected.</p> </li> </ul>"},{"location":"building_os/","title":"Building PiKVM OS","text":"<p>The assembly of PiKVM OS is carried out using a special build environment. Here the minimum required for its use, imposed on the build machine:</p> <ul> <li>kernel >= 5.8</li> <li>glibc >= 2.33</li> <li>docker >= 19.03.13</li> <li>git</li> </ul> <p>Docker must work in privileged mode.</p> <ol> <li> <p>When starting with a clean OS you need to install and configure Docker. An example for Ubuntu:</p> <pre><code>[user@localhost ~]$ sudo apt-get install git make curl binutils -y\n[user@localhost ~]$ sudo apt-get install docker.io\n[user@localhost ~]$ sudo usermod -aG docker $USER\n</code></pre> <p>Re-login to apply the changes.</p> </li> <li> <p>Checkout the build environment:</p> <pre><code>[user@localhost ~]$ git clone --depth=1 https://github.com/pikvm/os\n[user@localhost ~]$ cd os\n</code></pre> </li> <li> <p>Determine the target board and platform:</p> <ul> <li> <p>Choose the board:</p> <ul> <li><code>BOARD=rpi4</code> for Raspberry Pi 4.</li> <li><code>BOARD=zero2w</code></li> <li><code>BOARD=rpi3</code></li> <li><code>BOARD=rpi2</code></li> </ul> </li> <li> <p>Choose the platform:</p> <ul> <li><code>PLATFORM=v4mini-hdmi</code> for PiKVM V4 Mini.</li> <li><code>PLATFORM=v4plus-hdmi</code> for PiKVM V4 Plus.</li> <li><code>PLATFORM=v3-hdmi</code> for RPi4 and PiKVM V3 HAT.</li> <li><code>PLATFORM=v2-hdmi</code> for RPi3a+/RPi4 or Zero2W with HDMI-CSI bridge.</li> <li><code>PLATFORM=v2-hdmiusb</code> for RPi4 with HDMI-USB dongle.</li> <li><code>PLATFORM=v1-hdmi</code> for RPi2 or 3b+ with HDMI-CSI bridge and the Pico HID.</li> <li><code>PLATFORM=v1-hdmiusb</code> for RPi2 or 3b+ with HDMI-USB dongle and the Pico HID.</li> </ul> </li> </ul> </li> <li> <p>Create the build config file <code>config.mk</code> for the target system and and the <code>BOARD</code> and <code>PLATFORM</code> variables. You can also set some other parameters as you wish (see below). Please note: if your password contains the # character, you must escape it using a backslash like <code>ROOT_PASSWD = pass\\#word</code>.</p> <pre><code># Base board\nBOARD = rpi4\n\n# Hardware configuration\nPLATFORM = v2-hdmi\n\n# Target hostname\nHOSTNAME = pikvm\n\n# ru_RU, etc. UTF-8 only\nLOCALE = en_US\n\n# See /usr/share/zoneinfo\nTIMEZONE = Europe/Nicosia\n\n# For SSH root user\nROOT_PASSWD = rootpass\n\n# Web UI credentials: user=admin, password=adminpass\nWEBUI_ADMIN_PASSWD = adminpass\n\n# IPMI credentials: user=admin, password=adminpass\nIPMI_ADMIN_PASSWD = adminpass\n</code></pre> </li> <li> <p>Build the OS. It may take about one hour depending on the Internet connection:</p> <pre><code>[user@localhost os]$ make os\n</code></pre> <p>Tip</p> <p>If you get an error about failing to retrieving a file, please edit the Makefile and remove <code>de3.</code> from the repo URL.</p> </li> <li> <p>Create an image. It will be stored in the <code>images</code> directory as a file with <code>*.img</code> extension:</p> <pre><code>[user@localhost os]$ make image\n</code></pre> </li> <li> <p>Flash the result image to SD card.</p> </li> </ol>"},{"location":"cheatsheet/","title":"PiKVM Cheat Sheet","text":""},{"location":"cheatsheet/#pikvm-cheat-sheet","title":"PiKVM Cheat Sheet","text":"<p>Here are first steps guides for each PiKVM device:</p> <p>PiKVM V4 Mini & Plus</p> <p>PiKVM V3</p> <p>DIY PiKVM V2</p> <p>DIY PiKVM V1</p>"},{"location":"cheatsheet/#basics","title":"Basics","text":"Performing commands with root privileges <p>There are two ways to perform any command with root privileges.</p> <ol> <li> <p>Gain root privileges, then perform any command.</p> <p><code>[kvmd-webterm@pikvm ~]$ su -</code></p> <p>After providing root account password, you will be able to run any commands as a root user as long as the session is running. Use it wisely. For example, if you need to reboot PiKVM, all you need to do is this:</p> <p><code>[root@pikvm ~]# reboot</code></p> <p>The use of <code>su -</code> applies to both SSH and web terminal sessions.</p> </li> <li> <p>Use <code>su -c</code> followed by the command wrapped in apostrophes. This will perform the command with root privileges a single time, you will not gain permanent root access. This will For example, to reboot PiKVM, do this:</p> <p><code>[kvmd-webterm@pikvm ~]$ su -c 'reboot'</code></p> <p>The use of <code>su -c</code> applies to both SSH and web terminal sessions.</p> </li> </ol> Changing PiKVM Passwords <p>PiKVM comes with the following default passwords:</p> <ul> <li> <p>Linux OS-level admin (SSH, console...):</p> <ul> <li>Username: <code>root</code></li> <li>Password: <code>root</code></li> </ul> </li> <li> <p>KVM user (Web Interface, API, VNC...):</p> <ul> <li>Username: <code>admin</code></li> <li>Password: <code>admin</code></li> <li>No 2FA code</li> </ul> </li> </ul> <p>They are two separate accounts with independent passwords.</p> <p>To change passwords, you will need to use the console access via SSH or the Web Terminal. If you are using the Web Terminal, enter the <code>su -</code> command to get the <code>root</code> access (enter the <code>root</code> user password).</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# passwd root\n[root@pikvm ~]# kvmd-htpasswd set admin\n[root@pikvm ~]# ro\n</code></pre> <p>If you require additional user for the Web UI access, use the following:</p> <pre><code>[root@pikvm ~]# kvmd-htpasswd add <user> # Add a new user with password\n[root@pikvm ~]# kvmd-htpasswd del <user> # Remove/delete a user\n</code></pre> <p>Optionally you can enable the two-factor authentication for more security.</p> <p>Changing the VNCAuth key and IPMI password at the first start of PiKVM is not required, since these services are disabled by default. But it is here just so that you remember their existence.</p> Configuring PiKVM OS <p>Need more info? We have it!</p> <p>The following is a brief guide to configuring PiKVM. For more information (including the basics of YAML syntax and how to use a text editor in the Linux console), please refer to this page.</p> <p>Most of the PiKVM configuration files are located in the <code>/etc/kvmd</code> directory.</p> <p>The <code>/usr/lib/kvmd/main.yaml</code> file defines the platform configuration, and you should never edit it. To redefine system parameters use the file <code>/etc/kvmd/override.yaml</code>. All other files that are also not recommended for editing have read-only permissions.</p> <p>You can also create several files with the <code>.*yaml</code> suffix and put then into <code>/etc/kvmd/override.d</code> directory to split your customization into logical parts. The <code>override.yaml</code> file definitions takes precedence over the <code>override.d</code> directory.</p> <p>A complete list of all parameters can be viewed using the <code>kvmd -m</code> command.</p> <p>Files with the <code>*.yaml</code> suffix uses the YAML syntax and describes a parameter tree with key-value pairs of different types. To define the parameters within one section, an indent of 4 spaces is used. Comments starts with the <code>#</code> symbol.</p> <p>Only 4 spaces should be used for indentation</p> <p>Be careful when editing YAML and follow this rule. Invalid indentation or tabs instead of spaces will cause an error when starting the services.</p> <p>Sections under the same keys should be merged:</p> <ul> <li> <p>Wrong:</p> <pre><code>kvmd:\n gpio:\n drivers: ...\nkvmd:\n gpio:\n scheme: ...\n</code></pre> </li> <li> <p>Correct:</p> <pre><code>kvmd:\n gpio:\n drivers: ...\n scheme: ...\n</code></pre> </li> </ul> <p>In the <code>/etc/kvmd/meta.yaml</code> file you can specify some information regarding this PiKVM installation in an almost free YAML format.</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> Connecting to PiKVM via SSH <p>SSH is the most common remote access method in the Linux world. Normally, it should be possible to simply run <code>ssh root@pikvm</code> in a terminal window to connect to your PiKVM. However, this can fail for various reasons. In that case, you will have to connect using PiKVM's IP address.</p> <p>To connect to PiKVM via SSH, do this:</p> <ol> <li> <p>Discover PiKVM's IP address in the local network. There are several ways to do that:</p> <ul> <li>Open the web interface of your router and find the list of issued IP addresses there.</li> <li>Linux-only: install and run arp-scan: <code>sudo arp-scan --localnet</code>.</li> <li>Linux, MacOS, Windows: Download and run Angry IP Scanner.</li> <li>Windows PowerShell: Use the <code>arp -a</code> command.</li> </ul> <p>In each case, look for the entry that says \"Raspberry Pi Trading Ltd\" and copy its IP address to the clipboard. Let's assume that the IP address is <code>192.168.0.100</code>.</p> </li> <li> <p>Run the SSH client to connect to PiKVM:</p> <ul> <li>Linux, MacOS: Open any terminal application and run: <code>ssh root@192.168.0.100</code>.</li> <li>Windows: Use PuTTY for this.</li> </ul> </li> <li> <p>Submit your <code>root</code> user credentials. The default password is <code>root</code>. If you haven't changed it, you absolutely should do it.</p> </li> <li> <p>You should now be able to see and interact with the serial port. All the system tools in PiKVM will be available in the terminal window. Once you are done, type <code>exit</code> and press Enter, or simply press Ctrl+d to terminate the session.</p> </li> </ol> Connecting to PiKVM via serial console <p>A serial console is a convenient and fast way to connect to PiKVM when there is no network, or get boot logs and a console if something goes wrong.</p> <ol> <li> <p>Connect to the physical universal asynchronous receiver / transmitter (UART) console from your host computer:</p> <ul> <li> <p>On PiKVM V3 or V4, you have a built-in USB-UART adapter in your device. Just disconnect the OTG cable and place the USB-C end into the <code>IOIOI</code> port on V4 (or the <code>CON</code> port on V3). Place the USB-A end into the port you want serial to be accessed, typically done on the host. If you have a Windows host, you may need to install this driver, other operating systems may not need one.</p> </li> <li> <p>On DIY PiKVM V1 or V2, you'll need to get the right TTY to USB cable, we recommend the RPi Debug Probe and follow existing RPi TTY serial setups.</p> </li> </ul> </li> <li> <p>Install <code>picocom</code> on a Linux or a macOS host (available in Homebrew and MacPorts), or Putty on Windows.</p> </li> <li> <p>Identify the port that your operating system exposes for connecting to the PiKVM.</p> <ul> <li> <p>Windows: look this up in the Device Manager</p> </li> <li> <p>Linux: open a terminal program, run <code>sudo dmesg | grep tty</code>and look for a message like this:</p> </li> </ul> <pre><code>[14362.388405] usb 1-2: cp210x converter now attached to ttyUSB0\n</code></pre> <p>This means you will need to use <code>/dev/ttyUSB0</code>.</p> <ul> <li>macOS: open the terminal and list all USB serial devices with <code>ls /dev/cu.usbserial-*</code>. Look for a device that contains <code>cu.usbserial</code>, e.g. <code>/dev/cu.usbserial-FT0RVWSW</code>.</li> </ul> </li> <li> <p>Connect via the serial port:</p> <ul> <li> <p>Windows: select the COM port in Putty and use the 115200 baud rate, then connect.</p> </li> <li> <p>Linux/macOS: open your terminal program and run <code>sudo picocom -b 115200 $USB_SERIAL_DEVICE</code> where <code>$USB_SERIAL_DEVICE</code> is the device you looked up, e.g. <code>/dev/ttyUSB0</code> on Linux or <code>/dev/cu.usbserial-FT0RVWSW</code> on macOS.</p> </li> </ul> <p>After running the command, press Enter to get to a login prompt.</p> </li> <li> <p>Submit your root user credentials.</p> </li> <li> <p>You should now be able to see and interact with the serial port. All the system tools in PiKVM will be available in the terminal window. Once you are done, press Ctrl+a and then immediately Ctrl+x to terminate the session.</p> </li> </ol> Shutting down PiKVM <p>PiKVM defaults to using the system in read-only mode, so there is no need to explicitly shut it down. You can simply unplug the device from power.</p> <p>If you absolutely need to use the shutdown command, please ensure the following requirements are met:</p> <ul> <li>This is not one of the DIY (V1 or V2) devices. If you shut down a DIY PiKVM, it will not power on until you physically reconnect the power cord.</li> <li>You are not currently running a system update. If you are, you will likely corrupt the system.</li> <li>You are not currently uploading a mass storage drive image. If you are, you will likely corrupt the system.</li> </ul> <p>If all these requirements are met, do this:</p> <pre><code>[kvmd-webterm@pikvm ~]$ su -\n[root@pikvm ~]# shutdown -h now\n</code></pre> <p>PiKVM V3 and V4 will automatically reboot after several minutes of being halted. DIY PiKVM will need a power cord reconnection to become available again. </p>"},{"location":"cheatsheet/#getting-user-support","title":"Getting User Support","text":"<p>If something doesn't work, check out our FAQ. Otherwise, head straight to our Support.</p>"},{"location":"cloudflared/","title":"Cloudflare tunnels","text":"<p>Warning</p> <p>This is unofficial instructions proposed by the community. We don't officially support this and don't know what problems may arise when using cloudflared.</p> <p>Cloudflare Tunnels can be used to access PiKVM over the internet securely using Cloudflare Zero Trust with Cloudflared. This is a convenient and free (for 50 users) tool for allowing access to web services running on your internal network without port forwarding or IPv4/IPv6 compatability issues. This document is provided as an example for accessing your PiKVM over the internet but you can also use Zerotier/Tailscale/Insert XYZ VPN service here. Basic support like whats shown below is provided as an example, any other setting or functionality needs to be redirected to the appropriate community.</p> <p>If you get error 1033 / lookup localhost error</p> <p>You might need to add <code>127.0.0.1 localhost</code> into your /etc/hosts file</p>"},{"location":"cloudflared/#prequisites","title":"Prequisites","text":"<ol> <li> <p>A domain utilizing Cloudflare for DNS</p> </li> <li> <p>A Cloudflare tunnel configured with an application created and secured by an access policy</p> </li> <li> <p>Custom firewall rules configured in Cloudflare as needed</p> </li> </ol>"},{"location":"cloudflared/#cloudflare-tunnel-steps","title":"Cloudflare Tunnel Steps","text":"<ol> <li> <p>Login to Cloudflare and provision a tunnel using the steps here. Save the tunnel token as we will need this later. In most cases the target will be https://localhost </p> </li> <li> <p>Create a self-hosted application with the URL matching one created in the previous step by following the steps here. </p> </li> <li> <p>You will need to check the http options to disable SSL certificate verification under <code>Tunnels -> Configure -> Public Hostname -> yourapplication.yourdomain -> Edit -> TLS Settings -> No TLS Verify</code> as the PiKVM uses self-signed certificates.</p> </li> <li> <p>Don't skip the access policies as this important to preventing randoms from the internet from gaining access to your PiKVM. Cloudflare offers a variety of login options with the simplest being One-time PINs that are emailed to you. NOTE: This external authentication will not replace the username/password for the PiKVM but instead supplement it acting as a first line of defense from the internet.</p> </li> </ol>"},{"location":"cloudflared/#installation-on-the-pikvm","title":"Installation on the PiKVM","text":"<ol> <li> <p>Use these commands to install Cloudflared:</p> <pre><code># rw\n# curl -L -o /usr/local/bin/cloudflared \"$(curl -s \"https://api.github.com/repos/cloudflare/cloudflared/releases/latest\" | grep -e 'browser_download_url.*/cloudflared-linux-armhf\"' | sed -e 's/[\\ \\\":]//g' -e 's/browser_download_url//g' -e 's/\\/\\//:\\/\\//g')\"\n# chmod +x /usr/local/bin/cloudflared\n# cloudflared version\n</code></pre> </li> <li> <p>Update /etc/systemd/resolved.conf and set cloudflare nameservers.</p> <pre><code># sudo vim /etc/systemd/resolved.conf\n# Uncomment DNS line and set 'DNS=1.1.1.1 1.0.0.1'\n# systemctl restart systemd-resolved\n</code></pre> </li> <li> <p>Install the Cloudflare tunnel service to Cloudflared.</p> <pre><code># sudo cloudflared service install SERVICE_TOKEN_HERE\n</code></pre> </li> <li> <p>Ensure cloudflared service is enabled so it starts on boot.</p> <pre><code># sudo systemctl enable cloudflared\n</code></pre> </li> <li> <p>Open a web browser and attempt to connect to your tunnel.</p> </li> <li> <p>Drop back in to read only mode</p> <pre><code># ro\n</code></pre> </li> <li> <p>Reboot pikvm and ensure your tunnel comes back up. This may take a few minutes. </p> </li> </ol>"},{"location":"cloudflared/#updating-cloudflared","title":"Updating Cloudflared","text":"<p>Use these commands to update Cloudflared:</p> <pre><code># rw\n# cloudflared update\n# ro\n</code></pre>"},{"location":"compliance/","title":"Compliance","text":""},{"location":"compliance/#compliance-information","title":"Compliance Information","text":"<ul> <li>PiKVM CE/UKCA</li> </ul>"},{"location":"config/","title":"Overriding system settings","text":"<p>PiKVM OS has various low-level settings you can customize: timeout for the <code>kvmd</code> daemon, default keymap for the emulated keyboard, scroll rate for VNC sessions, logs formatting, etc. To do that, you need to override default settings.</p>"},{"location":"config/#how-overrides-work-in-pikvm-os","title":"How overrides work in PiKVM OS","text":"<p>Main default settings are stored in <code>/usr/lib/kvmd/main.yaml</code>. However, you should never edit that file. To override these and other defaults, you need to edit <code>/etc/kvmd/override.yaml</code> instead.</p> <p>PiKVM OS applies settings from <code>main.yaml</code> first and then applies anything it finds in <code>override.yaml</code>. This approach helps keeping defaults and customizations safely separate from each other.</p>"},{"location":"config/#how-overrideyaml-is-structured","title":"How <code>override.yaml</code> is structured","text":"<p>The <code>/etc/kvmd/override.yaml</code> file has YAML syntax. All configurations are stored as key-value pairs.</p> <p>Consider this example:</p> <pre><code>file: /etc/kvmd/ipmipasswd\n</code></pre> <p>Here, <code>file</code> is a key, or the name of a configuration entry, and <code>/etc/kvmd/ipmipasswd</code> is the value. Keys and values are separated by a semicolon.</p> <p>YAML files can have nested key-value pairs:</p> <pre><code>ipmi:\n auth:\n file: /etc/kvmd/ipmipasswd\n</code></pre> <p>To nest key-value pairs correctly, use four spaces rather than tabulation for indentation.</p> <p>There is no need to copy and paste an entire configuration tree of key-value pairs to change just one setting. For example, if you want to change just the <code>kvmd</code> timeout, you only need the <code>timeout</code> setting and its parent keys, kvmd and vnc:</p> <pre><code>vnc:\n kvmd:\n timeout: 7.0\n</code></pre> <p>An important rule is that sections under the same keys should be merged:</p> <ul> <li> <p>Wrong:</p> <pre><code>kvmd:\n gpio:\n drivers: ...\nkvmd:\n gpio:\n scheme: ...\n</code></pre> </li> <li> <p>Correct:</p> <pre><code>kvmd:\n gpio:\n drivers: ...\n scheme: ...\n</code></pre> </li> </ul> <p>Anything that starts with <code>#</code> is considered a comment. This is useful when you need to document your customizations, e.g., write down the rationale for changing a particular default.</p> <p>You can start new lines with comments if you need to write a longer explanation.</p> <pre><code># 2025-05-08: changed the default timeout to 7.0 after some troubleshooting.\nvnc:\n kvmd:\n timeout: 7.0\n</code></pre> <p>You can also write inline comments like this:</p> <pre><code>vnc:\n kvmd:\n timeout: 7.0 #this seems to work better\n</code></pre> <p>Let's practice changing a default setting by switching to a German keyboard map by default. This is just an example to explain how overrides work.</p>"},{"location":"config/#change-file-system-access-to-read-write","title":"Change file system access to read-write","text":"<p>For safety reasons, access to the file system of PiKVM OS is read-only by default. You need to temporarily change it to read-write to be able to save changes to the configuration file. To do it, use the <code>rw</code> command:</p> <pre><code>[root@pikvm ~]# rw\n</code></pre>"},{"location":"config/#identify-the-configuration-entry","title":"Identify the configuration entry","text":"<p>Before you start editing, you need to find the setting you will need to override. Run <code>kvmd -m</code> to look up configuration entries you can redefine. This command will print the entire list. We need the <code>keymap</code> setting somewhere in the <code>kvmd</code> group:</p> <p></p> <p>So, the correct hierarchy is <code>kvmd/hid/keymap</code>, and the path to keymaps is <code>/usr/share/kvmd/keymaps/</code>.</p> <p>List all keymaps in that directory:</p> <pre><code>[root@pikvm ~]# ls /usr/share/kvmd/keymaps/\nar cz de en-gb en-us-altgr-intl es fi fr fr-ca hr is ja lv nl pl pt-br sl th\nbepo da de-ch en-us en-us-colemak et fo fr-be fr-ch hu it lt mk no pt ru sv tr\n</code></pre> <p>You will need <code>de</code>, which is a two-letter code for German.</p>"},{"location":"config/#edit-overrideyaml","title":"Edit <code>override.yaml</code>","text":"<p>Now, let's open <code>override.yaml</code> for editing. PiKVM ships with both <code>nano</code> and <code>vim</code>. We generally recommend <code>nano</code> over <code>vim</code> for new users:</p> <pre><code>[root@pikvm ~]# nano /etc/kvmd/override.yaml\n</code></pre> <p><code>nano</code> has a console user interface, so it displays the text file right in the terminal window:</p> <p></p> <p>Scroll down to the bottom of the file (use Ctrl+End, PageDown, or ArrowDown keys). Type this:</p> <pre><code>kvmd:\n hid:\n keymap: /usr/share/kvmd/keymaps/de\n</code></pre> <p>Don't forget to indent each child key with four spaces.</p>"},{"location":"config/#save-the-file","title":"Save the file","text":"<p>Now, you need to save the configuration file and exit. Nano displays hints on the most important keyboard shortcuts at the bottom of its window.</p> <p></p> <p><code>^</code> stands for Ctrl on Windows and Linux and for Cmd on macOS. <code>M</code> stands for Alt.</p> <p>Press Ctrl+O to save the configuration file and then Ctrl+X to quit nano.</p>"},{"location":"config/#validate-the-configuration","title":"Validate the configuration","text":"<p>Before attempting to make your changes take effect, you should always validate <code>override.yaml</code>. To do that, run <code>kvmd -m</code>. If there are any syntax errors, <code>kvmd</code> will complain about them.</p> <p>For example, if you accidentally used a semicolon instead of a colon between the key and the value like this:</p> <pre><code>keymap; /usr/share/kvmd/keymaps/de\n</code></pre> <p><code>kvmd -m</code> will display this message instead of outputting all configuration entries:</p> <pre><code>ConfigError: The node 'vnc' must be a dictionary\n</code></pre> <p>If you see any errors in the output, fix them and run <code>kvmd -m</code> again to verify that the error is gone.</p> <p>Note that <code>kvmd -m</code> does not validate configuration entries for correct key names. So if your changes don't work, that's #1 thing to check for when troubleshooting.</p>"},{"location":"config/#change-access-to-read-only","title":"Change access to read-only","text":"<p>Before you go to the next step, change the file system access mode to read-only. To do that, run the <code>ro</code> command:</p> <pre><code>[root@pikvm kvmd-webterm]# ro\n</code></pre>"},{"location":"config/#reboot-your-pikvm","title":"Reboot your PiKVM","text":"<p>There are close to a dozen various system daemons that depend on configuration settings. The easiest way to apply your changes is to simply reboot your PiKVM:</p> <pre><code>[root@pikvm ~]# reboot\n</code></pre> <p>Once the device restarts, your changes take effect.</p>"},{"location":"config/#keeping-customizations-atomic","title":"Keeping customizations atomic","text":"<p>When you apply massive customizations, it may help separating changes into several files to keep them manageable.</p> <p>To do that, create these YAML files inside the <code>/etc/kvmd/override.d/</code> directory. KVMD will apply all configurations in the following order: <code>main.yaml</code> -> legacy <code>auth.yaml</code> -> <code>override.d</code> -> <code>override.yaml</code>. Inside the <code>override.d</code> directory, KVMD will apply YAML files in alphabetical order, so please pay attention to how you name them.</p> <p>We recommend sticking with a particular file-naming scheme, e.g. <code>0000-vendor-otg-serial.yaml</code>. We do reserve <code>-vendor-</code> and <code>-pikvm-</code> prefixes for our own future needs, though.</p> <p>Once you completed the customization and validated newly created/edited files, reboot your PiKVM for the changes to take effect.</p>"},{"location":"config/#legacy-notes","title":"Legacy notes","text":"<ul> <li> <p>Older installations may have used the outdated <code>/etc/kvmd/auth.yaml</code> for authorization settings. It existed even before the introduction of <code>/etc/override*</code> mechanism. It has never been recommended for use in this documentation and should contain only the string <code>{}</code>, meaning an empty configuration.</p> <p>However, if you have used it, you should move your configuration from <code>/etc/kvmd/auth.yaml</code> somewhere in <code>/etc/kvmd/override.d</code> or even <code>/etc/kvmd/override.yaml</code>, and then delete the source file <code>/etc/kvmd/auth.yaml</code>.</p> <p>For example, if the <code>/etc/kvmd/auth.yaml</code> contained the following text:</p> <pre><code>enabled: false\n</code></pre> <p>You can move it to <code>/etc/kvmd/override.d/9999-auth.yaml</code> and change the nesting of the parameters as follows:</p> <pre><code>kvmd:\n auth:\n enabled: false\n</code></pre> </li> <li> <p>Early YAML configurations could contain the <code>!include</code> directive, which loaded the content of another file to the appropriate level. It still works, but has been deprecated and should not be used. Support will be removed in the future.</p> </li> </ul>"},{"location":"edid/","title":"EDID","text":"<p>Info</p> <p>This applies to PiKVM V3, V4 and DIY based on CSI bridge. It is impossible to change the EDID for the HDMI-USB dongle.</p> <p>The EDID provides an information about the video modes supported by the video capture device. In the case of PiKVM, this is an HDMI CSI bridge. Usually, you don't need to change this, since the default configuration is quite flexible, but sometimes, for example for strange UEFIs/BIOSes, this may be necessary (a story).</p>"},{"location":"edid/#basics","title":"Basics","text":"<p>The EDID is stored on the PiKVM in the file <code>/etc/kvmd/tc358743-edid.hex</code> in HEX format. When booting PiKVM OS, it is used by <code>kvmd-tc358743.service</code> and loaded into the video capture chip.</p> <p>If you replace the EDID in this file, the EDID can be applied manually without rebooting using the command <code>kvmd-edidconf --apply</code>.</p> <p>If you just want to change the monitor's identification, we don't recommend that you change the entire EDID. Just use <code>kvmd-edidconf</code> and its built-in EDID changing options.</p> <p>Note</p> <p>Windows caches drivers and registry settings so changing the monitor name is not enough, you will also need to change the product ID and/or the serial number along with the monitor name:</p> <pre><code>[root@pikvm ~]# kvmd-edidconf --set-monitor-name=TOSHIBA --set-mfc-id=TTP --set-product-id=34953 --set-serial=2290649089 --apply\n</code></pre> <p>Quick IDs changing on PiKVM V4 Plus</p> <p>PiKVM V4 Plus has a simple way read and adopt display identifiers like model and serial number from your physical display. See here for details.</p> <p>Run <code>kvmd-edidconf</code> on PiKVM:</p> <pre><code>[root@pikvm ~]# kvmd-edidconf\nManufacturer ID: LNX\nProduct ID: 0x7773 (30579)\nSerial number: 0x01010101 (16843009)\nMonitor name: PiKVM V4 Plus\nMonitor serial: CAFEBABE\nAudio: yes\n</code></pre> <p>The fields have obvious names and purposes. Note the two similar fields <code>Serial number</code> and <code>Monitor serial</code>. The first has a numeric value, and the second is ASCII. If you are using a custom EDID from some real display, some fields may be missing.</p> <p>To change the values of the EDID fields, use the <code>kvmd-edidconf</code> with options, a complete list is available in <code>kvmd-edidconfi --help</code>.</p> <p>Here the small example of changing all available fields from the previous listing:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# kvmd-edidconf --set-mfc-id=TTP --set-product-id=0x5B81 --set-serial=0x8DE11B79 --set-monitor-name=TOSHIBA --set-monitor-serial=ABCD1234 --apply\nManufacturer ID: TTP\nProduct ID: 0x5B81 (23425)\nSerial number: 0x8DE11B79 (2380340089)\nMonitor name: TOSHIBA\nMonitor serial: ABCD1234\nAudio: yes\n...\n[root@pikvm ~]# ro\n</code></pre> <p>The full list of manufacturer IDs is available here.</p> <p>Typical examples of working with EDID and the full cycle of using custom EDID will be shown below.</p>"},{"location":"edid/#adopt-real-display-indentifiers-on-v4-plus","title":"Adopt real display indentifiers on V4 Plus","text":"<p>PiKVM V4 Plus has a simple way read and adopt display identifiers like model and serial number from the physical monitor connected to <code>OUT2</code> port (it's also used for HDMI passthrough). This way, the target host will recognize PiKVM as your display.</p> <p>To adopt display identifiers, connect the display to <code>OUT2</code> port and run these commands:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# kvmd-edidconf --import-display-ids --apply\n[root@pikvm ~]# ro\n</code></pre> <p>Now the display can be unplugged. PiKVM will remember the new settings.</p>"},{"location":"edid/#restore-default-edid","title":"Restore default EDID","text":"<p>If you need to restore the default EDID you can easily do this with <code>kvmd-edidconf</code>, for example:</p> <p></p><pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# kvmd-edidconf --import-preset=v4plus --apply\n[root@pikvm ~]# ro\n</code></pre> Available options: <code>v0</code>, <code>v1</code>, <code>v2</code>, <code>v3</code>, <code>v4mini</code> and <code>v4plus</code>. <p>Also defaults edid can be found locally on your PiKVM: <code>/usr/share/kvmd/configs.default/kvmd/edid</code>, or in the kvmd repo.</p>"},{"location":"edid/#force-1080p-by-default-on-pikvm-v0-v3","title":"Force 1080p by default on PiKVM V0-V3","text":"<p>PiKVM V3 (or DIY V0-V2) has a hardware limit of 50Hz for 1080p mode, and this is a less common frequency than 60Hz. Therefore, on V3, the default mode is 720p. Some OS (like Proxmox) may not work well with 720p, so you can force 1080p resolution by default:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# kvmd-edidconf --import-preset=v3.1080p-by-default --apply # Or, for example, v1.1080p-by-default\n[root@pikvm ~]# ro\n</code></pre>"},{"location":"edid/#disable-1920x1200-on-pikvm-v4","title":"Disable 1920x1200 on PiKVM V4","text":"<p>PiKVM V4 supports the advanced capture mode with 1920x1200. If it bothers you (for example, if you use a physical monitor 1920x1080 with video passthrough), you can easily disable it and use only 1920x1080:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# kvmd-edidconf --import-preset=v4plus.no-1920x1200 --apply # Or v4mini.no-1920x1200\n[root@pikvm ~]# ro\n</code></pre>"},{"location":"edid/#applying-a-custom-edid","title":"Applying a custom EDID","text":"<p>PiKVM is able to emulate a physical display with a specific EDID. You can find EDID examples in the community database and then use it on PiKVM.</p> <p>At the same time, you should pay attention to the hardware capabilities of PiKVM and the EDID capabilities that you use. For example, if EDID reports 8K support, then this obviously won't work: your host will try to send an 8K signal, while PiKVM can process no more than 1080p.</p> <ul> <li>PiKVM V1-V3: The maximum resolution is 1920x1080 at 50Hz.</li> <li>PiKVM V4: The maximum is 1920x1200 at 60Hz.</li> </ul> <p>In the case of the PiKVM V4, almost any EDID for 1080p monitors will work. All EDIDs that are suitable for PiKVM V3 will work too.</p>"},{"location":"edid/#example-edids-for-v4","title":"Example EDIDs for V4","text":"Acer B246WL, 1920x1200, with audio <p>Taken here, as described above. </p><pre><code>00FFFFFFFFFFFF00047265058A3F6101\n101E0104A53420783FC125A8554EA026\n0D5054BFEF80714F8140818081C08100\n8B009500B300283C80A070B023403020\n360006442100001A000000FD00304C57\n5716010A202020202020000000FC0042\n323436574C0A202020202020000000FF\n0054384E4545303033383532320A01F8\n02031CF14F9002030405060701111213\n1415161F2309070783010000011D8018\n711C1620582C250006442100009E011D\n007251D01E206E28550006442100001E\n8C0AD08A20E02D10103E960006442100\n0018C344806E70B028401720A8040644\n2100001E000000000000000000000000\n00000000000000000000000000000096\n</code></pre> ASUS PA248QV, 1920x1200, with audio <p>Taken here, as described above. </p><pre><code>00FFFFFFFFFFFF0006B3872401010101\n021F010380342078EA6DB5A7564EA025\n0D5054BF6F00714F8180814081C0A940\n9500B300D1C0283C80A070B023403020\n360006442100001A000000FD00314B1E\n5F19000A202020202020000000FC0050\n4132343851560A2020202020000000FF\n004D314C4D51533035323135370A014D\n02032AF14B900504030201111213141F\n230907078301000065030C001000681A\n00000101314BE6E2006A023A80187138\n2D40582C450006442100001ECD5F80B0\n72B0374088D0360006442100001C011D\n007251D01E206E28550006442100001E\n8C0AD08A20E02D10103E960006442100\n001800000000000000000000000000DC\n</code></pre> DELL D2721H to avoid black screen on some HDMI splitters, 1920x1080, no audio <p>Taken here, as described above. </p><pre><code>00FFFFFFFFFFFF0010AC132045393639\n201E0103803C22782ACD25A3574B9F27\n0D5054A54B00714F8180A9C0D1C00101\n010101010101023A801871382D40582C\n450056502100001E000000FF00335335\n475132330A2020202020000000FC0044\n454C4C204432373231480A20000000FD\n00384C1E5311000A2020202020200181\n02031AB14F9005040302071601061112\n1513141F65030C001000023A80187138\n2D40582C450056502100001E011D8018\n711C1620582C250056502100009E011D\n007251D01E206E28550056502100001E\n8C0AD08A20E02D10103E960056502100\n00180000000000000000000000000000\n0000000000000000000000000000004F\n</code></pre>"},{"location":"edid/#example-edids-for-v1-v3","title":"Example EDIDs for V1-V3","text":"1280x1024 as preferred. Useful for Gigabyte GA-H77-DS3H <pre><code>00FFFFFFFFFFFF005262888800888888\n1C150103800000780AEE91A3544C9926\n0F505425400001000100010001000100\n010001010101D51B0050500019400820\nB80080001000001EEC2C80A070381A40\n3020350040442100001E000000FC0050\n492D4B564D20566964656F0A000000FD\n00323D0F2E0F0000000000000000014D\n02030400DE0D20A03058122030203400\nF0B400000018E01500A0400016303020\n3400000000000018B41400A050D01120\n3020350080D810000018AB22A0A05084\n1A3030203600B00E1100001800000000\n00000000000000000000000000000000\n00000000000000000000000000000000\n00000000000000000000000000000045\n</code></pre> 1920x1080 as preferred. Useful for motherboards such as ASRock H670 PG Riptide, Gigabyte GA-H77-DS3H, MSI series such as B550M, B660M, Z690-A and X570. Also the Intel NUC. <pre><code>00FFFFFFFFFFFF005262888800888888\n1C150103800000780AEE91A3544C9926\n0F505425400001000100010001000100\n010001010101D32C80A070381A403020\n350040442100001E7E1D00A050001940\n3020370080001000001E000000FC0050\n492D4B564D20566964656F0A000000FD\n00323D0F2E0F000000000000000001C4\n02030400DE0D20A03058122030203400\nF0B400000018E01500A0400016303020\n3400000000000018B41400A050D01120\n3020350080D810000018AB22A0A05084\n1A3030203600B00E1100001800000000\n00000000000000000000000000000000\n00000000000000000000000000000000\n00000000000000000000000000000045\n</code></pre> 1280x1024 as preferred, disabled 1080p at all. This may be necessary in extremely rare cases if the BIOS is completely buggy. In the future, we will provide a way to dynamically switch EDID <pre><code>00FFFFFFFFFFFF005262888800888888\n1C150103800000780AEE91A3544C9926\n0F50542FCF0001000100010001000100\n0100010101018C2300A050001E403020\n370080001000001E000000FC0050492D\n4B564D20566964656F0A000000FD0032\n3D0F2E0F000000000000000000000010\n0000000000000000000000000000016B\n02030400DE0D20A03058122030203400\nF0B400000018E01500A0400016303020\n3400000000000018B41400A050D01120\n3020350080D810000018AB22A0A05084\n1A3030203600B00E1100001800000000\n00000000000000000000000000000000\n00000000000000000000000000000000\n00000000000000000000000000000045\n</code></pre>"},{"location":"edid/#applying-a-choosen-custom-edid","title":"Applying a choosen custom EDID","text":"<p>To apply the selected EDID, follow these steps:</p> <ol> <li> <p>Switch filesystem to RW-mode:</p> <pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Open the file <code>/etc/kvmd/tc358743-edid.hex</code> with any text editor, for example, with Nano:</p> <pre><code>[root@pikvm ~]# nano /etc/kvmd/tc358743-edid.hex\n</code></pre> </li> <li> <p>Replace the HEX data with the new, save and close the editor.</p> </li> <li> <p>Apply the EDID:</p> <pre><code>[root@pikvm ~]# kvmd-edidconf --apply\n</code></pre> </li> <li> <p>Sometimes it may be necessary to reboot the target host. Check the OS on the host, UEFI/BIOS. If everything works, then your goal has been achieved and proceed to the last step. If something went wrong, you can always undo these changes and restore the default EDID.</p> </li> <li> <p>Don't forget to switch filesystem to the RO-mode:</p> <pre><code>[root@pikvm ~]# ro\n</code></pre> </li> </ol>"},{"location":"edid/#editing-edid","title":"Editing EDID","text":"<p>To edit the EDID, it is best to use third-party utilities, such as the recommended advanced AW EDID Editor for Windows (it's working great in wine) or wxEDID. Both editors work with the binary EDID format, but you can easily import and export it to PiKVM using the <code>kvmd-edidconf</code> utility.</p> <p>So, to tune EDID on PiKVM, use the following steps:</p> <ol> <li> <p>Switch filesystem to RW-mode:</p> <pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Export the system EDID to the binary file <code>myedid.bin</code>:</p> <pre><code># kvmd-edidconf --export-bin=/root/myedid.bin\n</code></pre> </li> <li> <p>Copy this file to your PC using SCP, Putty or something like that. Open this binary file in the EDID editor and change the necessary parameters. Save your changes and copy the binary file back to PiKVM.</p> </li> <li> <p>Convert the binary file to the HEX and test it:</p> <pre><code>[root@pikvm ~]# kvmd-edidconf --import=/root/myedid.bin --apply\n</code></pre> </li> <li> <p>Sometimes it may be necessary to reboot the target host. Check the OS on the host, UEFI/BIOS. If everything works, then your goal has been achieved and proceed to the last step. If something went wrong, you can always undo these changes and restore the default EDID.</p> </li> <li> <p>Don't forget to switch filesystem to the RO-mode:</p> <pre><code>[root@pikvm ~]# ro\n</code></pre> </li> </ol>"},{"location":"ezcoo/","title":"ezCoo managed multiport KVM switch","text":"<p>Warning</p> <p>While we provide this document for your convenience, this is a third-party hardware device in the same path as a PiKVM. Therefore, you may need to experiment (trial and error) to get it to work how you like. In the case of the U3P (hot key version), it may or may not work as expected.</p> <p>PiKVM + Multiport Switches compatibility</p> <p>Please note that this switch requires a USB port for control. The following devices can provide this:</p> <ul> <li>PiKVM V3 & V4 Plus.</li> <li>DIY devices based on Raspberry Pi 2, 3 and 4.</li> </ul> <p>The following devices are not compatible:</p> <ul> <li>PiKVM V4 Mini - it doesn't have a USB host port and cannot control switches, it's a single-host device.</li> <li>DIY based on Raspberry Pi Zero 2 W - it doesn't have USB host port too.</li> </ul> <p>The ezCoo managed switch can be controlled by PiKVM to allow it to connect to multiple hosts. A typical scenario is a single PiKVM device which can control and switch between multiple hosts or servers using the ezCoo switch. UI elements can be added to the GPIO dropdown to allow switching between hosts from the PiKVM webpage.</p> <p>The instructions here were tested with the ezCoo SW41HA HDMI 4x1 switch ezCoo EZ-SW41HA-KVMU3L 4x1 switch OR ezCoo EZ-SW41HA-KVMU3P 4x1 switch.</p> <p>Both older USB2.0 and newer USB3.0 variants are supported. The following was testing on a Raspberry Pi 4 but should also work on the Pi 2 and 3.</p> <p>This document was created using the contributions from multiple users in our Discord and the author appreciates their efforts.</p> <p>Info</p> <p>While most images of the switch do not show the sides, there is a Micro USB port on the side of the ezCoo switch. This is the management port, which is controlled via COM port on the ezCoo KVM. When plugged into the Raspberry Pi, it appears as <code>/dev/ttyUSB0</code>.</p> <p>Info</p> <p>Audio was not tested, it is assumed to be non-functional.</p> <p>Tip</p> <p>ezCoo EZ-SW41HA-KVMU3L - includes 4x1m USB 3.0 A Male to A Male. You will need 1 extra USB A Male to USB Micro B to connect from the PiKVM to the ezcoo \"F/W CTL - Management\" port</p>"},{"location":"ezcoo/#connections","title":"Connections","text":"<p>EZCOO Wiring example can be found here Scroll down to bottom of page for picture</p> <p>Please review the item description and manual before deploying.</p> <p>From a high level, the ezCoo switch uses standard connections to the host machines (USB-A to USB-B and HDMI for USB2 version, USB-A to USB-A for the USB3 version). The Raspberry Pi OTG connector (the one coming from the USB-C port on a Pi 4 via the custom splitter cable or device) should be connected to the USB 3 port on the ezCoo switch. There is an additional USB cable connected to the managed port on the switch.</p> <ol> <li> <p>Connect the USB-C cable from the Raspberry Pi OTG port to ezCoo switch USB 3 port on the front or USB 1 port on the back of the switch. Note: If this cable is connected to the keyboard port (USB 2) of the ezCoo switch, the mouse will not be present.</p> </li> <li> <p>Connect the HDMI out from the ezCoo switch to the Raspberry Pi CSI-2 to HDMI input. Other users have reported HDMI encoder USB dongles as working.</p> </li> <li> <p>Connect a USB-A to Micro USB cable from the Raspberry Pi to the management port on the side of the ezCoo switch.</p> </li> <li> <p>Connect host USB and HDMI cables from the ezCoo switch to the machines to be managed per the switch instructions.</p> </li> <li> <p>At this point the KVM switch should be present as a device on the PiKVM. SSH into PiKVM and ensure a device like <code>/dev/ttyUSB0</code> is present. The following instructions assume this is the KVM switch.</p> </li> </ol> <p>Info</p> <p>There is a limitation in the underlying PiKVM software related to plugging video cables from a host which is already powered and connected to a monitor to a Raspberry Pi CSI2-HDMI encoder. These limitations apply equally when using the ezCoo KVM switch. If video is not present in PiKVM, try keeping all host machines off and connecting them directly to the ezCoo switch before powering the hosts on.</p>"},{"location":"ezcoo/#adding-ui-elements-to-control-the-kvm-switch","title":"Adding UI elements to control the KVM switch","text":"<p>The UI can be updated to add buttons to switch between KVM inputs and indicators for which input is currently selected. The instructions below will make these available in the PiKVM UI after clicking the \"GPIO\" menu button in the KVM view.</p> <ol> <li> <p>Enable read-write mode on the SD card via <code>rw</code></p> </li> <li> <p>Edit the file: <code>nano /etc/kvmd/override.yaml</code> and include the following. Note the assumption that the KVM switch is present on <code>/dev/ttyUSB0</code>:</p> <pre><code>kvmd:\n gpio:\n drivers:\n ez:\n type: ezcoo\n protocol: 2\n device: /dev/ttyUSB0\n scheme:\n ch0_led:\n driver: ez\n pin: 0\n mode: input\n ch1_led:\n driver: ez\n pin: 1\n mode: input\n ch2_led:\n driver: ez\n pin: 2\n mode: input\n ch3_led:\n driver: ez\n pin: 3\n mode: input\n ch0_button:\n driver: ez\n pin: 0\n mode: output\n switch: false\n ch1_button:\n driver: ez\n pin: 1\n mode: output\n switch: false\n ch2_button:\n driver: ez\n pin: 2\n mode: output\n switch: false\n ch3_button:\n driver: ez\n pin: 3\n mode: output\n switch: false\n view:\n table:\n - [\"#Input 1\", ch0_led, ch0_button]\n - [\"#Input 2\", ch1_led, ch1_button]\n - [\"#Input 3\", ch2_led, ch2_button]\n - [\"#Input 4\", ch3_led, ch3_button]\n</code></pre> Editing '#Input X' to '#Something else' will change the table name in the GUI drop down, if you want a different name, name it something else and restart kvmd. <p>This now only applies to older images, newer images do not have this issue. Make sure to notate the spaces for each line, needs to be a total of 4 spaces added per line (NOT tabs):</p> <pre><code>For example:\n parent: 0 spaces (kvmd:)\n child: 4 spaces (gpio:)\n sub-child: 8 spaces (drivers:)\n sub-sub-child: 12 spaces (ez:)\n</code></pre> </li> <li> <p>Return to read-only mode for the sd card via <code>ro</code>.</p> </li> <li> <p>Restart the kvmd service: <code>systemctl restart kvmd</code>.</p> </li> <li> <p>If you are still not getting KB output, issue a <code>ls -la /dev/tty* | grep USB</code> , if no output change cables (Alot of cables are power only)</p> </li> </ol>"},{"location":"ezcoo/#switching-between-hosts-in-the-ui","title":"Switching between hosts in the UI","text":"<p>To switch between hosts, enter the KVM UI and click the \"GPIO\" menu. You should see 4 inputs, one of which will have a green circle indicating it is currently selected. Click the other inputs to change the selected host.</p>"},{"location":"ezcoo/#additional-step-for-the-usb-20-version-old-eol-version","title":"Additional step for the USB 2.0 version (Old EOL version)","text":"<p>Please remove <code>protocol: 2</code> to the override.yaml under the <code>type: ezcoo</code> at the same level:</p> <pre><code>kvmd:\n gpio:\n drivers:\n ez:\n type: ezcoo\n device: /dev/ttyUSB0\n</code></pre>"},{"location":"ezcoo/#developer-info","title":"Developer info","text":"<ul> <li>The official protocol version 1 reference</li> <li> Differences between protocols 1 and 2 <pre><code>===============================================================================================================================\n=********************************************************Systems HELP*********************************************************=\n=-----------------------------------------------------------------------------------------------------------------------------=\n= System Address = 00 F/W Version : 1.20 =\n= Azz : All Commands start by Prefix System Address zz, if [01-99] =\n=-----------------------------------------------------------------------------------------------------------------------------=\n= EZH : Help =\n= EZSTA : Show Global System Status =\n= EZS RST : Reset to Factory Defaults =\n= EZS ADDR xx : Set System Address to xx {xx=[00~99](00=Single)} =\n= EZS CAS EN/DIS : Set Cascade Mode Enable/Disable =\n= EZS OUTx VS INy : Set Output x To Input y{x=[0~2](0=ALL), y=[1~4]} =\n= EZS IR SYS xx.yy : Set IR Custom Code{xx=[00-FFH],yy=[00-FFH]} =\n= EZS IR OUTx INy CODE zz : Set IR Data Code{x=[1~2],y=[1~4],zz=[00-FFH]} =\n= EZG ADDR : Get System Address =\n= EZG STA : Get System System Status =\n= EZG CAS : Get Cascade Mode Status =\n= EZG OUTx VS : Get Output x Video Route{x=[0~2](0=ALL)} =\n= EZG IR SYS : Get IR Custom Code =\n= EZG IR OUTx INy CODE : Get IR Data Code{x=[1~2],y=[1~4]} =\n= EZS OUTx VIDEOy : Set Output VIDEO Mode =\n= {x=[1~2], y=[1~2](1=BYPASS,2=4K->2K)} =\n=-----------------------------------------------------------------------------------------------------------------------------=\n=Input Setup Commands:(Note:input number(x)=HDMI(x),x=1) =\n= EZS INx EDID y : Set Input x EDID{x=[0~4](0=ALL), y=[0~15]} =\n= 0:EDID_BYPASS 1:1080P_2CH_HDR 2:1080P_6CH_HDR 3:1080P_8CH_HDR =\n= 4:1080P_3D_2CH_HDR 5:1080P_3D_6CH_HDR 6:1080P_3D_8CH_HDR =\n= 7:4K30HZ_3D_2CH_HDR 8:4K30HZ_3D_6CH_HDR 9:4K30HZ_3D_8CH_HDR =\n= 10:4K60HzY420_3D_2CH_HDR 11:4K60HzY420_3D_6CH_HDR 12:4K60HzY420_3D_8CH_HDR =\n= 13:4K60HZ_3D_2CH_HDR 14:4K60HZ_3D_6CH_HDR 15:4K60HZ_3D_8CH_HDR =\n= 16:H4K_DOLBY_VISION_ATMOS =\n= EZG INx EDID : Get Input x EDID Index{x=[0~4](0=ALL)} =\n=-----------------------------------------------------------------------------------------------------------------------------=\n=*****************************************************************************************************************************=\n===============================================================================================================================\n</code></pre> </li> </ul>"},{"location":"ezcoo/#simple-troubleshooting-steps-to-perform","title":"Simple troubleshooting steps to perform","text":"<pre><code> Video Issues:\n Hook a monitor to the output and test\n Reseat the cables\n Change out the cables\n\n Switching issues:\n SSH or open a web terminal to your PiKVM\n `ls -la /dev/ttyUSB*` - This should give you an output. If not, try a different cable till an output is displayed.\n</code></pre>"},{"location":"faq/","title":"FAQ & Troubleshooting","text":"<p>As a first step, we recommend carefully reading our documentation on GitHub or the updated documentation. Most steps to successfully set up your PiKVM are already described there.</p> <p>If you run into any issues you can check this page which will list common errors. If that still doesn't help you you're welcome to raise an issue ticket or contact our Suppor for further help.</p>"},{"location":"faq/#common-questions","title":"Common questions","text":"Where can I get a memory card image for PiKVM? <p>See here: https://pikvm.org/download</p> Can PiKVM work on Raspberry Pi 5? <ul> <li>Not now, but it will. Pi5 does not support hardware video encoding so there is no any reason to use it for PiKVM.</li> <li>RPi5 is not compatible with PiKVM V3 HAT due to the difference in form factor with RPi4.</li> </ul> Can I connect multiple servers to a single PiKVM? <p>Yes, but it requires additional work to set up. See this page.</p> How can I get the access to PiKVM in my local network over Internet? <p>You can use port forwarding for port 443 on your router if it has an external IP address. In all other cases, you can use the excellent free VPN service Tailscale, which can be configured on PiKVM with a few simple commands.</p> Can I assign a static IP to a PiKVM <p>Yes, we highly suggest using this document first for those that are not Linux savvy.</p> <p>[ONLY FOR ADVANCED LINUX USERS]</p> <p>Edit file <code>/etc/systemd/network/eth0.network</code> for Ethernet or <code>wlan0.network</code> for Wi-Fi and edit the <code>[Network]</code> section:</p> <pre><code>[Network]\nAddress=192.168.x.x/24\nGateway=192.168.x.x\nDNS=192.168.x.x\nDNS=192.168.x.x\n</code></pre> <p>Don't forget the <code>/24</code> suffix (CIDR), otherwise it will not work and your PiKVM will become unreachable.</p> How can I disable IPv6 on PiKVM? <p>To do this, you need at least KVMD 3.301 installed on your device. If this is not the case, update the OS.</p> <p>Next, append the <code>ipv6.disable=1</code> parameter to <code>/boot/cmdline.txt</code> and perform <code>reboot</code>.</p> How do I recover my PiKVM, it cannot be reached now <ol> <li>Take the USB-C end cable you have for your target and move to the PiKVM IOIO port or CON port</li> <li>Take the USB-A end cable and put this on the HOST(The controlling PC)</li> <li>Turn on or reboot your PiKVM, you should now see a COMx port on your HOST PC</li> <li>Connect using something like Putty, use 115200 as your baud rate</li> <li>Edit the file using nano or whatever text editor you are comfortable with, save the file</li> <li>Reboot your PiKVM, check for functionality</li> <li>If still unreachable, edit the same file to fix it</li> <li>ONLY Disconnect the IOIO port once you have fully recovered your PiKVM and place this back onto the Target system</li> </ol> Can I use PiKVM for gaming? <p>No, because:</p> <ul> <li>For HDMI-CSI bridge, bus bandwidth is not enough to transmit more than 1080p50.</li> <li>For HDMI-USB dongle, high latency and low video quality.</li> <li>General hardware video capture differs from software streaming and introduces additional latency.</li> </ul> Can PiKVM do 4K video? <ul> <li>For HDMI-CSI bridge, no. There is not enough bandwidth in the CSI bus for that much data. 1080p50 will max out the bandwidth.</li> <li>For the USB capture devices: technically yes, they will down sample to something smaller to meet the USB 2.0 bandwidth limitations, so the source may be 4k, but the stream will not.</li> <li>The 4K real-time video will not fit through the network anyway.</li> </ul> Where does the cursor/video latency come from? <p>Here is the chain of transferring an image to your browser or VNC client.</p> <p><code>Capture device -> Compression -> Network -> Decompression -> Rendering</code></p> <p>100-200ms is very, very fast for this. But we are working to speed things up even more.</p> I am expecting to see 60fps and I am not, why? <p>PiKVM receives the entire signal, but then the encoding is the bottleneck. For 1080p, this is no more than 30 fps. V4 throws out every second frame of 60 hz/fps, and 30 fps is encoded. V3 and DIY can't process 60 hz and is only able to capture 50 hz, and in the same way they take every second frame, all you get out is 25 fps. The reason why V3 and DIY does not encode 30 out of 50 is that the picture will be jerky, but smooth at 25.</p> Does PiKVM support sound? <p>Yes but the only officially supported version is the PiKVM V3+ devices, V2 we will attempt best effort but ultimately we do not support CSI modules or USB.</p> Can I power the Pi via PoE? <p>Yes! </p> <p>For a POE HAT</p> <p>You still need a splitter to ensure you isolate the 5v connection between the Raspberry Pi and host PC to prevent back power issues that can cause instability or damage to either the host PC or the Pi. Power/Data cable + USB power blocker would work.</p> <p>For a POE Splitter</p> <p>No, there is no need for anything additional, you can power your RPi and or the PiKVM Mini with the USB-C variant.</p> Do I need a power splitter? Why do I need one? <ul> <li>Yes for RPi4 - Please see the main v2 document for splitter types listed under V2 hardware</li> <li>Yes for Zero W and Zero W 2, if using dedicated power you still need to split the power from the data towards the target. If using the target for power, this is not needed.</li> <li>This is not needed if you have a PiKVM V3 and V4, as they splits power and signal on the board.</li> </ul> Can I use PiKVM with non-Raspberry Pi boards (Orange, Nano, etc)? <p>Yes, but you will have to prepare the operating system yourself. For the PiKVM software, you will need to replace some config files (such as UDEV rules). If you are a developer or an experienced system administrator, you will not have any problems with this. In addition, we are open to patches. If you need help with this, please contact us via Discord (#unofficial_ports channel).</p> Is PiKVM OS its own custom distro? <p>No. PiKVM OS is an Arch Linux ARM with our own repository for KVM-related packages. We distribute OS images (that is, our Arch Linux ARM build) to simplify installation, since PiKVM requires some tuning of the OS and special partitioning of the memory card.</p> Why is PiKVM OS based on Arch Linux ARM and not Raspbian / Raspberry Pi OS? <p>There are several reasons:</p> <ul> <li>Several years ago, when PiKVM was just starting out, Raspbian didn't have a minimalistic image and the transition to systemd was in full swing, which is why the distribution was not too stable.</li> <li>Raspbian did not have all the necessary packages in the repositories to satisfy most software dependencies.</li> <li>PiKVM was born as a pet project, and the founder likes Arch the most.</li> </ul> <p>However, we plan to provide an alternative OS image based on Raspberry Pi OS in the future - now it is quite stable.</p> Can I use an iPad on PiKVM? <ul> <li>Yes, with the correct hardware you can control an iPad.</li> <li>In the opposite sense - yes, use VNC and use JUMP app (fully-featured but more expensive), or bVNC (cheap). RealVNC does NOT work.</li> </ul> How do I add my own SSL cert? <p>If you have a certificate (making a cert falls outside the scope of PiKVM - please reference OpenSSL documentation or use Let's Encrypt), replace keys in <code>/etc/kvmd/nginx/ssl</code>, edit <code>/etc/kvmd/nginx/ssl.conf</code> if necessary and restart <code>kvmd-nginx</code> service.</p> How do I emulate various USB devices on the target machine? <p>For a detailed description, see here.</p> <p>Use the following USB database to get the desired devices: https://the-sz.com/products/usbid or https://devicehunt.com.</p> Can I run a desktop on PiKVM? <p>Yes, but it's strongly not recommended OR supported as this OS should be used in read-only mode and it will need read-write enabled all of the time, however if you insist on running one, instructions are here.</p> How do I blank the oled screen? <p>Please run the following: </p><pre><code># systemctl disable --now kvmd-oled kvmd-oled-reboot kvmd-oled-shutdown\n# kvmd-oled --height=32 --interval=0 --clear-on-exit --text=x\n</code></pre> To re-enable the display: <pre><code># systemctl enable --now kvmd-oled kvmd-oled-reboot kvmd-oled-shutdown\n</code></pre> How do I rotate the OLED display? <p>Please run the following: </p><pre><code>1. mkdir -p /etc/systemd/system/kvmd-oled.service.d\n2. Create file /etc/systemd/system/kvmd-oled.service.d/override.conf:\n[Service]\nExecStart=\nExecStart=/usr/bin/kvmd-oled --height=32 --clear-on-exit --rotate=2\n</code></pre> I am getting a 500/503 error when I try and access the main KVM page! <p>This maybe due to a few of the following:</p> <ul> <li>Missing <code>/etc/kvmd/override.yaml</code> file, to resolve it run <code>rw; touch /etc/kvmd/override.yaml; ro</code></li> <li>Bad YAML syntax, edit your <code>/etc/kvmd/override.yaml</code> file and undo what you did and restart PiKVM.</li> </ul> How can I use the serial console to gain access to other devices <p>You need to stop the service which listens on the <code>/dev/ttyAMA0</code>:</p> <pre><code>rw\nsystemctl stop serial-getty@ttyAMA0.service\n</code></pre> <p>If you want this change permanent (not starting again after reboot), you can disable this service, ('enable' to reverse this decision):</p> <pre><code>systemctl disable serial-getty@ttyAMA0.service\n</code></pre> <p>Note</p> <ul> <li>Only USB OR the RJ-45 serial connector will work, you can't use them together!</li> <li>If you disable the service permanently, you can't recover your device via serial console if you need this.</li> <li>There are some reports, that you need to remove <code>ttyAMA0</code> from /boot/cmdline.txt, but this is not needed on new installations.</li> </ul> Can I run PiKVM in a docker? <p>No, technically it might be possible but the OS requires many specific settings that cannot be performed inside the container.</p> How can I change the HTTP/HTTPS ports? <p>To do this, you need at least KVMD 3.301 installed on your device. If this is not the case, update the OS.</p> <p>Add some of these lines to <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>nginx:\n https:\n port: 4430\n http:\n port: 8080\n</code></pre> <p>After that, restart the server: <code>systemctl restart kvmd-nginx</code>.</p> Can I control IR devices using PiKVM? <p>This goes far beyond the usual use of PiKVM, so there is no official way to do this, but there are some ways from the community that you can try if you know how to handle a soldering iron.</p>"},{"location":"faq/#first-steps","title":"First steps","text":"I can't find the PiKVM IP address in my network <p>Follow the device guide of your PiKVM here.</p> What is the default password? How do I change it? <p>See here.</p> How do I add another user? <p>See here.</p> How do I get root access in the web terminal? <p>See here.</p> Where is the PiKVM configuration located? <p>Almost all KVMD (the main daemon controlling PiKVM) configuration files are located in <code>/etc/kvmd</code>. You can also find nginx configs and SSL certificates there. KVMD configs use YAML syntax. The specific platform parameters can be found in the file <code>/etc/kvmd/main.yaml</code> and you should never edit it. Use <code>/etc/kvmd/override.yaml</code> to redefine the system parameters.</p> <p>Files that are not recommended for editing have read-only permissions. If you edit any of these files, you will need to manually make changes to them when you upgrade your system. You can view the current configuration and all available KVMD parameters using the command <code>kvmd -m</code>.</p> I can't edit any file on PiKVM. Why is the system in read-only mode? <p>The PiKVM file system is always mounted in read-only mode. This measure prevents it from being damaged by a sudden power outage. To change the configuration you must first switch the filesystem to write mode using the command <code>rw</code> from root. After the changes, be sure to run the command <code>ro</code> to switch it back to read-only. If you get a message that the file system is busy, then the easiest way is to perform a <code>reboot</code>.</p> I want to get read-write filesystem all of the time <p>DON'T DO THIS</p> <p>DON'T DO THIS</p> <p>DON'T DO THIS</p> <p>Seriously, DON'T. Read-only mode increases the life of the memory card and protects the filesystem from power loss failures. See the question above ^ ^ ^</p> <p>You can turn it off, but don't say you weren't warned.</p> DON'T OPEN THIS SPOILER AND DON'T DO THIS <p>Okay, fine.</p> <ul> <li>Edit <code>/boot/cmdline.txt</code> and change option <code>ro</code> to <code>rw</code>.</li> <li>Do the same in <code>/etc/fstab</code> for the <code>/boot</code> partition.</li> <li>Comment <code>tmpfs</code> lines in <code>/etc/fstab</code> for <code>/var/lib</code> and <code>/var/log</code>.</li> </ul> <p>But again: DON'T DO THIS</p> <p>If you do plan on doing this, no assistance will be provided beyond this point other than the existing documentation.</p> How to set the date, time and timezone from command line? <ul> <li>Become root with the command <code>su -</code> or <code>sudo -s</code>.</li> <li>Enable read/write with the command <code>rw</code>.</li> <li>Find your timezone string e.g. <code>timedatectl list-timezones</code> or <code>timedatectl list-timezones | grep -i australia</code>.</li> <li>Set the timezone with <code>timedatectl set-timezone <YourTimeZoneHere></code> e.g. <code>timedatectl set-timezone Australia/Victoria</code>.</li> <li>Stop the time syncing service with <code>systemctl stop systemd-timesyncd</code> as this will prevent the next step if running.</li> <li>Set the time and date with <code>timedatectl set-time 'YYYY-MM-DD HH:MM:SS'</code> e.g. <code>timedatectl set-time '2023-02-26 14:50:10'</code>.</li> <li>If you have hardware clock e.g. V3+, update it with <code>hwclock --systohc</code> , then check it with <code>hwclock --show</code>.</li> <li>Switch filesystem to RO-mode with the command <code>ro</code>.</li> </ul> How do I update PiKVM with the latest software? Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> How do I install or remove packages in PiKVM OS? <p>PiKVM OS is based on Arch Linux ARM and uses the pacman package manager.</p> <ul> <li>Ensure the date is correct: <code>date</code>. Otherwise you may get the error <code>SSL certificate problem: certificate is not yet valid</code></li> <li>It is recommended to update the OS before installing new packages (see the tip upper ^^^).</li> <li>Switch filesystem to RW-mode: <code>rw</code>.</li> <li>Find some packages (<code>emacs</code> for example): <code>pacman -Ss emacs</code>.</li> <li>Install it: <code>pacman -Syy</code> to update local packages list and <code>pacman -Su emacs</code> to install.</li> <li>Remove it: <code>pacman -R emacs</code>.</li> <li>Switch filesystem to RO-mode: <code>ro</code>.</li> </ul> I don't need ATX functions. How do I disable this in the Web UI? <p>If you don't need ATX power control you can disable the relevant Web UI menu in <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>kvmd:\n atx:\n type: disabled\n</code></pre> <p>... then restart <code>kvmd</code>:</p> <pre><code># systemctl restart kvmd\n</code></pre> How do I disable the web terminal? <pre><code># rw\n# systemctl disable --now kvmd-webterm\n# ro\n</code></pre> How do I completely disable authorization in PiKVM? <p>See here.</p> Can I have different hostnames for each of my PiKVMs? <p>Yes! And it's easy to do! Using a SSH session or the web terminal: * Make sure you are root, run <code>rw</code> then run <code>hostnamectl set-hostname yournewhostname.domain</code>. * Optional: edit <code>/etc/kvmd/meta.yaml</code> to alter the displayed hostname in the web UI. * Run <code>ro</code> and <code>reboot</code>.</p> Why not add software support for another codec? <p>Encoding is a heavy process and will add significant latency, its best to have hardware support to avoid additional latency.</p>"},{"location":"faq/#video-problems","title":"Video problems","text":"I can see the video but I can't see the WebRTC / video mode switch <p>WebRTC and Direct H.264 modes are only available on V2+ platforms with HDMI-CSI capture device, including PiKVM V3 or V4 Plus/Mini. See the modes guide to solve any problems.</p> PiKVM does not show the video from the computer at all <ul> <li>Double-check that the video capture device is connected correctly.</li> <li>Some laptops do not output any signal until you switch the output (usually via the FN + and an F5 key on the keyboard).</li> <li>Your computer may have turned on sleep mode for the monitor. Move the mouse to turn it off.</li> <li>For windows you might need to check for the active signal resolution. To change the active signal resolution you have to go to Settings>System>Display>Advanced display settings>Display adapter properties then, click \"List All Models\" and choose the one you want. Keep trying different Hz settings.</li> </ul> The video works in the booted OS, but not in the BIOS/UEFI <p>This problem appears on Intel NUC, GA-H77-DS3H, and some other devices when using a CSI bridge. All you need to do is change the EDID data. This is the information about supported resolutions that the CSI bridge reports to your computer.</p> Glitchy or wrong BIOS/UEFI resolution <p>On some motherboards, the BIOS may be displayed at a lower resolution, or with some rendering issues/glitches, specially on newer ASUS ones. Like this:</p> <p></p> <p>This can be solved by enabling the Compatibility Support Module (CSM) in your BIOS, usually under the Boot options.</p> <p>If you can't or don't want to enable the CSM, you can try connecting a DisplayPort (DP) monitor, or a dummy plug. If you remove the DP cable/adapter the bug will reappear.</p> <p>If none of this works, try connecting the DP cable first, boot into the BIOS, disable the CSM and shutdown (do not restart) your PC. Then, boot into the BIOS and enable the CSM before shutting down your PC. Then connect the HDMI and turn your PC on again.</p> There is no video in GRUB2, but there is before and after <p>Sometimes this can be caused by the specifics of the BIOS/UEFI and how GRUB2 works with video.</p> <p>This can be solved by enabling the Compatibility Support Module (CSM) in your BIOS, usually under the Boot options. The video mode will be located in the same section. Switch the Video mode from UEFI to Legacy.</p> Why does the CSI bridge does not work with official Raspberry Pi PoE HAT? <p>Details here. The reason is that the official HAT has a built-in fan controller that conflicts with the TC358743 chip of the bridge. The solution is to disable the fan control and connect the fan to the power line so that it works continuously. To turn off the controller you need to add the line <code>disable_poe_fan=1</code> to <code>/boot/config.txt</code>.</p> The video freezes a few seconds after the start, restarting the Web UI or VNC does not help <p>The story is here. Very very rarely, Raspberry Pi boards can have a hardware defect that causes some of the chip blocks to be unstable under normal power. The solution is to slightly increase the power supply, as you would when overclocking. Add <code>over_voltage=1</code> (or <code>over_voltage=2</code> if previous doesn't help) to <code>/boot/config.txt</code> and perform <code>reboot</code>.</p> <p>To make sure that you are facing this particular problem, first perform a diagnostic:</p> <ul> <li>Boot the PiKVM without the specified options.</li> <li>Open Web-UI and wait for freezing.</li> <li>Click <code>System -> Reset Stream</code>.</li> <li>Click <code>System -> Open log</code> and make sure that the log contains messages like <code>H264: Can't wait for the VCOS semaphore</code>.</li> <li>Make sure that the last message from ustreamer was <code>H264: Configuring MMAL encoder</code> (not counting messages about connecting and disconnecting stream clients).</li> </ul> No image from computer with Linux + Awesome WM <p>Sometimes Awesome WM on Linux can't recognize a video output change on a cable. That is, if the cable was first inserted into the monitor, and then you reconnected it to PiKVM - it may happen that you will not see the image. It seems that the problem is Awesome WM, since for example with KDE, it is not reproducible. If you turn on your workstation with PiKVM already connected, everything will work fine.</p> Windows shows limited Available Resolutions <p>This is due to a driver issue. A possible resolution can be found here.</p> Firefox ESR from the Debian repo shows the black screen in H.264 mode <p>Make sure the OpenH264 Plugin both exists and is enabled (known issue on Debian GNU/Linux). Press <code>Ctrl+Shift+A</code> to open the Add-ons Manager, then press <code>Plugins</code>. You should see OpenH264 Video Codec provided by Cisco Systems, Inc.. Make sure it is enabled by pressing the \"more options\" button (3 horizontal dots), then pressing <code>Always Activate</code>.</p> Apple TB/USB-C HDMI video doesn't work <p>A possible solution can be found here.</p> I am seeing a NO SIGNAL, what can I do? <p>If you are using PiKVM V2 or a V3, you need to ensure that your target is using the maximum resolution 1920x1080@50Hz, 60Hz will not work.</p> <p>If you are using the PiKVM V4, ensure that you are getting a signal out from the target by using a physical monitor using the same exact cable/dongle, ensure that you are using the maximum resolution 1920x1200@60hz, 2K/4K resolutions will not work.</p>"},{"location":"faq/#usb-problems-keyboard-mouse-mass-storage-etc","title":"USB problems (keyboard, mouse, mass storage, etc)","text":"My computer does not recognize USB of PiKVM V2+ at all <ul> <li>Make sure that you have used the correct USB cable with DATA lines to connect the OTG port for the Raspberry to the computer. You may have decided to use a USB hub instead of a Y-cable and it won't work. Use good cables and follow the instructions :)</li> <li>In rare cases, some very buggy BIOS's do not like HID and Mass Storage in one USB device. You can either disable Mass Storage, or use the Pico HID to physically separate them.</li> </ul> BIOS/UEFI does not recognize USB of V2+, but computer does <p>If you are using a USB hub or USB PCI controller, this may not be handled by your BIOS. Try to use another USB port. Some ports may have a built-in hub on the motherboard and a buggy BIOS that can't handle it.</p> My keyboard works in BIOS/UEFI, but my mouse does not <p>The BIOS does not support absolute mouse mode, which is preferred by PiKVM. In this case, you can enable relative or dual positioning mode.</p> My mass storage drive works (I can boot an image from PiKVM V2+), but my keyboard/mouse does not <p>In rare cases, some very buggy BIOS's does not like HID and Mass Storage in one USB device. You can either disable Mass Storage, or use the Pico HID to physically separate them.</p> Buggy absolute mouse on Windows 98 as managed server <p>How to fix:</p> <ul> <li>V2+.</li> <li>Pico HID.</li> </ul> The mouse does not work with NVR/DVR CCTV <p>Often these devices have a buggy USB driver that does not understand an absolute mouse and/or a mouse with horizontal scrolling. In this case, the following configuration for <code>/etc/kvmd/override.yaml</code> will help you:</p> <pre><code>kvmd:\n hid:\n mouse:\n absolute: false\n horizontal_wheel: false\n mouse_alt:\n device: \"\"\n</code></pre> <p>It will make the relative mouse without horizontal scrolling the only mice.</p> There's big mouse latency on another Raspberry Pi as managed server <p>Unusual case: RPi4 is used as a PiKVM to control RPi3. In this case, the mouse delay may be several seconds. To fix it, append <code>usbhid.mousepoll=0</code> to the boot line in <code>/boot/cmdline.txt</code> on the managed server (i.e. RPI3 in our case) and reboot it. Source.</p> What speed is the USB OTG port? <p>Per the official RPI documentation, this is a limitation of the SoC. The OTG port is only USB2.0, so is limited to 455 Mbit/s.</p> On MacOSX, my mouse/keyboard does not work! <p>There are a few fixes the community has suggested:</p> <p>If using a USB-C to USB-C cable, you need to use the included USB-C to USB-A cable then use a USB-A to USB-C adapter</p> <p>You may need to allow new accessories to connect. Source</p>"},{"location":"faq/#web-ui-problems","title":"Web UI problems","text":"Chrome reports a Certificate Issue when I try to access the PiKVM web interface <p>The latest versions of Chrome do not allow access to the page with a self signed certificate, so if you see the following screen when loading the PiKVM website:</p> <p></p> <p>You can proceed by typing <code>thisisunsafe</code> and Chrome will then load the page. Also see Let's Encrypt page.</p> Pressing ESC in full screen mode causes the PiKVM page to close <p>Your browser does not support keyboard lock. Right now (January 2022), only Chromium implements this, so it works on Chrome, Edge, and Opera.</p> The Web UI doesn't work properly in Firefox while it works fine in Chrome <p>This might be related to your specific hardware combination or browser hardware acceleration. Try disabling hardware acceleration in Firefox or updating your GPU and chipset drivers.</p> Unexpected interruption while loading the image for Mass storage drive <p>If problems occur when uploading even a small disk image it may be due to unstable network operation or antivirus software. It is well known that Kaspersky antivirus cuts off PiKVM connections during uploading, so you should add the PiKVM website to Kaspersky's list of exceptions or not filter web requests with the antivirus. Antivirus programs can also affect the performance of certain interface elements, for example the quality slider. For Kaspersky, the steps to add the network address of PiKVM's website to the exclusion list is: <code>Protection -> Private browsing -> Categories and exclusions -> Exclusions</code>.</p> I can't click on anything when using the WebGUI on my phone <p>At this time, iOS has the buttons on the bottom if you have the correct resolution, sometimes you cannot see them due to the resolution. At this time, android is not supported, our suggestion is to use a VNC client.</p> I changed the Display Resolution to 720p but Windows still shows 1080p and the display looks blurry <p>This is mostly seen on Windows, open <code>Display Settings -> Advanced display settings -> Display adapter setting for Display 1 -> List all modes -> (Toggle between 720p30hz back to 50hz)</code>, this may need to be done if you need to change it back for 1080p.</p>"},{"location":"faq/#hardware-problems-wi-fi-atx-etc","title":"Hardware problems (Wi-Fi, ATX, etc)","text":"I can't connect to Wi-Fi on a Raspberry Pi Zero W <ul> <li>Some Zeros contain a defective Wi-Fi chip. You can either return the device to the store, or try the software workaround.</li> </ul> I can't connect to Wi-Fi at all! <ul> <li> <p>If your device is unable to connect to the Wi-Fi network that you have set up, check the 2.4 GHz Wi-Fi channel used by your Wi-Fi access point. </p> </li> <li> <p>If channels 12 to 14 are used (some countries have banned these channels) try to use a channel between 1 and 11.</p> </li> </ul> LEDs/Switches do not work in ATX control <p>Double check your wiring. Make sure you placed the relays (G3VM-61A1) in the correct orientation. The relays for switches (Power, Reset) have a different orientation than the ones for LEDs.</p> My PiKVM keeps disconnecting from the Wi-Fi network <p>Try to edit <code>/etc/conf.d/wireless-regdom</code> and look for your region and uncomment it. For example: <code>WIRELESS_REGDOM=\"US\"</code>.</p> PiKVM complains about low power warnings <ul> <li>Are you using a \"proper\" power supply? Not one you hacked together?</li> <li>Some USB power bricks advertise 5V 2.1A or higher, but can't deliver consistent 5V. Best to use Raspberry Pi Foundation recommended power supplies.</li> </ul> PiKVM complains about a RTC low voltage detected, date/time is not reliable <ul> <li>This is mearly a warning that can be ignored however, the following resolves the issue:</li> <li>Leave plugged in for 24+ hours and or</li> <li>Connect to the internet using the eth cable, the internal NTP service will set the time accordlingly</li> <li>Force a time sync: <code>rw && hwclock --systohc\"</code> or <code>\"rw && hwclock -w\"</code></li> <li>Set date and time manually can be found here.</li> </ul>"},{"location":"flashing_hid/","title":"Flashing hid","text":"<p>Legacy warning</p> <p>This page describes the legacy keyboard and mouse emulator used in old DIY builds. There is no point using it today because there is a more modern and better replacement for the new Pico HID. This one can also serve as an in-place compatible replacement for the Arduino HID in the old build.</p>"},{"location":"flashing_hid/#flashing-the-arduino-hid","title":"Flashing the Arduino HID","text":""},{"location":"flashing_hid/#note-for-the-recent-images","title":"Note for the recent images","text":"<p>Current image no longer ships with necessary tools for flashing Arduino HID, therefore please install <code>platformio-core</code> and <code>avrdude</code> and continue:</p> <pre><code>pacman -Syu\npacman -S platformio-core avrdude\n</code></pre>"},{"location":"flashing_hid/#serial-firmware-the-default-option","title":"Serial Firmware (the default option)","text":"<p>This operation can be done using your RPi (except Pi Zero W). Here the common steps:</p> <ol> <li> <p>Disconnect the RESET wire from the Arduino board.</p> </li> <li> <p>Connect the Arduino and RPi with a suitable USB cable.</p> </li> <li> <p>Log in to the Raspberry Pi console using SSH or Web Terminal.</p> </li> <li> <p>Upload the firmware (USB keyboard & mouse is used by default, on this step you can choose PS/2 keyboard):</p> <pre><code># rw\n# systemctl stop kvmd\n# cp -r /usr/share/kvmd/hid/arduino ~\n# cd ~/arduino\n# make\n# make install\n# reboot\n</code></pre> </li> <li> <p>Connect the RESET wire, disconnect the USB cable, and reboot the RPi.</p> </li> </ol> <p>With a Pi Zero W, you may consider building the firmware on a faster system and programming using USB or booting from another SD card and following the build steps using a clone of the KVMD repo.</p>"},{"location":"flashing_hid/#spi-firmware","title":"SPI Firmware","text":"<p>This operation can be done using your Raspberry Pi without disconnecting any wires:</p> <ol> <li> <p>Connect the Arduino and RPi with a suitable USB cable.</p> </li> <li> <p>Log in to the Raspberry Pi console using SSH or Web Terminal.</p> </li> <li> <p>Execute <code>rw</code>, add line <code>dtoverlay=spi0-1cs</code> to <code>/boot/config.txt</code> and perform <code>reboot</code>.</p> </li> <li> <p>Build and upload the firmware (USB keyboard & mouse is used by default)</p> <pre><code># rw\n# systemctl stop kvmd\n# cp -r /usr/share/kvmd/hid/arduino ~\n# cd ~/arduino\n# make spi\n# make install\n# reboot\n</code></pre> </li> </ol>"},{"location":"flashing_hid/#common-errors","title":"Common Errors","text":""},{"location":"flashing_hid/#circuit-issues","title":"Circuit Issues","text":""},{"location":"flashing_hid/#common-reset-wire","title":"Common - Reset Wire","text":"<p>Different pins are used for the reset wire but serve a similar function. For programming the TTL firmware over USB, the reset wire should be disconnected. When programming using SPI, the reset wire needs to be connected through a transistor circuit and connected to GPIO25 (pin 22 on the GPIO header)</p>"},{"location":"flashing_hid/#spi-specific-wiring","title":"SPI-specific Wiring","text":"<p>The 3v3, ground, Reset (GPIO25), MISO, MOSI, SCLK, and CS1 need to be connected appropriately. SPIO_CS0 and SPIO_CS1 can both be used but the default configuration uses SPIO_CS1 for the Arduino Microcontroller (CS0 is used for another device on the V3). These generally follow a block as follows:</p> <pre><code>Pin 0 2 4\n 2 0 0\n .........GR.C.......\nRow # 12345678901234567890\n ........3MMS........\nPin 0 1 3\n 1 7 9\n</code></pre> <p>The most common error is an \"off-by-one\" error where pins are shifted by a row. Some cases have non-standard GPIO layouts so please be careful when following these instructions using a case that has a modified pinout.</p>"},{"location":"flashing_os/","title":"Flashing PiKVM OS image","text":"<p>Micro-SD Card Requirements</p> <p>Minimum 32 Gb, Class 10 recommended.</p>"},{"location":"flashing_os/#download-the-image","title":"Download the image","text":"<p>Download the appropriate SD card image. Select it based on the board, platform, and the video capture device you are using.</p> <p>Official PiKVM Devices</p> <p>These images are not suitable for DIY and are intended only for our branded devices.</p> <ul> <li> <p>PiKVM V4 <sub>64-bit</sub></p> <ul> <li>PiKVM V4 Mini <sub>- sha1</sub></li> <li>PiKVM V4 Plus <sub>- sha1</sub></li> </ul> </li> <li> <p>PiKVM V3 <sub>64-bit</sub></p> <ul> <li>PiKVM V3 HAT BOX Image, OLED/FAN preactivated <sub>- sha1</sub></li> <li>PiKVM V3 HAT DIY Assembly <sub>- sha1</sub></li> </ul> </li> </ul> <p>DIY PiKVM V2 Platform</p> <ul> <li> <p>Raspberry Pi 4 <sub>64-bit</sub></p> <ul> <li>For HDMI-CSI bridge <sub>- sha1</sub></li> <li>For HDMI-USB dongle <sub>- sha1</sub></li> </ul> </li> <li> <p>Raspberry Pi Zero 2 W <sub>32-bit</sub></p> <ul> <li>For HDMI-CSI bridge <sub>- sha1</sub></li> </ul> </li> </ul> <p>DIY PiKVM V1 Platform</p> <ul> <li> <p>Raspberry Pi 3 <sub>32-bit</sub></p> <ul> <li>For HDMI-CSI bridge <sub>- sha1</sub></li> <li>For HDMI-USB dongle <sub>- sha1</sub></li> </ul> </li> <li> <p>Raspberry Pi 2 <sub>32-bit</sub></p> <ul> <li>For HDMI-CSI bridge <sub>- sha1</sub></li> <li>For HDMI-USB dongle <sub>- sha1</sub></li> </ul> </li> <li> <p>Raspberry Pi Zero 2 W <sub>32-bit</sub></p> <ul> <li>For HDMI-CSI bridge <sub>- sha1</sub></li> <li>For HDMI-USB dongle <sub>- sha1</sub></li> </ul> </li> </ul> <p>Any other combinations for advanced users</p> <p>Please check the file archives for ready-made image or build the image yourself.</p>"},{"location":"flashing_os/#flashing-the-image","title":"Flashing the image","text":"<p>Tip</p> <p>After inserting the memory card into your computer, ignore request to format. This is not nessessary.</p>"},{"location":"flashing_os/#using-linux-cli-advanced-users","title":"Using Linux CLI (ADVANCED USERS)","text":"<p>Decompress (if nessessary) and flash the image. Be careful when choosing the device path, it may be different on your machine:</p> <pre><code>[user@localhost]$ xz --decompress v2-hdmi-rpi4-latest.img.xz\n[user@localhost]$ sudo dd if=v2-hdmi-rpi4-latest.img of=/dev/mmcblkX\n</code></pre> <p>You can also use <code>dd_rescue</code> or <code>ddrescue</code>.</p>"},{"location":"flashing_os/#using-rpi-imager-linux-macos-and-windows","title":"Using RPi Imager (Linux, MacOS and Windows)","text":"<ol> <li> <p>Download and install the latest version of RPi Imager.</p> </li> <li> <p>Run RPi Imager:</p> <p></p> </li> <li> <p>Press NO FILTERING then CHOOSE OS and select Use custom image at bottom of the list:</p> <p></p> </li> <li> <p>After clicking on this item, select the image file (<code>*.img</code> or <code>*.img.xz</code>), then click CHOOSE STORAGE:</p> <p>Warning</p> <p>This should already be set to blank though the flashing process from step 7 but its best to double check the advanced settings (<code>CTRL+SHIFT+X</code>), make sure they are blank or the flash will fail.</p> <p></p> </li> <li> <p>Insert the memory card into the card reader. Choose the card reader from this list. Be careful and choose the right device:</p> <p></p> </li> <li> <p>After choosing the memory card, press the WRITE button. Confirm the operation when you are asked about it:</p> <p></p> </li> <li> <p>Refuse customization options.</p> <p>Warning</p> <p>The customization is designed for Raspberry OS and will not work in PiKVM OS. If you apply any custom settings, this will cause the image to malfunction.</p> <p>PiKVM OS has its own settings mechanism, please use it after the flashing if you need to configure Wi-Fi or something similar.</p> <p></p> </li> <li> <p>Wait for the process to finish. Get yourself a coffee or do some stretching :) The process may hang at 99% for a long time, this is okay, just wait for it to complete.</p> <p></p> </li> <li> <p>Remove the memory card after successful completion. If an error occurs during flashing or booting PiKVM, repeat the process. If the error persists, use a different memory card.</p> </li> </ol>"},{"location":"gpio/","title":"GPIO","text":"<p>GPIO (general-purpose input/output) is a series of digital interfaces that can be used to connect relays, LEDs, sensors, and other components.</p> <p>Warning</p> <ul> <li>Before using GPIO on PiKVM v3 HAT, carefully study the purpose of its ports.</li> <li>Using GPIO on a PiKVM was designed as a feature for advanced users, so please familiarize yourself with the topic to make sure you understand how to use use it before setting it up.</li> <li>Careless usage of GPIO can damage your Raspberry Pi or components.</li> </ul> <p>When talking about PiKVM and GPIO it refers not solely to the physical interface of the Raspberry Pi, but also to various plugins (for example, for USB relays) that can also be used transparently by emulating an abstract GPIO API.</p>"},{"location":"gpio/#basics","title":"Basics","text":"<p>Setting up GPIO is considerably complex. The interface is divided into several layers for flexibility. Any configuration is performed using a file <code>/etc/kvmd/override.yaml</code> which uses the YAML syntax. We will look at each part of the configuration individually with an example for each. Sections should be combined under shared keys.</p> <ul> <li> <p>Wrong:</p> <pre><code>kvmd:\n gpio:\n drivers: ...\nkvmd:\n gpio:\n scheme: ...\n</code></pre> </li> <li> <p>Correct:</p> <pre><code>kvmd:\n gpio:\n drivers: ...\n scheme: ...\n</code></pre> </li> </ul>"},{"location":"gpio/#drivers","title":"Drivers","text":"<p>The first part of the configuration refers to the hardware layer, which defines which IO channels are used (standard GPIO pins of the Raspberry Pi, an USB relay, and so on). If you just want to use GPIO with the default settings you can skip to the next section Scheme.</p> <p>Each hardware input/output requires a individual driver configuration entry. Each driver has a type (which refers to the plugin that handles the communication between PiKVM and the hardware) and a unique name. This allows you to either can add multiple drivers of the same type with different settings or connect multiple USB HID relays.</p> <p>Note</p> <p>Each driver requires a unique name. Names surrounded by double underscore are system reserved and should not be used.</p> <p>The only exception to this is the default GPIO driver with the name <code>__gpio__</code>, representing the physical GPIO interface of the Raspberry Pi. The configuration section for <code>__gpio__</code> is only required in your <code>/etc/kvmd/override.yaml</code> if you want to change the default settings. It can be omitted if you are fine with the defaults.</p> <pre><code>kvmd:\n gpio:\n drivers:\n # This example shows how the default __gpio__ driver settings can be changed. It can be omitted if you are fine with the defaults.\n __gpio__: # Names surrounded by double underscore are system reserved\n type: gpio # Refers to the plugin name handling the communication\n\n # You can define another gpio driver for some reason\n my_gpio: \n type: gpio\n\n # Example for a USB HID relay connected to PiKVM\n relay:\n type: hidrelay\n device: /dev/hidraw0 # The path to the linux device\n</code></pre>"},{"location":"gpio/#scheme","title":"Scheme","text":"<p>The second part defines how the various driver channels are configured. Each channel has a unique name, a mode (<code>input</code> or <code>output</code>), a pin number, and a reference to the driver configured in the previous part.</p> <p>Note</p> <p>Names that starts and ends with two underscores (like <code>__magic__</code>) are reserved.</p> <p>Two interaction modes are available for outputs: <code>pulse</code> and <code>switch</code>. In pulse mode, the output quickly switches its state to logical 1 and back (just like pressing a button). In switch mode, it saves (toggles) the state that the user set. When PiKVM is started/rebooted (any time the KVMD daemon is started or stopped) all output channels are reset to 0. This can be changed using the <code>initial</code> parameter. For example, <code>initial=true</code> for logic 1 on startup.</p> <p>If you don't specify a driver for the channel in the scheme the default driver, <code>__gpio__</code> will be used.</p> Parameter Type Allowed values Default Description <code>led1</code>, <code>button1</code>, <code>relay1</code>, etc. <code>string</code> <code>a-Z</code>, numbers, <code>_</code>, <code>-</code> A section for the named channel <code>driver</code> <code>string</code> <code>a-Z</code>, numbers, <code>_</code>, <code>-</code> Optional, Name of the section defined above in <code>Drivers</code> if not GPIO <code>pin</code> <code>integer</code> <code>X >= 0</code> Refers to a GPIO pin or driver's pin/port <code>mode</code> <code>enum</code> <code>input</code> or <code>output</code> Defines if a channel is used for input or output, may be limited by driver plugin Input only <code>debounce</code> <code>float</code> <code>x >= 0</code> <code>0.1</code> Debounce time in seconds. <code>0</code> for disable debounce Output only <code>switch</code> <code>bool</code> <code>true</code> or <code>false</code> <code>true</code> Enables or disables the switch mode on the channel (enabled by default). <code>initial</code> <code>nullable bool</code> <code>true</code>, <code>false</code> or <code>null</code> <code>false</code> Defines the initial state of the switch upon boot, <code>null</code> for don't make changes (the last one does not supported by generic GPIO) <code>inverted</code> <code>bool</code> <code>true</code> or <code>false</code> <code>false</code> Inverts the active logical level <code>pulse</code> A section header to define switch pulse configuration <code>delay</code> <code>float</code> <code>X >= 0</code> <code>0.1</code> Defines the pulse time in seconds, <code>0</code> for disable pulsing <code>min_delay</code> <code>float</code> <code>X >= 0.1</code> <code>0.1</code> <code>max_delay</code> <code>float</code> <code>X >= 0.1</code> <code>0.1</code> <pre><code>kvmd:\n gpio:\n scheme:\n # A certain device sends signals to the RPi and we want the PiKVM to display this as an led\n led1:\n pin: 19 # GPIO pin number on the RPi\n mode: input \n led2:\n pin: 16\n mode: input \n\n # Two outputs of RPi's GPIO\n button1:\n pin: 26 # GPIO pin number on the RPi\n mode: output\n switch: false # Disable switching, only pulse available\n button2:\n pin: 20\n mode: output\n switch: false\n\n relay1: # Channel 1 of the relay /dev/hidraw0\n driver: relay # Not GPIO, so add name from the above Drivers section\n pin: 0 # Numerating starts from 0\n mode: output # Relays can't be inputs\n initial: null # Don't reset the state to 0 when initializing and terminating KVMD\n relay2: # Channel 2\n driver: relay\n pin: 1\n mode: output\n initial: null\n pulse:\n delay: 2 # Default pulse value\n max_delay: 2 # The pulse interval can be between min_delay=0.1 (by default) and max_delay=2\n</code></pre>"},{"location":"gpio/#view","title":"View","text":"<p>This is the last part of the required configuration. It defines how the previous driver and channel configuration is rendered on the Web interface. Here's an example for the example configuration above:</p> <pre><code>kvmd:\n gpio:\n view:\n header:\n title: Switches # The menu title\n table: # The menu items are rendered in the form of a table of text labels and controls\n - [\"#Generic GPIO leds\"] # Text starting with the sharp symbol will be a label\n - [] # creates a horizontal separator and starts a new table\n - [\"#Test 1:\", led1, button1] # Text label, one input, one button with text \"Click\"\n - [\"#Test 2:\", led2, button2]\n - []\n - [\"#HID Relays /dev/hidraw0\"]\n - []\n - [\"#Relay #1:\", \"relay1|Boop 0.1\"] # Text label and button with alternative text\n - [\"#Relay #2:\", \"relay2|Boop 2.0\"]\n</code></pre> <p>This will be rendered as:</p> <p></p> <p>Some rules and customization options:</p> <ul> <li>Text starting with the <code>#</code> symbol will be a label.</li> <li>To place a channel in a cell, use the name you defined in the scheme.</li> <li>Inputs are displayed as round LEDs.</li> <li>Outputs are displayed as a switch AND a button.</li> <li>If the switch mode is disabled, only a button will be displayed. If pulse is disabled, only a switch will be shown.</li> <li>To change the LED's color specify it after the channel name like <code>\"led1|red\"</code>. Available: <code>green</code>, <code>yellow</code>, <code>red</code>, <code>blue</code>, <code>cyan</code>, <code>magenta</code>, <code>pink</code> and <code>white</code>.</li> <li>To change title of the button, write some its name like <code>\"relay1|My cool relay\"</code>.</li> <li>Buttons and switches can request confirmation on acting. To do this write its name like <code>\"relay1|confirm|My cool relay\"</code>. The third argument with a title is required in this case.</li> <li>The button can automatically close the menu when clicked. Use something like <code>\"relay1|hide|My button\"</code>. It can be used with confirmation option: <code>\"relay1|confirm,hide|My button\"</code>.</li> </ul> <p>Also you can place some leds in the menu title using the similar syntax:</p> <pre><code>kvmd\n gpio:\n view:\n header:\n title: [\"#Test1:\", led1, \"Test2:\", led2]\n</code></pre>"},{"location":"gpio/#hardware-modules-and-pseudo-drivers","title":"Hardware modules and pseudo-drivers","text":""},{"location":"gpio/#raspberrys-gpio","title":"Raspberry's GPIO","text":"Click to view <p>The driver <code>gpio</code> provides access to regular GPIO pins with input and output modes. It uses <code>/dev/gpiochip0</code> and the libgpiod library to communicate with the hardware. Does not support saving state between KVMD restarts (meaning <code>initial=null</code>).</p> <p>You can use the interactive scheme when selecting the pins to use. Please note that when selecting a pin for a channel, you need to use a logical number instead of a physical number. That is, if you want to use a physical pin with the number 40, the channel must have the number 21 corresponding to the logical GPIO21.</p> <p>Channels should not use duplicate pins. You can also not use already used pins. To see which pins are currently used, run the command <code>gpioinfo</code>.</p>"},{"location":"gpio/#usb-hid-relay","title":"USB HID Relay","text":"Click to view <p>The driver <code>hidrelay</code> provides access to cheap managed USB HID relays that can be found on AliExpress. This driver does not support input mode, only output. To use it, you need to specify the path to the device file (like <code>/dev/hidraw0</code>) using the <code>device</code> parameter.</p> <p>Additionally, we recommend to configure access rights and static device name using UDEV rules. For example, create <code>/etc/udev/rules.d/99-kvmd-extra.rules</code>:</p> <pre><code>KERNEL==\"hidraw[0-9]*\", SUBSYSTEMS==\"usb\", ATTRS{idVendor}==\"16c0\", ATTRS{idProduct}==\"05df\", GROUP=\"kvmd\"\n</code></pre> <p>Channels should not use duplicate physical numbers. The driver supports saving state between KVMD restarts (meaning <code>initial=null</code>).</p>"},{"location":"gpio/#ezcoo-kvm-switch","title":"ezCoo KVM switch","text":"Click to view <p>You can use GPIO to control KVM port switching. This usually requires the use of relays and buttons, but for the ezCoo switch there is a special <code>ezcoo</code> driver that simulates GPIO by sending commands to the switch via serial port. So you can make a menu in PiKVM to control the multiport switch.</p>"},{"location":"gpio/#ipmi","title":"IPMI","text":"Click to view <p>The driver <code>ipmi</code> provides the ability to send IPMI commands (on, off, reset) and show the power status of the remote host. In fact, this is not a hardware driver, but something like a pseudo-GPIO. Each \"pin\" is actually responsible for a specific IPMI operation of <code>ipmitool</code>:</p> Pin Type Command <code>0</code> <code>input</code> <code>ipmitool ... power status</code>, can be used to draw the LED in the menu <code>1</code> <code>output</code> <code>ipmitool ... power on</code>, sends the <code>on</code> command (and only this), so like all other outputs it should be a button <code>2</code> <code>output</code> <code>ipmitool ... power off</code> <code>3</code> <code>output</code> <code>ipmitool ... power cycle</code> <code>4</code> <code>output</code> <code>ipmitool ... power reset</code> <code>5</code> <code>output</code> <code>ipmitool ... power diag</code> <code>6</code> <code>output</code> <code>ipmitool ... power soft</code> <p>You are supposed to define one driver per host:</p> <pre><code>kvmd:\n gpio:\n drivers:\n my_server:\n type: ipmi\n host: myserver.local\n user: admin\n passwd: admin\n scheme:\n my_server_status:\n driver: my_server\n pin: 0\n mode: input\n my_server_on:\n driver: my_server\n pin: 1\n mode: output\n switch: false\n my_server_off:\n driver: my_server\n pin: 2\n mode: output\n switch: false\n view:\n table:\n - [my_server_status, \"my_server_on|On\", \"my_server_off|Off\"]\n</code></pre>"},{"location":"gpio/#wake-on-lan","title":"Wake-on-LAN","text":"Click to view <p>The driver <code>wol</code> provides a simple generator of Wake-on-LAN packages. One driver and one output are generated for one host if a simplified configuration method is used. However, you can define multiple drivers if you want to manage different hosts. One driver controls one host, and can only be used as an output. Pin numbers are ignored.</p> <pre><code>kvmd:\n gpio:\n drivers:\n wol_server1:\n type: wol\n mac: ff:ff:ff:ff:ff:f1\n wol_server2:\n type: wol\n mac: ff:ff:ff:ff:ff:f2\n ip: 192.168.0.100\n port: 9\n scheme:\n wol_server1:\n driver: wol_server1\n pin: 0\n mode: output\n switch: false\n wol_server2:\n driver: wol_server2\n pin: 0\n mode: output\n switch: false\n view:\n table:\n - [\"#Server 1\", \"wol_server1|Send Wake-on-LAN\"]\n - [\"#Server 2\", \"wol_server2|Send Wake-on-LAN\"]\n</code></pre>"},{"location":"gpio/#cmd","title":"CMD","text":"Click to view <p>The <code>cmd</code> driver allows you to run custom command on PiKVM OS.</p> <p>Note</p> <p>This driver does not support bash operators, that is, it is a direct call to commands with arguments. For more complex cases, write your own shell scripts.</p> <p>Commands are executed from the user <code>kvmd</code>. If you want to run the command as root, then you need to configure <code>sudo</code>. Example of the <code>/etc/sudoers.d/custom_commands</code>:</p> <p>Granular example</p> <pre><code>kvmd ALL=(ALL) NOPASSWD: /usr/bin/reboot\n</code></pre> <p>NON Granular example (Captures ALL commands)</p> <pre><code>kvmd ALL=(ALL) NOPASSWD: ALL\n</code></pre> <p>Example of the <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>kvmd:\n gpio:\n drivers:\n reboot:\n type: cmd\n cmd: [/usr/bin/sudo, reboot]\n scheme:\n reboot_button:\n driver: reboot\n pin: 0\n mode: output\n switch: false\n view:\n table:\n - [\"reboot_button|confirm|Reboot PiKVM\"]\n</code></pre> <p>An example to help you get started:</p> <ul> <li><code>cmd: [/usr/bin/sudo, kvmd-otgconf, --disable-function, mass_storage.usb0]</code></li> <li><code>cmd: [(absolute path to sudo, command, flag, flag, absolute path to file]</code></li> </ul> <p>Then run the following:</p> <pre><code>systemctl restart kvmd\n</code></pre>"},{"location":"gpio/#pwm","title":"PWM","text":"Click to view <p>The <code>pwm</code> driver allows you to use some GPIO pins on the Raspberry Pi for PWM.</p> <p>Note</p> <p>Due to hardware limitations, this module conflicts with the kvmd-fan (the fan controller) on PiKVM V3 and V4 Plus. To use it, you have to use hardware PWM for kvmfan. To do this, add the following lines to <code>/etc/kvmd/fan.ini</code>:</p> <pre><code>[main]\npwm_soft = 80\n</code></pre> <p>Not needed for V4 Mini because it does not have a fan.</p> <p>Here the small example with servo control:</p> <ol> <li> <p>Add some params to <code>/boot/config.txt</code>:</p> <ul> <li> <p>For PiKVM V3 or DIY device to enable PWM0_0 on RPi GPIO18:</p> <pre><code>dtoverlay=pwm\n</code></pre> </li> <li> <p>For PiKVM V4 to enable PWM0_0 on CM4 GPIO12 (CN5 NeoPixel Pin) and set the PWM function to 4 (ALT0):</p> <pre><code>dtoverlay=pwm,pin=12,func=4\n</code></pre> </li> </ul> </li> <li> <p>Create <code>/etc/udev/rules.d/99-kvmd-pwm.rules</code>:</p> <pre><code>SUBSYSTEM==\"pwm*\", ACTION==\"add\", RUN+=\"/bin/chgrp -R kvmd /sys%p\", RUN+=\"/bin/chmod -R g=u /sys%p\"\nSUBSYSTEM==\"pwm*\", ACTION==\"change\", ENV{TRIGGER}!=\"none\", RUN+=\"/bin/chgrp -R kvmd /sys%p\", RUN+=\"/bin/chmod -R g=u /sys%p\"\n</code></pre> </li> <li> <p>Connect Servo motor like SG90 PWM connection to RPi GPIO18 or CM4 GPIO12, +5V and GND to a 5V and GND pin on header:</p> </li> <li> <p>Add to /etc/kvmd/override.yaml</p> <pre><code>kvmd:\n gpio:\n drivers:\n servo1:\n type: pwm\n chip: 0 # PWM Chip Number\n period: 20000000 # Servo Motor SG90 Period in nano-seconds\n duty_cycle_push: 1500000 # Servo Motor SG90 duty_cycle for pushing button\n duty_cycle_release: 1000000 # Servo Motor SG90 duty_cycle for releasing button\n scheme:\n __v4_locator__: # v4-mini only\n pin: 25 # v4-mini only\n short_press:\n driver: servo1\n pin: 0 # Pin number is the PWM channel number on the PWM Chip\n mode: output\n switch: false\n pulse:\n delay: 0.5\n max_delay: 2\n long_press:\n driver: servo1\n pin: 0\n mode: output\n switch: false\n pulse:\n delay: 2\n max_delay: 2\n extra_long_press:\n driver: servo1\n pin: 0\n mode: output\n switch: false\n pulse:\n delay: 10\n max_delay: 20\n view:\n header:\n title: Controls\n table:\n - [\"#Servo - Short Press\", \"short_press|Press\"]\n - [\"#Servo - Long Press\", \"long_press|Press\"]\n - [\"#Servo - Extra Long Press\", \"extra_long_press|Press\"]\n</code></pre> </li> </ol>"},{"location":"gpio/#servo","title":"Servo","text":"Click to view <p>The <code>servo</code> module is built on top of the <code>pwm</code> module and allows user to define angles instead of <code>duty_cyles</code> to control a PWM enabled servo motor like SG90. When the button is pressed the servo motor moves to an angle defined by <code>angle_push</code> and when button is released it moves back to <code>angle_release</code>. In the example configuration for a cheap 5V SG90 Servo, the motor moves to an angle of 45 degrees when button is pressed and moves back to 20 degress when released.</p> <p>Note</p> <p>Due to hardware limitations, this module conflicts with the kvmd-fan (the fan controller) on PiKVM V3 and V4 Plus. To use it, you have to use hardware PWM for kvmfan. To do this, add the following lines to <code>/etc/kvmd/fan.ini</code>:</p> <pre><code>[main]\npwm_soft = 80\n</code></pre> <p>Not needed for v4-mini because it does not have a fan.</p> <p>To use Servo motors in PiKVM you need to follow steps 1-3 for PWM Module and then use the following configuration.</p> <p>Add to <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>kvmd:\n gpio:\n drivers:\n servo1:\n type: servo\n chip: 0 # PWM Chip Number\n period: 20000000 # Servo Motor SG90 Period in nano-seconds\n duty_cycle_min: 350000 # Servo Motor SG90 duty_cycle for -90 degrees\n duty_cycle_max: 2350000 # Servo Motor SG90 duty_cycle for +90 degrees\n angle_max: 90 # Servo Motor SG90 angle at duty_cycle_max\n angle_min: -90 # Servo Motor SG90 angle at duty_cycle_min\n angle_push: 45 # Servo Motor SG90 angle to push button\n angle_release: 20 # Servo Motor SG90 angle to release button\n scheme:\n __v4_locator__: # v4-mini only\n pin: 25 # v4-mini only\n short_press:\n driver: servo1\n pin: 0 # Pin number is the PWM channel number on the PWM Chip\n mode: output\n switch: false\n pulse:\n delay: 0.5\n max_delay: 2\n long_press:\n driver: servo1\n pin: 0\n mode: output\n switch: false\n pulse:\n delay: 2\n max_delay: 2\n extra_long_press:\n driver: servo1\n pin: 0\n mode: output\n switch: false\n pulse:\n delay: 10\n max_delay: 20\n view:\n header:\n title: Controls\n table:\n - [\"#Servo - Short Press\", \"short_press|Press\"]\n - [\"#Servo - Long Press\", \"long_press|Press\"]\n - [\"#Servo - Extra Long Press\", \"extra_long_press|Press\"]\n</code></pre>"},{"location":"gpio/#philips-hue","title":"Philips Hue","text":"Click to view <p>The <code>hue</code> module can control smartplugs and lamps over Philips Hue Bridge API. In general the plugin can switch any device on/off which is connected to the bridge. To use it you will need API token aka username:</p> <ol> <li>Open <code>http://bridge/debug/clip.html</code>.</li> <li>In the URL: Field type <code>/api/</code>.</li> <li>In the Message Body: Field type: <code>{\"devicetype\": \"pikvm\"}</code>.</li> <li>Hit the Get Button.</li> <li>As the Response you become the Username: <code>{\"success\": {\"username\": \"apiusername\"}</code>.</li> </ol> <p>Example:</p> <pre><code>kvmd:\n gpio:\n drivers:\n hue:\n type: hue\n url: http://bridge\n token: YG-xxxxxxxxxxxx\n scheme:\n plug_button:\n driver: hue\n pin: 32\n mode: output\n initial: null\n switch: true\n pulse:\n delay: 0\n plug_led:\n driver: hue\n pin: 32\n mode: input\n view:\n table:\n - [\"plug_led\", \"plug_button\"]\n</code></pre>"},{"location":"gpio/#anel-net-pwrctrl","title":"ANEL NET-PwrCtrl","text":"Click to view <p>The <code>anelpwr</code> plugin allows you to use ANEL NET-PwrCrtl IP-PDUs (switchabel sockets) as gpios. There are up to 8 Ports per PDU. Input pulls the the current state from the PDU, Output switches the Socket. </p> <pre><code>kvmd:\n gpio:\n drivers:\n anel_pdu_0:\n type: anelpwr\n url: http://IP:port\n user: admin\n passwd: anel\n scheme:\n pdu0_0_pwr:\n pin: 0\n driver: anel_pdu_0\n mode: output\n pulse:\n delay: 0\n pdu0_0_led:\n pin: 0\n driver: anel_pdu_0\n mode: input\n view:\n header:\n title: \"PDUs\"\n table:\n - [\"#PDU0\"]\n - []\n - [\"#PDU0_Port0:\", pdu0_0_led, \"pdu0_0_pwr|confirm|test\"] \n</code></pre>"},{"location":"gpio/#extron-sw-series-switchers","title":"Extron SW Series Switchers","text":"Click to view <p>The <code>extron</code> plugin allows you to control Extron SW series switchers (ex. SW4 USB, SW4 VGA, etc.). There are up to 4 Ports per switcher. Input pulls the the current state from the switcher, Output switches the active port.</p> <pre><code>kvmd:\n gpio:\n drivers:\n extron_vga:\n type: extron\n device: /dev/ttyUSB0 # The path to the RS-232 serial adapter\n scheme:\n vga_port1_led:\n pin: 0\n driver: extron_vga\n mode: input\n vga_port2_led:\n pin: 1\n driver: extron_vga\n mode: input\n vga_port3_led:\n pin: 2\n driver: extron_vga\n mode: input\n vga_port4_led:\n pin: 3\n driver: extron_vga\n mode: input\n vga_port1_button:\n pin: 0\n driver: extron_vga\n mode: output\n vga_port2_button:\n pin: 1\n driver: extron_vga\n mode: output\n vga_port3_button:\n pin: 2\n driver: extron_vga\n mode: output\n vga_port4_button:\n pin: 3\n driver: extron_vga\n mode: output\n view:\n header:\n title: \"Extron SW4 VGA\"\n table:\n - [\"vga_port1_led|red\", \"vga_port1_button||Port 1\"]\n - [\"vga_port2_led|red\", \"vga_port2_button||Port 2\"]\n - [\"vga_port3_led|red\", \"vga_port3_button||Port 3\"]\n - [\"vga_port4_led|red\", \"vga_port4_button||Port 4\"]\n</code></pre>"},{"location":"id/","title":"Identifying PiKVM on the target host","text":"<p>This page explains how PiKVM is presented to the target host's operating system, and how this can be changed. This is useful for developers, testers and system administrators who need PiKVM to emulate a specific USB device or monitor.</p> <p>Info</p> <p>Before exploring this page, we recommend to read the PiKVM configuration guide so that you understand the terminology and how exactly the parameters described below change.</p>"},{"location":"id/#basics","title":"Basics","text":"<p>PiKVM is a combined emulator of several devices for user interaction. Simply put, your host sees the connected PiKVM not just as a single device, but as a set of multiple devices.</p> <p>In the most default case out of the box, these are the following:</p> <ul> <li>HDMI video display;</li> <li>USB keyboard;</li> <li>USB mouse (two mice for PiKVM V4);</li> <li>USB mass storage drive (ejectable);</li> </ul> <p>Thus, PiKVM emulates two types of devices: HDMI and USB. Each of them has a specific set of identifiers. For example, if you go to monitor settings on the host, you will see something like <code>PiKVM V4 Plus</code>. It works in a similar way with USB.</p>"},{"location":"id/#hdmi-identifiers","title":"HDMI Identifiers","text":"<p>Info</p> <p>This applies to PiKVM V3, V4 and DIY based on CSI bridge. It is impossible to change the EDID for the HDMI-USB dongle.</p> <p>The EDID (Extended Display Identification Data) is responsible for presenting the display. It also provides the host with information about the resolutions that PiKVM supports. More information about this is written on this page, and here we will provide brief information.</p> <p>Quick IDs changing on PiKVM V4 Plus</p> <p>PiKVM V4 Plus has a simple way read and adopt display identifiers like model and serial number from your physical display. See here for details.</p> <p>Run <code>kvmd-edidconf</code> on PiKVM:</p> <pre><code>[root@pikvm ~]# kvmd-edidconf\nManufacturer ID: LNX\nProduct ID: 0x7773 (30579)\nSerial number: 0x01010101 (16843009)\nMonitor name: PiKVM V4 Plus\nMonitor serial: CAFEBABE\nAudio: yes\n</code></pre> <p>The fields have obvious names and purposes. Note the two similar fields <code>Serial number</code> and <code>Monitor serial</code>. The first has a numeric value, and the second is ASCII. If you are using a custom EDID from some real display, some fields may be missing.</p> <p>To change the values of the EDID fields, use the <code>kvmd-edidconf</code> with options, a complete list is available in <code>kvmd-edidconfi --help</code>.</p> <p>Here the small example of changing all available fields from the previous listing:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# kvmd-edidconf --set-mfc-id=TTP --set-product-id=0x5B81 --set-serial=0x8DE11B79 --set-monitor-name=TOSHIBA --set-monitor-serial=ABCD1234 --apply\nManufacturer ID: TTP\nProduct ID: 0x5B81 (23425)\nSerial number: 0x8DE11B79 (2380340089)\nMonitor name: TOSHIBA\nMonitor serial: ABCD1234\nAudio: yes\n...\n[root@pikvm ~]# ro\n</code></pre> <p>The full list of manufacturer IDs is available here.</p> <p>For a detailed guide on customizing EDID, please visit this page. There you can also find out how to set the EDID from a real monitor, or quickly adopt your real monitor IDs with PiKVM V4 Plus.</p>"},{"location":"id/#usb-identifiers","title":"USB Identifiers","text":"<p>Info</p> <p>This applies to PiKVM V2+. Identifiers on V1 and/or the Pico HID can't be changed without recompilation and reflashing of the firmware.</p> <p>USB is a much more complex subsystem and another part of PiKVM is responsible for it. Be careful when changing the settings here, it may cause the USB to fail.</p> <p>For information on how to control emulated devices see here. The identification is described below.</p> <p>As you may have found out from the PiKVM configuration guide (if you haven't read it yet, now is the time), you can get the list of all configuration parameters using the <code>kvmd -m</code> command.</p> <p>Below is a listing of all the parameters, from which the unrelated and those USB parameters that should not be changed have been removed. In the context of identifiers, we are interested in the following:</p> <pre><code>[root@pikvm ~]# kvmd -m\notg:\n vendor_id: 7531\n product_id: 260\n manufacturer: PiKVM\n product: PiKVM Composite Device\n serial: CAFEBABE\n device_version: -1\n max_power: 250\n\n devices:\n drives:\n default:\n inquiry_string:\n cdrom:\n vendor: PiKVM\n product: Optical Drive\n revision: '1.00'\n\n flash:\n vendor: PiKVM\n product: Flash Drive\n revision: '1.00'\n\n msd:\n default:\n inquiry_string:\n cdrom:\n vendor: PiKVM\n product: Optical Drive\n revision: '1.00'\n\n flash:\n vendor: PiKVM\n product: Flash Drive\n revision: '1.00'\n</code></pre> <p>Pay attention to the nesting levels. The parameters are always located in certain sections. All numeric values are displayed in decimal form, but in the config you can use a hex form. The generally accepted names from the USB specifications are shown too.</p> Parameter USB Spec Description <code>vendor_id</code> <code>idVendor</code> Unique vendor ID assigned by USB.org. <code>product_id</code> <code>idProduct</code> Just an ID for the product assigned by this vendor. <code>manufacturer</code> <code>iManufacturer</code> to 0x409 ASCII name of the vendor. <code>product</code> <code>iProduct</code> to 0x409 ASCII name of the product. <code>serial</code> <code>iSerialNumber</code> to 0x409 ASCII serial number of the product. <code>device_version</code> <code>bcdDevice</code> Kinda the revision of the device. Assigned automatically. It can be changed to 256, 257, 258 or something like this <p>These IDs are also used for the microphone on PiKVM V4.</p> <p>The strings under <code>otg/drives</code> and <code>otg/msd</code> sections deserve a special description. They relate to virtual media emulation and are separate parts of the SCSI inquiry string, the drive identifier used by the OS driver. All three parameters <code>vendor</code>, <code>product</code>, and <code>revision</code> are short ASCII strings responsible for CD/DVD or Flash representation.</p> <p>The <code>msd</code> refers to a virtual drive accessible from the Web UI, and the <code>drives</code> describes all additional drives if you have configured them (disabled by default). Note that mass storage drive can be completely disabled.</p> <p>To change the parameters, use the <code>/etc/kvmd/override.yaml</code>, for example, like this:</p> <pre><code>otg:\n vendor_id: 0x6940\n product_id: 0x6973\n manufacturer: Corsair\n product: Gaming RGB\n serial: 1000\n\n devices:\n msd:\n default:\n inquiry_string:\n cdrom:\n vendor: Corsair\n product: DVD\n revision: '1.00'\n\n flash:\n vendor: Corsair\n product: STICK\n revision: '1.00'\n</code></pre> <p>After changing validate the config using <code>kvmd -m</code>. You will see the full config list with changed and default values, or a message about configuration error.</p> <p>If everything is fine, perform the soft reboot.</p>"},{"location":"id/#replicating-setups","title":"Replicating setups","text":"<p>You can use <code>kvmd-edidconf</code> and <code>kvmd-otgconf</code> to replicate an entire host configuration for testing or other purposes. What you can do will vary depending on the PiKVM device you have:</p> <ul> <li>V4 Plus: you can import both EDID and USB IDs.</li> <li>V4 Mini: you must manually edit <code>override.yaml</code>, as there is neither a second HDMI Out or additional USB ports on your PiKVM.</li> <li>V3: you can import USB IDs only, as there is no second HDMI output on your PiKVM.</li> </ul> <p>Assuming you have PiKVM V4 Plus, follow these steps:</p> <ol> <li>Connect the host's display to one of the two HDMI Out ports on the rear panel of your PiKVM.</li> <li>Connect the host's USB keyboard and mouse to USB ports on the front and the rear panel of you PiKVM.</li> <li>Run <code>rw</code> to switch to read-write mode.</li> <li>Run <code>kvmd-edidconf --import-display-ids --apply</code> as root on the PiKVM. This will fetch EDID information from the connected physical display and place it into the <code>/etc/kvmd/override.yaml</code> configuration file.</li> <li>Run <code>kvmd-otgconf --import-usb-ids</code> as root on the PiKVM. This will fetch IDs of the connected physical USB devices and place them into the <code>/etc/kvmd/override.yaml</code> configuration file.</li> <li>Run <code>ro</code> to switch to read-only mode.</li> <li>Run <code>reboot</code> to reboot your PiKVM and apply newly the added customization.</li> <li>Reconnect the host's display and keyboard/mouse back to the host.</li> </ol>"},{"location":"ipmi/","title":"IPMI & Redfish","text":"<p>Info</p> <p>This page is about the server-side IPMI emulation if you want to manage PiKVM using <code>ipmitool</code> 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.</p> <p>Warning</p> <p>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.</p> <p>Please consider to using the Redfish or KVMD API instead of it.</p>"},{"location":"ipmi/#ipmi-bmc","title":"IPMI BMC","text":"<p>IPMI is a legacy protocol 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.</p> Step by step: Enabling IPMI server on PiKVM <ol> <li> <p>Switch the filesystem to the RW-mode:</p> <pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Set up IPMI account in file <code>/etc/kvmd/ipmipasswd</code> (see the comment inside it).</p> </li> <li> <p>Enable the <code>kvmd-ipmi</code> daemon:</p> <pre><code>[root@pikvm ~]# systemctl enable --now kvmd-ipmi\n</code></pre> </li> <li> <p>Switch the filesystem back to the RO:</p> <pre><code>[root@pikvm ~]# ro\n</code></pre> </li> <li> <p>Try some commands on the client PC:</p> <pre><code>$ ipmitool -I lanplus -U admin -P admin -H pikvm power status\n$ ipmitool -I lanplus -U admin -P admin -H pikvm power on\n</code></pre> </li> </ol>"},{"location":"ipmi/#ipmi-sol","title":"IPMI SoL","text":"<p>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.</p> <p>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.</p> Step by step: Enabling IPMI SoL for USB-COM adapter <p>As with IPMI BMC, you need to configure <code>kvmd-ipmi</code> server (see the previous chapter about IPMI BMC) and add the following configuration to <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>ipmi:\n sol:\n device: /dev/ttyUSB0 # Path of your USB-COM adapter\n speed: 115200\n</code></pre> <p>Then restart the <code>kvmd-ipmi</code> server: <code>systemctl restart kvmd-ipmi</code>.</p> <p>All requests that it receives over the network regarding the COM port will be forwarded to your server. For example:</p> <pre><code>[root@pikvm ~]$ ipmitool -I lanplus -U admin -P admin -H pikvm sol activate\n</code></pre>"},{"location":"ipmi/#redfish","title":"Redfish","text":"<p>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.</p> <p>PiKVM supports the Redfish natively and provides a power management handles with it.</p> <p>To access the Redfish API, use HTTP Basic Auth methods. Also you can use the redfishtool:</p> <pre><code>[root@pikvm ~]$ redfishtool -S Never -r pikvm root\n[root@pikvm ~]$ redfishtool -S Never -u admin -p admin -r pikvm Systems\n[root@pikvm ~]$ redfishtool -S Never -u admin -p admin -r pikvm Systems reset ForceOff\n</code></pre>"},{"location":"letsencrypt/","title":"Let's Encrypt certificates","text":"<p>PiKVM uses self-signed SSL certificates out of the box. If you have a domain name, you can use Let's Encrypt certificates.</p> <p>Usually Let's Encrypt certificates are issued and updated automatically using Certbot, however, since PiKVM uses a read-only file system, special tools around Certbot are required to work with certificates. KVMD 3.117 provides them.</p> <p>Note</p> <p>This feature is available on images as old as 2022.06.19 since it requires PST storage partition on SD card. Ports 80+443 need to be opened if you are port forwarding for this to work properly.</p>"},{"location":"letsencrypt/#basic-setup","title":"Basic setup","text":"<ol> <li> <p>Update the OS and make sure that you are using a new image with PST storage.</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> <pre><code># kvmd-pstrun -- true\n</code></pre> <p>If the storage is not available, you need to reflash the OS image to the latest one from our official website.</p> </li> <li> <p>Switch filesystem to RW and obtain the certificate (for example, <code>pikvm.example.com</code>. The method depends on the network configuration. In the simplest case, if PiKVM is open for access from the Internet, it is recommended to use the webroot. Another examples will be described below.</p> <pre><code># rw\n# kvmd-certbot certonly_webroot --agree-tos -n --email user@example.com -d pikvm.example.com\n</code></pre> </li> <li> <p>Install the certificate for KVMD-Nginx and (optionally) KVMD-VNC. Running services will be restarted/reloaded automatically. Switch filesystem to RO.</p> <pre><code># kvmd-certbot install_nginx pikvm.example.com\n# kvmd-certbot install_vnc pikvm.example.com\n# ro\n</code></pre> </li> <li> <p>Check the renewal immediately, just for testing:</p> <pre><code># kvmd-certbot renew --force-renewal\n</code></pre> </li> <li> <p>Enable automatic certificate renewal:</p> <pre><code># rw\n# systemctl enable --now kvmd-certbot.timer\n# ro\n</code></pre> </li> </ol>"},{"location":"letsencrypt/#cloudflare-dns","title":"Cloudflare DNS","text":"<p>This example shows that PiKVM may not be accessible from the internet, but you can still get a certificate if you use Cloudflare DNS.</p> <ol> <li> <p>Switch filesystem to RW and install the Cloudflare DNS plugin:</p> <pre><code># rw\n# pacman -S certbot-dns-cloudflare\n</code></pre> </li> <li> <p>Prepare the environment for the DNS plugin (place the auth data):</p> <p></p><pre><code># kvmd-pstrun -- mkdir -p /var/lib/kvmd/pst/data/certbot/runroot\n# kvmd-pstrun -- nano /var/lib/kvmd/pst/data/certbot/runroot/.cloudflare.auth\n# kvmd-pstrun -- chmod 600 /var/lib/kvmd/pst/data/certbot/runroot/.cloudflare.auth\n# kvmd-pstrun -- chown kvmd-certbot: /var/lib/kvmd/pst/data/certbot/runroot/.cloudflare.auth\n</code></pre> See certbot-dns-cloudflare's doc here about the content of <code>.cloudflare.auth</code>. </li> <li> <p>Obtain the certificate:</p> <pre><code># kvmd-certbot certonly \\\n --dns-cloudflare \\\n --dns-cloudflare-propagation-seconds 60 \\\n --dns-cloudflare-credentials /var/lib/kvmd/pst/data/certbot/runroot/.cloudflare.auth \\\n --agree-tos \\\n -n \\\n --email user@example.com \\\n -d pikvm.example.com\n</code></pre> </li> <li> <p>Next follow the basic guide starts at step 3.</p> </li> </ol>"},{"location":"letsencrypt/#route53-dns","title":"Route53 DNS","text":"<p>This example shows that PiKVM may not be accessible from the internet, but you can still get a certificate if you use AWS Route53 DNS. Make sure you are running an image newer than 2022.06.20 and kvmd version 3.119-1 or greater.</p> <ol> <li> <p>Switch filesystem to RW and install the Route53 DNS plugin:</p> <pre><code># rw\n# pacman -S certbot-dns-route53\n</code></pre> </li> <li> <p>Configure Your AWS User For the certbot_dns_route53 plugin to work it needs to be able to connect to AWS using an access key with the correct permissions.</p> <p>To do this securely you\u2019ll want to create a new AWS user that only has the necessary permissions it needs to work.</p> <p>You can find instructions for creating a user here. The basics of it is you\u2019ll want a user with Programmatic access (not console), add it to a group (I created a new one just for this user and any future certbot users I might need).</p> <p>The user will need specific permissions that are required to allow the certbot plugin to create the necessary CNAME records. These can be added by manually selecting them from a very long list or you can use the json view to give it the following permissions.</p> <pre><code>{\n\"Version\": \"2012-10-17\",\n\"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\"route53:ListHostedZones\", \"route53:GetChange\"],\n \"Resource\": [\"*\"]\n },\n {\n \"Effect\": \"Allow\",\n \"Action\": [\"route53:ChangeResourceRecordSets\"],\n \"Resource\": [\"arn:aws:route53:::hostedzone/YOURHOSTEDZONEID\"]\n }\n]\n}\n</code></pre> <p>Make sure you replace YOURHOSTEDZONEID with the instance ID of your hosted zone.</p> <p>Once the user is created don\u2019t forget to download and save your access key and secret access key (somewhere secure, these are as sensitive as your passwords).</p> </li> <li> <p>Setup credentials:</p> <p>We now need to put the AWS credentials on the PiKVM so the certbot can use them.</p> <pre><code># kvmd-pstrun -- mkdir -p /var/lib/kvmd/pst/data/certbot/runroot\n</code></pre> <p>Copy and paste your AWS credentials into the nano editor and save the file.</p> <pre><code># kvmd-pstrun -- nano /var/lib/kvmd/pst/data/certbot/runroot/.route53.auth\n</code></pre> <p>Here is an example .route53.auth file. Replace the placeholders with the access key and secret access key that you just saved from AWS and fill them in.</p> <pre><code>[default]\naws_access_key_id=XXXXXX\naws_secret_access_key=XXXX/XXXXX\n</code></pre> <p>Update permissions:</p> <pre><code># kvmd-pstrun -- chmod 600 /var/lib/kvmd/pst/data/certbot/runroot/.route53.auth\n# kvmd-pstrun -- chown kvmd-certbot: /var/lib/kvmd/pst/data/certbot/runroot/.route53.auth\n</code></pre> </li> <li> <p>Obtain the certificate:</p> <pre><code># export AWS_SHARED_CREDENTIALS_FILE=\"/var/lib/kvmd/pst/data/certbot/runroot/.route53.auth\"\n# kvmd-certbot certonly \\\n --dns-route53 \\\n --agree-tos \\\n -n \\\n --email user@example.com \\\n -d pikvm.example.com\n</code></pre> </li> <li> <p>Enable automatic certificate renewal:</p> <p>Create the file: <code>/etc/conf.d/kvmd-certbot</code> with the following contents so the renewall service can find the authentication file containing the AWS credentials:</p> <pre><code>AWS_SHARED_CREDENTIALS_FILE=\"/var/lib/kvmd/pst/data/certbot/runroot/.route53.auth\"\n</code></pre> <p>Now enable the renewal service:</p> <pre><code># systemctl enable --now kvmd-certbot.timer\n</code></pre> </li> </ol>"},{"location":"letsencrypt/#acme-dns","title":"ACME DNS","text":"<p>ACME DNS is a \"Limited DNS server with RESTful HTTP API to handle ACME DNS challenges easily and securely.\" The acme-dns-client works, in conjunction, with Certbot (<code>kvmd-certbot</code>) to enable <code>DNS-01</code> challenge support via ACME DNS.</p> <p>These instructions are for how to install and use the <code>acme-dns-client</code> with ACME DNS for PiKVM.</p>"},{"location":"letsencrypt/#assumptions","title":"Assumptions","text":"<ul> <li>ACME DNS is already set up and functioning in the environment</li> <li>ACME DNS Server is <code>auth.example.org</code></li> <li>PiKVM Fully Qualified Domain Name (FQDN) is <code>pikvm.example.org</code></li> <li>PiKVM is running on a supported Raspberry Pi using the PiKVM OS (which is 32-bit as of the writing of this documentation)</li> <li>All configuration examples below are as user <code>root</code> via a terminal session to PiKVM</li> </ul>"},{"location":"letsencrypt/#not-in-scope","title":"Not in Scope","text":"<ul> <li>Installation and Setup of ACME DNS Server</li> </ul>"},{"location":"letsencrypt/#instructions","title":"Instructions","text":"<ol> <li>Ensure that Step 1 from Basic Setup has been completed</li> <li>Visit the Releases page to get the download URL for the latest <code>acme-dns-client</code> release (PiKVM OS is 32-bit, which is <code>linux_armv6</code>)</li> <li> <p>Install <code>acme-dns-client</code></p> <p>The <code>acme-dns-client</code> is not distributed by <code>pacman</code> and is a manual installation. The steps below are for:</p> <ul> <li>Creating a folder for <code>acme-dns-client</code></li> <li>Downloading and extracting the <code>acme-dns-client</code> TAR from Github</li> <li>Moving the <code>acme-dns-client</code> binary to the created folder</li> <li>Cleaning up files from the download</li> <li>Creating the necessary persistent symbolic link to allow <code>acme-dns-client</code> to be ran</li> <li>Initialize <code>acme-dns-client</code></li> </ul> <p>Note</p> <p>Make sure to replace the URL below with the one gathered from Step 1. As of the writing of this documentation: - The latest (and demonstrated) version is v0.3 - (Demonstrated) Platform is <code>linux-armv6</code> </p> <pre><code># mkdir /etc/acmedns\n# curl -LO https://github.com/acme-dns/acme-dns-client/releases/download/v0.3/acme-dns-client_0.3_linux_armv6.tar.gz\n# tar -zxvf acme-dns-client_0.3_linux_armv6.tar.gz\n# mv acme-dns-client /etc/acmedns/acme-dns-client\n# ln -sf /etc/acmedns/acme-dns-client /usr/local/bin/acme-dns-client\n# rm LICENSE README.md acme-dns-client_0.3_linux_armv6.tar.gz\n# acme-dns-client\n</code></pre> </li> <li> <p>Register <code>acme-dns-client</code> with ACME DNS </p> <p>Note</p> <p>This is interactive, follow instructions for creating and verifying the appropriate <code>CNAME</code> record. </p> <pre><code># acme-dns-client register -d pikvm.example.org -s http://auth.example.org\n</code></pre> <p>Once registration is complete ownership of <code>clientstorage.json</code> must be changed to <code>kvmd-certbot</code>.</p> <pre><code># chown kvmd-certbot:kvmd-certbot /etc/acmedns/clientstorage.json\n</code></pre> <p>Note</p> <p>If using <code>acme-dns-client</code> on an internal/private domain with an ACME compatible Certificate Authority do not forget to add <code>-ns <dns-server-ip>:<dns-server-port></code> to <code>acme-dns-client register</code></p> </li> <li> <p>Register Certbot</p> <pre><code># kvmd-certbot register\n</code></pre> </li> <li> <p>Request Certificate via Certbot</p> <pre><code># kvmd-certbot certonly --manual --preferred-challenges dns --manual-auth-hook 'acme-dns-client' -d pikvm.example.org\n</code></pre> <p>Note</p> <p>If using an ACME compatible Certificate Authority (other than Let's Encrypt) do not forget to add <code>--server https://ca.example.org/acme/acme/directory</code> to <code>kvmd-certbot</code></p> </li> <li> <p>Follow steps 3 through 5 under Basic Setup to complete setup and renewal of certificates</p> </li> </ol>"},{"location":"letsencrypt/#wireguard-proxy","title":"Wireguard proxy","text":"<p>If you don't have public IP, and you don't want to put your API keys in PiKVM, you can forward HTTP traffic over wireguard. To Let's Encrypt you'll appear to serve ACME challenges from a host they can reach from the Internet (e.g. VPS), to which you'll connect over wireguard.</p>"},{"location":"letsencrypt/#assumptions_1","title":"Assumptions","text":"<ul> <li>FQDN of your pikvm is <code>pikvm1.int.example</code>;</li> <li>FQDN of the proxy VPS is <code>acme-proxy.example</code>;</li> <li>public IP addresses of VPS are <code>198.51.100.1</code> and <code>2001:db8::1</code>;</li> <li>internal (wireguard) IPv4 address of the PiKVM is <code>10.11.12.13</code>.</li> </ul>"},{"location":"letsencrypt/#instructions_1","title":"Instructions","text":"<ol> <li> <p>Setup wireguard and ensure it's working.</p> </li> <li> <p>Setup public DNS zone to point the domain address at the public VPS:</p> <pre><code>acme-proxy.example. IN A 198.51.100.1\nacme-proxy.example. IN AAAA 2001:db8::1\npikvm1.int.example. IN CNAME acme-proxy.example.\n</code></pre> </li> <li> <p>On the public VPS, configure HTTP proxy to forward <code>/.well-known/acme-challenge</code> to PiKVM. For example in nginx:</p> <pre><code>server {\n listen 80;\n listen [::]:80;\n\n server_name pikvm1.int.example;\n\n location ^~ /.well-known/acme-challenge {\n proxy_pass http://10.11.12.13:80;\n proxy_set_header Host $host;\n }\n\n location / {\n return 404;\n }\n}\n</code></pre> </li> <li> <p>Now you can use <code>kvmd-certbot certonly_webroot</code> as in basic scenario above.</p> </li> </ol>"},{"location":"modem/","title":"Setting up 3G/4G/LTE modem","text":"<p>With PiKVM, you can create a portable device to work in a distant environment without a permanent wired internet connection. A cellular modem in combination with any VPN like Tailscale is also an excellent backup for emergency access to the host.</p>"},{"location":"modem/#choosing-a-modem","title":"Choosing a modem","text":"<p>PiKVM supports a huge number of USB modems. If the modem works with a desktop Linux, it will work with PiKVM as well.</p>"},{"location":"modem/#mini-pci-on-pikvm-v4-plus","title":"Mini-PCI on PiKVM V4 Plus","text":"<p>PiKVM V4 Plus has an internal Mini-PCI and built-in SIM card slot for installing a modem. Please note that only modems with USB data lines are supported.</p> <p>Here is a list of good modems that you can start with:</p> <ul> <li>SIMCom SIM7600G-H</li> <li>Sierra Wireless MC7700</li> <li>Huawei EM820W</li> <li>Quectel EG25-G</li> </ul> <p>An antenna and an SMA pigtail are also required to use the modem.</p> <p>When choosing an antenna, check the supported frequency list of your cellular ISP and the antenna itself.</p>"},{"location":"modem/#setting-up-the-connection","title":"Setting up the connection","text":"<p>Change default passwords if you haven't done so earlier. It's very important for the security.</p> <p>Cellular networks can open your device to the big world. PiKVM is safe if you use a strong password, so...</p> Changing PiKVM Passwords <p>PiKVM comes with the following default passwords:</p> <ul> <li> <p>Linux OS-level admin (SSH, console...):</p> <ul> <li>Username: <code>root</code></li> <li>Password: <code>root</code></li> </ul> </li> <li> <p>KVM user (Web Interface, API, VNC...):</p> <ul> <li>Username: <code>admin</code></li> <li>Password: <code>admin</code></li> <li>No 2FA code</li> </ul> </li> </ul> <p>They are two separate accounts with independent passwords.</p> <p>To change passwords, you will need to use the console access via SSH or the Web Terminal. If you are using the Web Terminal, enter the <code>su -</code> command to get the <code>root</code> access (enter the <code>root</code> user password).</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# passwd root\n[root@pikvm ~]# kvmd-htpasswd set admin\n[root@pikvm ~]# ro\n</code></pre> <p>If you require additional user for the Web UI access, use the following:</p> <pre><code>[root@pikvm ~]# kvmd-htpasswd add <user> # Add a new user with password\n[root@pikvm ~]# kvmd-htpasswd del <user> # Remove/delete a user\n</code></pre> <p>Optionally you can enable the two-factor authentication for more security.</p> <p>Changing the VNCAuth key and IPMI password at the first start of PiKVM is not required, since these services are disabled by default. But it is here just so that you remember their existence.</p> <ol> <li> <p>Update the OS and reboot.</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> </li> <li> <p>Make filesystem writable using <code>rw</code> command.</p> </li> <li> <p>Install NetworkManager and ModemManager:</p> <pre><code>[root@pikvm ~]# pacman -S modemmanager networkmanager\n</code></pre> </li> <li> <p>Create file <code>/etc/NetworkManager/conf.d/pikvm-unmanaged.conf</code> with following content:</p> <pre><code>[keyfile]\nunmanaged-devices=*,except:type:gsm\n</code></pre> </li> <li> <p>Run the services:</p> <pre><code>[root@pikvm ~]# systemctl enable --now NetworkManager ModemManager\n</code></pre> </li> <li> <p>Make sure that ModemManager detects your modem. You will see something similar after <code>mmcli</code>, modem <code>0</code> is detected here:</p> <pre><code>[root@pikvm ~]# mmcli --list-modems\n /org/freedesktop/ModemManager1/Modem/0 [QUALCOMM INCORPORATED] SIMCOM_SIM7600G-H\n</code></pre> </li> <li> <p>View the modem <code>0</code> information:</p> <pre><code>[root@pikvm ~]# mmcli -m 0\n -----------------------------------\n General | path: /org/freedesktop/ModemManager1/Modem/0\n | device id: ...\n -----------------------------------\n Hardware | manufacturer: QUALCOMM INCORPORATED\n | model: SIMCOM_SIM7600G-H\n | firmware revision: LE20B04SIM7600G22\n | carrier config: ROW_Gen_VoLTE\n | carrier config revision: ...\n | h/w revision: 10000\n | supported: gsm-umts, lte\n | current: gsm-umts, lte\n | equipment id: ...\n ...\n -----------------------------------\n Status | lock: sim-pin\n | unlock retries: sim-pin (3), sim-puk (10), sim-pin2 (3), sim-puk2 (10)\n | state: locked\n | power state: on\n ...\n</code></pre> </li> <li> <p>Set up the connection. You will need the APN value (from the mobile ISP) and PIN-code for the SIM:</p> <pre><code>[root@pikvm ~]# nmcli c add type gsm ifname '*' con-name pikvm-lte gsm.apn cytamobile gsm.pin 1234\n</code></pre> <ul> <li><code>pikvm-lte</code> is just a meaning name of the connection, use any you like.</li> <li><code>gsm.apn cytamobile</code> sets APN value to <code>cytamobile</code> (will be different for other ISP).</li> <li><code>gsm.pin 1234</code> sets PIN for unlocking the SIM card. If the SIM is not locked, omit these words.</li> </ul> <p>Depending on the ISP, you may need to specify a password and/or some other parameters.</p> </li> <li> <p>Make the connection automatically connected:</p> <pre><code>[root@pikvm ~]# nmcli connection modify pikvm-lte autoconnect yes\n</code></pre> </li> <li> <p>The connection will already be working:</p> <pre><code>[root@pikvm ~]# nmcli\ncdc-wdm0: connected to pikvm-lte\n \"cdc-wdm0\"\n gsm (option, qmi_wwan), hw, iface wwan0, mtu 1500\n ip4 default\n inet4 XXX.XXX.XXX.XXX/XX\n route4 XXX.XXX.XXX.XXX/XX metric 700\n route4 default via XXX.XXX.XXX.XXX/XX metric 700\n...\n</code></pre> </li> <li> <p>Perform <code>reboot</code>.</p> </li> </ol> <p>To set up a Tailscale VPN, refer to this page.</p>"},{"location":"mouse/","title":"Mouse","text":"<p>There are two modes of pointer device: absolute and relative.</p> <p>In absolute mode, the input device transmits the exact coordinates <code>(X,Y)</code> where the cursor should be moved. This is how touchscreens or drawing tablets work.</p> <p>In relative mode, only the relative offset <code>(dX,dY)</code> to the current position is transmitted, which is unknown to the input device itself. This is a regular mouse.</p> <p>By default, PiKVM uses absolute positioning mode as the most convenient for the user and software. However, this is not always supported by the BIOS/UEFI. For such cases, support is provided for the relative mode of operation, which can be enabled in the config.</p> <p>When using relative mode, the browser will exclusively capture your mouse when you click on the stream window in PiKVM once. When you press <code>Esc</code>, the browser releases the mouse.</p>"},{"location":"mouse/#important-notes","title":"Important notes","text":"<p>The relative mouse generates a huge number of events that can be poorly transmitted over the network or very slowly perceived by the BIOS/UEFI driver. To solve this problem, mouse events are optimized using a vector sum. This mode is enabled by activating the below first and is available in the web menu <code>System -> Squash mouse moves</code>. You can try disabling this if you have problems with mouse acceleration. This is the best and most reasonable compromise right now.</p> <p>Also currently the relative mouse mode is not supported by PiKVM VNC server yet. The reason is that none of the recommended clients support the QEMU Pointer Motion Change extension. We expect to implement this in TigerVNC. The relative mode is also not supported by mobile browsers.</p>"},{"location":"mouse/#relative-mouse-on-v2-platform-otg-hid","title":"Relative mouse on V2+ platform (OTG HID)","text":"<p>Info</p> <p>On PiKVM V4 dual mode is enabled by default. To disable it and enable single mode, set <code>kvmd/hid/mouse_alt/device</code> (see below) to empty string:</p> <pre><code>kvmd:\n hid:\n mouse_alt:\n device: \"\"\n</code></pre>"},{"location":"mouse/#dual-mode","title":"Dual mode","text":"<p>Using dual mouse mode you can switch between the absolute and relative mouse in the <code>System</code> menu without reloading. This is more convenient, but for compatibility reasons it is disabled by default. To enable it, do the following:</p> <ol> <li> <p>Switch filesystem to RW-mode using command <code>rw</code>.</p> </li> <li> <p>Edit <code>/etc/kvmd/override.yaml</code> and add these lines:</p> <pre><code>kvmd:\n hid:\n mouse_alt:\n device: /dev/kvmd-hid-mouse-alt\n</code></pre> </li> <li> <p>Perform <code>reboot</code>. After that reboot your PC.</p> </li> </ol>"},{"location":"mouse/#single-relative-mode","title":"Single relative mode","text":"<ol> <li> <p>Switch filesystem to RW-mode using command <code>rw</code>.</p> </li> <li> <p>Edit <code>/etc/kvmd/override.yaml</code> and add these lines:</p> <pre><code>kvmd:\n hid:\n mouse:\n absolute: false\n</code></pre> </li> <li> <p>Perform <code>reboot</code>. After that reboot your PC.</p> </li> <li> <p>If the mouse is still not detected by the BIOS/UEFI, try disabling horizontal scrolling to achieve the maximum compatibility:</p> <pre><code>kvmd:\n hid:\n mouse:\n absolute: false\n horizontal_wheel: false\n</code></pre> </li> <li> <p>Don't forget to perform <code>reboot</code>.</p> </li> </ol>"},{"location":"mouse/#fixing-the-absolute-mouse-on-windows-98","title":"Fixing the absolute mouse on Windows 98","text":"<p>Due to an ancient buggy driver, the absolute mouse on Windows 98 moves only within the upper-left quarter of the screen. To fix this, you need to activate some magic workaround. Due to the specifics of the implementation, you will have to turn on the relative mouse too. Write it in <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>kvmd:\n hid:\n mouse:\n absolute_win98_fix: true\n mouse_alt:\n device: /dev/kvmd-hid-mouse-alt\n</code></pre> <p>... and run <code>systemctl restart kvmd</code>. After that, you will get 3 new buttons with mouse modes in the System menu in Web UI. Switch it to Abs-Win98.</p>"},{"location":"mouse/#relative-mouse-on-v0-v1-platform-picoarduino-hid","title":"Relative mouse on V0-V1 platform (Pico/Arduino HID)","text":"<p>Mode switching for the Pico HID or legacy Arduino HID can be performed on-the-fly starting with KVMD 2.6 and the corresponding firmware. No additional actions are required.</p>"},{"location":"mouse_jiggler/","title":"Mouse Jiggler","text":"<p>The mouse jiggler is a feature used to simulate the movement of a computer mouse. It prevents sleep mode, standby mode or the screensaver from activating. It is very useful when some lengthy process is going on on the target host (for example, installing software), and the user needs to monitor it with his side vision, without having to move the mouse manually to avoid the screensaver.</p>"},{"location":"mouse_jiggler/#using-the-jiggler","title":"Using the Jiggler","text":"<p>With a latest PiKVM OS, the jiggler is available in the Web UI:</p> <p></p> <p>If you don't see this switch, please update OS first:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p>"},{"location":"mouse_jiggler/#jiggler-settings","title":"Jiggler settings","text":"<p>This is not required usually, but it is possible to change some of the parameters of the jiggler or disable it completely.</p> <p>Here are some examples to place it to <code>/etc/kvmd/override.yaml</code>.</p> <ol> <li> <p>Make the jiggler unavailable in the menu:</p> <pre><code>kvmd:\n hid:\n jiggler:\n enabled: false\n</code></pre> </li> <li> <p>Activate it by default after PiKVM reboot:</p> <pre><code>kvmd:\n hid:\n jiggler:\n active: true\n</code></pre> </li> </ol>"},{"location":"mouse_jiggler/#description-of-the-algorithm","title":"Description of the algorithm","text":"<p>When the Jiggler is active, PiKVM counts down the time that has elapsed since the last user input: that is, any action with the keyboard or mouse. If there have been no actions for more than 15 seconds, the Jiggler performs a mouse movement and waits another 15 seconds until the next iteration.</p> <p>The Jiggler supports both mouse modes: absolute and relative.</p> <p>Movement patterns looks like these:</p> <ul> <li>Absolute: <code>(+100, +100), wait, (-100, -100), wait...</code>The coordinates are converted depending on the screen resolution.</li> <li>Relative: <code>(+10, +10), wait, (-10, -10), wait...</code></li> </ul> <p>The Jiggler works on the PiKVM device side, even if the Web UI was closed.</p> <p>An important feature of the Jiggler is that it does not interfere with normal user work. If the user is actively interacting with the keyboard and mouse, Jiggler will not introduce its interference until it notices that the period of inactivity has exceeded the threshold of 15 seconds.</p>"},{"location":"msd/","title":"Mass Storage Drive","text":"<p>This powerful feature that is available on all PiKVM V2+ devices. It allows PiKVM to emulate a virtual CD/DVD or Flash Drive for the target host which will be available even in BIOS/UEFI when you need live disk to revive the OS or even reinstall it.</p> <p>Warning</p> <p>This document is relevant for <code>KVMD >= 4.49</code>.</p> <p>Also since this version, PiKVM supports DVD emulation!</p> <p>If you are using an older version, please update the PiKVM OS:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> Take a look at the <code>Drive</code> menu in the Web UI <p>The following actions are available here:</p> <ul> <li>Uploading an image to the internal storage of PiKVM.</li> <li>Selecting an image to connect to the target host.</li> <li>Changing the media type and write availability mode.</li> <li>Downloading an image from the PiKVM storage.</li> <li>Drive connection management and much more.</li> </ul> <p>Warning</p> <p>Never turn off the power of the PiKVM while the image is being uploaded or while the image is connected to the target host in write mode. This may cause file corruption.</p> <p>The rest of the time, power off is safe because the PiKVM filesystem will be in read-only mode.</p> <p>Changing the media type between CD/DVD and Flash is possible only when the device is reconnected</p> <p>On PiKVM V3 and V4, this can be done using the <code>System -> Connect main USB</code> switch in the Web UI.</p> <p>In this case, the media type is determined at the time of connecting the image, and not by clicking on the switch. The switch affects the settings of the future connection. For non-V3/V4 devices, you need to either reboot your target host or otherwise reinitialize the drive.</p>"},{"location":"msd/#manual-images-uploading","title":"Manual images uploading","text":"<p>PiKVM stores images in a special memory card partition mounted in <code>/var/lib/kvmd/msd</code>.</p> <p>Most of the time, the partition is read-only, and is remounted for writing automatically if the appropriate drive emulation mode is enabled, or to upload a new image. This protects the data from damage in the event of a sudden loss of power.</p> Step by step: Manual image uploading using SCP or rsync <ol> <li> <p>Remount internal storage to read-write mode manually:</p> <pre><code>[root@pikvm ~]# kvmd-helper-otgmsd-remount rw\n</code></pre> </li> <li> <p>Upload the image(s) to <code>/var/lib/kvmd/msd</code> using <code>scp</code> or some other tool.</p> </li> <li> <p>Remount internal storage back to safe read-only mode:</p> <pre><code>[root@pikvm ~]# kvmd-helper-otgmsd-remount ro\n</code></pre> </li> </ol> <p>Tip</p> <p>An HTTP API for Mass Storage management is also available for advanced use.</p>"},{"location":"msd/#writable-flash-drive","title":"Writable Flash Drive","text":"<p>When emulating Flash Drive on PiKVM, you can allow the target host to write files to the image. After stopping the drive, this image can be downloaded and opened on the local host. This is useful if you need to get some files from the target host.</p> <p>The file system image for the virtual Flash Drive must be prepared in advance. This can be done either on the local host or in the PiKVM console.</p> <p>Here some options:</p> Step by step: Creating simple FAT32 image on PiKVM <ol> <li> <p>Remount internal storage to read-write mode manually:</p> <pre><code>[root@pikvm ~]# kvmd-helper-otgmsd-remount rw\n</code></pre> </li> <li> <p>Create an empty image file in <code>/var/lib/kvmd/msd</code> (this is the internal storage of PiKVM images) of desired size (512MB in this example) and format it to FAT32:</p> <pre><code>[root@pikvm ~]# fallocate -l 512M /var/lib/kvmd/msd/flash.img\n[root@pikvm ~]# loop=$(losetup -f)\n[root@pikvm ~]# echo -e 'o\\nn\\np\\n1\\n\\n\\nt\\nc\\nw\\n' | fdisk /var/lib/kvmd/msd/flash.img\n[root@pikvm ~]# losetup -P $loop /var/lib/kvmd/msd/flash.img\n[root@pikvm ~]# mkfs.vfat ${loop}p1\n[root@pikvm ~]# losetup -d $loop\n[root@pikvm ~]# chmod 666 /var/lib/kvmd/msd/flash.img\n</code></pre> </li> <li> <p>Remount internal storage back to safe read-only mode:</p> <pre><code>[root@pikvm ~]# kvmd-helper-otgmsd-remount ro\n</code></pre> </li> </ol> <p>Note</p> <ul> <li>For PiKVM V3+ you'll need to toggle the USB connection using the Web UI: Switch <code>System -> Connect Main USB</code> to off, then on.</li> <li>For V2 you'l need to reboot the target host.</li> </ul> Step by step: Creating an image on a local macOS <ol> <li> <p>Open <code>Disk Utility</code>.</p> </li> <li> <p>Click menu <code>File -> New Image -> Blank Image</code>.</p> </li> <li> <p>Set some options:</p> <code>Format</code> and <code>Partitions</code> are very important </li> <li> <p>Click <code>Save</code>. The drive will automatically be mounted.</p> </li> <li> <p>Copy files (such as BIOS updates) onto the new image (via terminal or drag and drop in Finder).</p> </li> <li> <p>Eject image.</p> </li> <li> <p>Rename the image file from <code>.dmg</code> to <code>.img</code>.</p> </li> <li> <p>Upload the image to PiKVM.</p> </li> </ol> <p>The image <code>flash.img</code> now should be available in the <code>Drive</code> menu in Web UI. Change drive mode to the <code>Flash</code> position and enable <code>Writable</code> switch. Connect the image, do whatever is necessary, with files, and disconnect it. The modified image containing your files can be downloaded to a local host by selecting it from the menu and clicking the floppy disk icon.</p>"},{"location":"msd/#nfs-storage","title":"NFS storage","text":"<p>It is possible to create a shared image storage for an entire fleet of PiKVMs using NFS.</p> <p>If you have some shares, you can easily connect them to PiKVM by creating mount points and adding relevant records to <code>/etc/fstab</code>. At the same time, you will be able to upload images via PiKVM Web UI to NFS, and still use local storage.</p> Step by step: Connecting NFS storage <ol> <li> <p>Update OS:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> </li> <li> <p>Make some preparations:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -S nfs-utils\n[root@pikvm ~]# kvmd-helper-otgmsd-remount rw\n[root@pikvm ~]# mkdir -p /var/lib/kvmd/msd/NFS_Primary\n[root@pikvm ~]# mkdir -p /var/lib/kvmd/msd/NFS_Secondary\n[root@pikvm ~]# kvmd-helper-otgmsd-remount ro\n</code></pre> </li> <li> <p>Add NFS shares to <code>/etc/fstab</code>:</p> <pre><code>server:/srv/nfs/NFS_Primary /var/lib/kvmd/msd/NFS_Primary nfs vers=3,timeo=1,retrans=1,soft,nolock 0 0\nserver:/srv/nfs/NFS_Secondary /var/lib/kvmd/msd/NFS_Secondary nfs vers=3,timeo=1,retrans=1,soft,nolock 0 0\n</code></pre> </li> <li> <p>Perform <code>reboot</code> to apply all changes.</p> </li> </ol> <p>Make sure that the <code>kvmd</code> user has the read access from these directories. You can also give the write access if needed. For the best performance, it is required to ensure reliable connectivity with NFS server and use minimum <code>timeo</code> and <code>retrans</code> values. Using the <code>soft</code> option is mandatory, <code>nolock</code> is recommended.</p> <p>Note if an image is added to the NFS storage from the outside, PiKVM will not be able to track this event, so it is required to use <code>Drive -> Reset</code> in the Web UI to update the list of images.</p> <p>Configuring an NFS server is beyond the scope of this guide.</p>"},{"location":"msd/#sambacifs-storage","title":"Samba/CIFS storage","text":"<p>If you already have a local samba server e.g. Unraid or another NAS you can use the isos from there.</p> <p>To refresh the list of available isos on the share it is currently necessary to reboot.</p> Step by step: Connecting Samba/CIFS storage <ol> <li> <p>Update OS:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> </li> <li> <p>Make some preparations:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -S cifs-utils\n[root@pikvm ~]# kvmd-helper-otgmsd-remount rw\n[root@pikvm ~]# mkdir -p /var/lib/kvmd/msd/isos\n[root@pikvm ~]# kvmd-helper-otgmsd-remount ro\n</code></pre> </li> <li> <p>Add Samba/CIFS shares to <code>/etc/fstab</code>:</p> <pre><code>//192.168.0.1/isos /var/lib/kvmd/msd/isos cifs guest,_netdev,nofail 0 0\n</code></pre> </li> <li> <p>Perform <code>reboot</code> to apply all changes.</p> </li> </ol>"},{"location":"msd/#exfat-filesystem-warning","title":"exFAT filesystem warning","text":"<p>Using the existing USB ports you can reduce writes to the internal SSD card by storing images on a USB thumb drive. This is mounted as would NFS or Samba, above. As recent drives are starting to come formatted with <code>exfat</code> instead of <code>fat</code> or <code>NTFS</code>, the linux kernel will default to 'root' ownership of the mountpoint. This means the volume will be visible in the 'Media' menu, but will be marked as <code>[read-only]</code>, without any obvious reason.</p> <p>The correct <code>/etc/fstab</code> entry for a USB drive that presents as <code>/dev/sda1</code> with an exfat filesystem is:</p> <pre><code> ```fstab\n /dev/sda1 /var/lib/kvmd/msd/usb exfat auto,nofail,rw,umask=0000 0 0\n ```\n</code></pre> <p>This says to mount it automatically, do not fail if it's missing, mount it read/write by default, and allow all users and groups access to it.</p> <p>Don't forget to create <code>/var/lib/kvmd/msd/usb</code> directory:</p> <pre><code>[root@pikvm ~]# kvmd-helper-otgmsd-remount\n[root@pikvm ~]# mkdir -p /var/lib/kvmd/msd/usb\n[root@pikvm ~]# kvmd-helper-otgmsd-remount ro\n</code></pre>"},{"location":"msd/#multiple-drives","title":"Multiple drives","text":"<p>By default, PiKVM creates one virtual drive for Mass Storage emulation. However, if necessary, you can create additional ones and manage them using console utility. This is useful if there is a need to boot the target host from the first drive, and then connect the second to exchange files.</p> <p>Note</p> <p>The first virtual drive is available for management both in the Web UI (the <code>Drive</code> menu) and using the <code>kvmd-otgmsd</code> console utility (see below). Extra drives are controlled only from console.</p> <p>The issue of additional drives concerns compatibility. There is an assumption that multiple drives on the same USB may confuse some BIOS/UEFI. So for paranoid reasons, this feature requires manual activation. It is recommended setting up the drives in advance, making sure that booting from ISO CD or Flash is still working with your specific target host, and then using the drives as planned.</p> <p>Also additional drives consumes extra endpoints, read more under the spoiler:</p> <p>USB limitations</p> <p>Each emulated USB device consumes a limited hardware resource called endpoints.</p> <p>Short info: by default, you can add only one additional USB device.</p> <p>To get more information about the endpoints, add more devices, and flexibly manage the configuration on the fly, see here.</p> <p>So, to add a second virtual drive, follow this:</p> Step by step: Enabling an additional drive <ol> <li> <p>Switch the filesystem to read-write mode:</p> <pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Edit <code>/etc/kvmd/override.yaml</code> and add the extra drive config section:</p> <pre><code>otg:\n devices:\n drives:\n enabled: true # Set it to true to enable\n count: 1 # +1 drive, default value\n default: # Default configuration for the all extra drives\n cdrom: false # Default value (false for the generic flash drive, true for CD/DVD)\n rw: false # Read-only by default\n</code></pre> <p>The <code>count</code> parameter determines the number of additional drives (remember the limit on endpoints). Each of the drives will be created with the same initial parameters described in the <code>default</code> section.</p> </li> <li> <p>Perform reboot:</p> <pre><code>[root@pikvm ~]# reboot\n</code></pre> </li> </ol>"},{"location":"msd/#manual-drives-management","title":"Manual drives management","text":"<p>The <code>kvmd-otgmsd</code> console utility is used to manage additional (and the first main one) drives. The full list of options can be found by running <code>kvmd-otgmsd --help</code>.</p> Step by step: Creating the flash drive image to get some files from the target host <ol> <li> <p>Switch the filesystem to read-write mode:</p> <pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Create an empty image file with desired size (1GB in this example):</p> <pre><code>[root@pikvm ~]# fallocate -l 1000M /root/flash.img\n</code></pre> </li> <li> <p>Connect it to the drive <code>1</code> (the creation process is described in the previous section):</p> <pre><code>[root@pikvm ~]# kvmd-otgmsd -i 1 --set-rw=1 --set-cdrom=0 --set-image=/root/flash.img\n</code></pre> <p>Note</p> <ul> <li> <p>Index <code>0</code> represents the main drive that is controlled via the Web UI and API.</p> </li> <li> <p>If <code>--set-cdrom=1</code>, the drive will work as CD-ROM for small images, and as DVD-ROM for big. Please note that CD/DVD can't be writable (you should use <code>--set-rw=0</code> in this case).</p> </li> </ul> </li> <li> <p>On this step, you will be able to access the flash drive from the target host and format the it in the usual way.</p> </li> <li> <p>View the drive state:</p> <pre><code>[root@pikvm ~]# kvmd-otgmsd -i 1\nImage file: /root/flash.img\nCD/DVD flag: no\nRW flag: yes\n</code></pre> </li> <li> <p>To disable the flash drive and view the files on it from the PiKVM, run:</p> <pre><code>[root@pikvm ~]# kvmd-otgmsd -i 1 --unlock --eject\n</code></pre> </li> <li> <p>Don't forget to remount the root filesystem to read-only mode:</p> <pre><code>[root@pikvm ~]# ro\n</code></pre> </li> <li> <p>You can download the resulting image via SCP or mount it as a loop device on the PiKVM:</p> <pre><code>[root@pikvm ~]# mount -o loop /root/flash.img /mnt\n[root@pikvm ~]# ls /mnt\n[root@pikvm ~]# umount /mnt\n</code></pre> </li> </ol> <p>Tip</p> <p>The main drive can also be switched to read-write mode, this can be done from the Web UI.</p> <p>In this case, the image will have to be prepared outside of PiKVM, and upload it to use, then download it back to your local host for files extraction.</p>"},{"location":"msd/#disabling-mass-storage","title":"Disabling Mass Storage","text":"<p>In rare cases, it may be necessary to disable Mass Storage emulation if the BIOS/UEFI does not recognize it correctly and even refuses to work with USB keyboard and mouse.</p> Step by step: Permanent disabling Mass Storage <ol> <li> <p>Switch the filesystem to read-write mode:</p> <pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Edit <code>/etc/kvmd/override.yaml</code> and add the extra drive config section:</p> <pre><code>kvmd:\n msd:\n type: disabled\n</code></pre> </li> <li> <p>Perform reboot:</p> <pre><code>[root@pikvm ~]# reboot\n</code></pre> </li> </ol> <p>Tip</p> <p>As an alternative method may be to use the dynamic USB configuration, which allows you to temporarily disable any of the emulated devices, including Mass Storage Drive.</p>"},{"location":"msd/#big-dvd-images-on-old-pikvm","title":"Big DVD images on old PiKVM","text":"<p>Since KVMD 4.49, PiKVM is able to emulate DVD images.</p> <p>Before that, users had to use Ventoy and other utilities to pre-convert large DVD images such as the official Windows ISO to Flash.</p> <p>We strongly recommend updating the PiKVM OS to simplify your Mass Storage experience when using DVDs:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> <p>Anyway, you can still view all these legacy recipes.</p>"},{"location":"msd_legacy/","title":"Big DVD images on old PiKVM","text":"<p>Since KVMD 4.49, PiKVM is able to emulate DVD images.</p> <p>Before that, users had to use Vento and other utilities to pre-convert large DVD images such as the official Windows ISO to Flash.</p> <p>We strongly recommend updating the PiKVM OS to simplify your Mass Storage experience when using DVDs:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p>"},{"location":"msd_legacy/#making-windows-boot-flash-image","title":"Making Windows Boot Flash Image","text":"<p>An alternative version of this can be found below that does not require a physical usb flash</p> <p>This procedure will create a disk image of a USB stick. This is mostly required for Windows based images since they are larger than the CDROM based limit of 2.2GB. You can create a bootable USB stick with the normal Microsoft tools, e.g. Media Creation Tool. Creating a bootable USB stick can also be made from an ISO file with other tools like Rufus.</p> <p>Without resizing, the full size of the USB stick will be used, so keep the stick as small as possible (e.g. 4GB or 8GB) but still large enough for all Windows files. The Media Creation tool will tell you what the minimum size is.</p> <p>Before creating the image file, you can use a tool like EaseUS Partition Master Free or GParted to resize the main FAT32 partition on the USB stick. This will save space on PiKVM.</p> <p>You can also perform these steps on a separate UNIX machine and transfer the image over to PiKVM. Or, on Windows you could use a program like PassMark ImageUSB (only for full USB size images) or <code>dd</code> for Windows to create the image.</p> <p>Once you have the desired USB stick perform the following on the RPi to create the image directly to the PiKVM image storage folder.</p> <ol> <li> <p>Insert Windows based USB stick into Pi4, generated with Microsoft USB creation tool. SSH to PiKVM as root.</p> <pre><code># dmesg\n[ 3025.025401] usb-storage 2-1:1.0: USB Mass Storage device detected\n[ 3025.038911] scsi host0: usb-storage 2-1:1.0\n[ 3026.132248] scsi 0:0:0:0: Direct-Access Kingston DataTraveler 3.0 PMAP PQ: 0 ANSI: 6\n[ 3026.771425] sd 0:0:0:0: [sda] 15360000 512-byte logical blocks: (7.86 GB/7.32 GiB)\n[ 3026.790276] sd 0:0:0:0: [sda] Write Protect is off\n[ 3026.802530] sd 0:0:0:0: [sda] Mode Sense: 23 00 00 00\n[ 3026.804450] sd 0:0:0:0: [sda] No Caching mode page found\n[ 3026.814082] sd 0:0:0:0: [sda] Assuming drive cache: write through\n[ 3026.908712] sda: sda1\n[ 3026.922794] sd 0:0:0:0: [sda] Attached SCSI removable disk\n[root@pikvm ~]#\n</code></pre> <p>USB devices shows as <code>sda</code>. We will use <code>sda1</code> as the Windows partition.</p> </li> <li> <p>mount msd folder as read/write</p> <pre><code># kvmd-helper-otgmsd-remount rw\n</code></pre> </li> <li> <p>Create image of USB data PARTITION to an image file, this will take some time, in this case about 12 minutes (RPi4).</p> <pre><code># dd if=/dev/sda1 of=/var/lib/kvmd/msd/windows10-2004.bin bs=8M status=progress\n4458545152 bytes (4.5 GB, 4.2 GiB) copied, 736 s, 6.1 MB/s\n531+1 records in\n531+1 records out\n4458545152 bytes (4.5 GB, 4.2 GiB) copied, 736.213 s, 6.1 MB/s\n</code></pre> </li> <li> <p>Correct ownership of new image and make sure the website reports the file as complete.</p> <pre><code># chown kvmd:kvmd /var/lib/kvmd/msd/windows10-2004.bin\n</code></pre> </li> <li> <p>Remount msd folder as read only</p> <pre><code># kvmd-helper-otgmsd-remount ro\n</code></pre> </li> <li> <p>On PiKVM webpage, under Storage select the new image and connect it in Drive Mode: Flash to the server.</p> </li> </ol> <p>Boot the server and select boot device like you normally would. E.g. in a AMI BIOS the boot device is called \"Linux File-CD Gadget 0504\".</p>"},{"location":"msd_legacy/#an-alternative-to-making-a-windows-boot-image-that-does-not-require-a-physical-usb-flash-drive","title":"An alternative to making a Windows boot image that does not require a physical usb flash drive","text":"<ul> <li>Physical USB is not needed but external system is mandatory.</li> <li>Create Ventoy image (on Ubuntu x86 machine) (Unaware of a windows version).</li> <li>There is an assumption that you know basic linux to understand that not all dev devices are named exactly like the below</li> </ul> <pre><code># dd if=/dev/zero of=ventoy.img bs=1M count=4700 status=progress\n</code></pre> <ul> <li>This makes a ventoy.img file, I would name this what it is EG: <code>ventoy_win10.img</code></li> <li> <p>At the same time, download Media Creation Tool and select iso</p> </li> <li> <p>On the Ubuntu machine</p> </li> <li>At the time of this, it was 1.0.51, change to latest version</li> </ul> <pre><code># wget https://github.com/ventoy/Ventoy/releases/download/v1.0.51/ventoy-1.0.51-linux.tar.gz\n# tar zxvf ventoy-1.0.51-linux.tar.gz\n# sudo losetup -f ventoy.img\n# sudo losetup -l | grep ventoy (To locate which loop device was used)\n# sudo sh ~/ventoy-1.0.51/Ventoy2Disk.sh -i /dev/loopXX (This will make a loopXXp1 and a loopXXp2 and will format both partitions\n# cd /media/XXX (Usually your login)\n# mkdir ventoy\n# sudo mount /dev/loopXXp1 /media/XXX/ventoy\n</code></pre> <ul> <li>Either cp/scp over the .iso you downloaded from the Media tool or use a NFS mount</li> </ul> <pre><code>sudo cp windows.iso /media/XXX/ventoy\nsudo umount /dev/loopXX \n# This is going to be different for everyone, please choose the same one you mounted earlier\nsudo losetup -d /dev/loopXX \n# This may or may not work for everyone, if it doesnt work, skip and move forward#\n</code></pre> <p>ssh into the Ubuntu system (Or whatever OS you are using)</p> <ul> <li>On PiKVM</li> </ul> <pre><code># cd /var/lib/kvmd/msd\n# mount -o remount,rw .\n</code></pre> <ul> <li>On Ubuntu</li> </ul> <pre><code># scp ventoy.img root@pikvm:/var/lib/kvmd/msd\n</code></pre> <ul> <li>Mount <code>ventoy.img</code> as normal flash and select the PiKVM boot device, it should popup with the VenToy logo with the window.iso as a selection </li> </ul>"},{"location":"msd_legacy/#an-alternative-to-making-a-windows-boot-image-that-does-not-require-a-physical-usb-flash-drive-on-a-single-windows-machine","title":"An alternative to making a Windows boot image that does not require a physical usb flash drive on a single windows machine","text":"<ul> <li>Physical USB is not needed</li> <li> <p>Requires Administrator rights on the windows machine</p> </li> <li> <p>Testing was done on a Windows 11 machine with a Windows 11 23H2 ISO</p> </li> <li> <p>Requires a windows ISO (can be downloaded from the microsoft website), Rufus (To write the ISO to the VHD) and VirtualBox (Uses VBoxManage to convert VHD to IMG)</p> </li> <li> <p>Create a VHD in Windows, This can be done in two ways that i know of.</p> <p>Method 1: Open up the windows settings, go to storage, press advanced storage settings and press Disks & Volumes Press the Create VHD button, Give the disk a name, set a storage location and set the Virtual hard disk size (for 23H2 i used 6300MB). Set the Virtual hard disk format to VHD and set it to Fixed Size. Press Create and then you will get a menu to initialize the disk, press cancel</p> <p>Method 2: Open up the windows partition manager, make sure you don't have any partitions or disks selected by pressing on empty space, Go to Action and select Create VHD. Select a location for the VHD file, set the VHD size (for 23H2 i used 6300MB), Set the Virtual hard disk format to VHD and set it to Fixed Size. Press OK</p> </li> </ul> <p>2. Download the Windows ISO and Rufus (i use the portable version), open rufus select the NO_LABEL disk that should roughly match size selected when creating the VHD (MiB vs MB). Select the ISO you downloaded and press start Once it is done close rufus (optionally delete rufus)</p> <ol> <li>Unmount the VHD by either opening up windows explorer, right clicking on the windows installer drive and pressing eject or opening up the windows partition manager, right clicking on the virtual disk and detaching the VHD</li> </ol> <p>4. Download and install Virtualbox Open up a command prompt in the location where you stored the VHD </p><pre><code>VBoxManage clonehd input.vhd output.img --format raw\n</code></pre> Or if virtualbox didn't get added to the system environment variables <pre><code>\"C:\\Program Files\\Oracle\\VirtualBox\\VBoxManage.exe\" clonehd input.vhd output.img --format raw\n</code></pre> This will convert the VHD to the IMG ready to be uploaded to the pikvm <ul> <li>using vboxmanage does have a slight quirk where it writes every conversion to .VirtualBox\\VirtualBox.xml so if you make changes to the vhd and try to convert it again it throws and error that the uuid doesn't match the stored value in VirtualBox.xml and you need to either throw away VirtualBox.xml or edit it and delete the line that matches the error</li> <li>this method has also been tested using the windows installer for ventoy (needs enabling show all devices in the windows installer)</li> </ul>"},{"location":"multiport/","title":"Multiport KVM-over-IP","text":"Note <p>V4 MINI can ONLY be used with the TESmart or other KVMs with LAN control, the TESmart has a convenience driver for easier setup</p> <p></p> <p>If you need to connect multiple hosts to a single PiKVM, then the best way to do this is to use our PiKVM Switch. It is designed specifically for PiKVM and has many advantages and features compared to regular desktop multiport switches.</p> <ul> <li>ATX control on each port.</li> <li>Per-port EDID configuration.</li> <li>HDMI dummy plug functionality.</li> <li>True Plug-n-Play with no need for override.yaml setups and complete control via Web UI.</li> <li>Multifunctional RGB LEDs with beacon mode and customizable color schemes.</li> <li>Firmware update directly from PiKVM and ready for future hardware extensions.</li> <li>Compatible with V4 Plus, V3 and DIY devices based on Pi2-Pi4 except Zero and V4 Mini.</li> </ul> <p>And now the best part: the switches can be chained! Need four ports? Get a PiKVM Switch. As your server fleet expands to eight, simply add another switch and link it to the first one. Need even more? No worries \u2014 connect up to five switches and enjoy 20 fully functional ports on your PiKVM.</p> <p>Just take a look!.</p> <p>You can order PiKVM Switch Multiport Extender from our international store.</p> <p>Canadian customers can place an order at PiShop.ca.</p>"},{"location":"multiport/#list-of-tested-third-party-kvms","title":"List of tested third-party KVMs","text":"<p>There are many ways to do this with third-party switches. For example you can choose a switch with USB control connection like ezCoo KVM switch.</p> <p>Also, PiKVM can be connected to a multi-port HDMI/USB switch and the switch's buttons can be connected via optocouplers to the Pi's GPIO to switch channels.</p> <p>If your KVM switches channels using keyboard shortcuts, there is a chance that it will not be able to work with OTG (v2+ platform, see below), since it does not fully implement the USB stack. In this case, you will have to use the Pico HID to emulate the keyboard & mouse (PiKVM supports this configuration).</p> <p>Warning</p> <p>If you choose AIMOS, be aware that it has a back powering issue that you need to use work arounds for. Limitations are are listed below. Also please be aware that Pico's will not work with the AIMOS KVM's.</p> <p>Here the status is:</p> <ul> <li>\u2714 - Everything is working as expected. There may be some subtleties.</li> <li>\u2639 - Not everything works. Additional work is needed for some functions to work, like MSD.</li> <li>\u2718 - The keyboard or mouse does not work at all, the switch loses the image, etc.</li> </ul> Model Status Notes ezCoo EZ-SW41HA-KVMU3L 4x1 switch ezCoo SW41HA HDMI 4x1 switch (legacy) \u2714 Using with PiKVM - 4 Port is the ONLY supported KVM, 2 Port does not work the same and is not supported, the same can be said about any of the HDMI splitters 1-in-2 Out eccoo EZ-SW41HA-KVMU3P 4x1 switch \u2714 Using with PiKVM. Make sure you buy the with hotkey version as that has the control port ezcoo EZ-SW41H21-KVMU3P 8K 4x1 switch \u2714 Does NOT have a control port. MSD Works. Can be managed through key combo (ctrl+ctrl+#) Level1Techs KVM switches \u2714 Just working pretty good TESmart 8 or 16 PORT - HDMI KVM SWITCH \u2714 Use OTG with USB 2.0 Hub only, limited hotkey support on certain models, but MSD only works through Hub ports. Switching available with serial (DIY/v4Plus) or IP-to-serial interface using fixed IP (v4mini et al) (/31 peer-to-peer addressing supported). Can be managed via WebUI or CLI tool XH-HK4401 4-port HDMI USB KVM Switch \u2714 Using with PiKVM - USB MSD works, requires the HDMI backpower solutions found below AIMOS 8-port HDMI USB-C KVM Switch \u2639 Similar to Ali's noname model, available in 4/8port editions, has same HDMI bridge boot problem/solution using a Marmitek 312 UHD HDMI splitter. ONLY supports HotKey switching. Limitations are are listed below Aten CS1758 8-port PS/2 / USB VGA KVM switch \u2639 Older Aten switches can be had for cheap and can be a viable alternative. Devices are connected via PS/2 so USB media support does not work. The setup relies on a VGA-> HDMI adapter to make the video signal work and there can be issues with unsupported VGA resolutions with some adapters. KVM hotkeys and switching all work and so does mouse and keyboard. <p>Limitations:</p> <ul> <li>HDMI backpower solutions:<ul> <li>See here</li> <li>See here - Advanced soldering required</li> <li>This loop capture device</li> <li>v3 HAT v3.3 (Kickstarter model and later) also takes care of the back power issue</li> </ul> </li> <li>Mass Storage Device (MSD) workaround (will not work OOB)<ul> <li>RPi4 OTG needs to be in the KB port for mouse and KB funtionality, ZeroW is required and needs to be connected to the HUB port for MSD functionality - \u2714KNOWN WORKING\u2714</li> <li>AIMOS 4/8-port: See here - Advanced soldering required - allows use of GPIO menu to change input by cycling</li> <li>AIMOS 8-port: See here - Advanced soldering required - allows use of GPIO menu to change input directly</li> </ul> </li> </ul>"},{"location":"ocr/","title":"OCR","text":"<p>This feature allows you to select a screen region, recognize it as text and copy this text to the clipboard. Recognition works locally on your PiKVM and does not use any cloud services. It uses the Tesseract OCR library. Tesseract does not see your image until you explicitly give the recognition command. The evil AI is not watching your screen.</p>"},{"location":"ocr/#language-support","title":"Language support","text":"<p>For any language, you will have to install its support. It is very easy to do this (English language for example): </p><pre><code># rw\n# pacman --assume-installed tessdata -S tesseract-data-eng\n# ro\n</code></pre> <p>List all available languages in the repository: </p><pre><code># pacman -Ss tesseract-data\n</code></pre>"},{"location":"ocr/#disabling-ocr","title":"Disabling OCR","text":"<p>If you want to get rid of this feature completely, you need to delete Tesseract and all its data:</p> <pre><code># rw\n# pacman -R tesseract\n# reboot\n</code></pre>"},{"location":"on_boot_config/","title":"On-boot configuration & production deployment","text":"<p>At the first boot, PiKVM generates encryption keys and performs other actions necessary to configure the device.</p> <p>Some parameters, such as connecting to Wi-Fi, or configuring a static interface for wired Ethernet, can be easily changed by the user if there is physical access to the memory card. This is convenient for quick customization of your device before the first use.</p> <p>All settings are made using a file <code>pikvm.txt</code> on the first section of the memory card. After applying the settings, the file is automatically deleted.</p>"},{"location":"on_boot_config/#setting-up-wi-fi","title":"Setting up Wi-Fi","text":"<p>Note</p> <p>Devices based on Raspberry Pi Zero 2 W does not support 5GHz Wi-Fi.</p> <ol> <li> <p>Remove the PiKVM memory card. The device must be turned off.</p> </li> <li> <p>Insert the memory card into the computer and mount the first FAT32 partition.</p> </li> <li> <p>Among the system files you will see the file <code>pikvm.txt</code>.</p> <ul> <li> <p>If you haven't powered up PiKVM yet, this file will contain a single line <code>FIRST_BOOT=1</code>. Do not remove it, just add following lines from the next step.</p> </li> <li> <p>If the file does not exist, create an empty file (don't add <code>FIRST_BOOT</code> option).</p> </li> </ul> </li> <li> <p>To connect to Wi-Fi with DHCP, you will need an ESSID (network name) and a password. Add this to <code>pikvm.txt</code>. If the file doesn't exists, just create it. Like following:</p> <pre><code>WIFI_ESSID='mynet'\nWIFI_PASSWD='p@s$$w0rd'\n</code></pre> <p>Note that backslash in the password should be escaped: <code>\\</code> should be written as <code>\\\\</code>.</p> <p>If there was a string <code>FIRST_BOOT=1</code> in the file, do not remove it. This is the trigger needed to initialize the OS at the first boot. On the contrary, if the file pikvm.txt does not exist, you should not add this line.</p> </li> <li> <p>Unmount partition and return the memory card to PiKVM.</p> </li> <li> <p>A few things to keep in mind:</p> <ul> <li>Note that after applying the settings, the pikvm.txt file will be deleted.</li> <li>WPA3 is not supported. Enable WPA2 on your router, while AES is supported, some aspects of it is not and you may need to disable AES for it to connect.</li> <li>There is a possibility that, in countries that support channel 13, the device will not connect. You will need to configure your router to disable channels 12-14 or disable Auto scan mode.</li> </ul> </li> </ol>"},{"location":"on_boot_config/#other-available-options","title":"Other available options","text":"<p>A number of other parameters can be applied in the same way as with Wi-Fi.</p> <p>Note</p> <p>The parameters must be specified strictly each on a separate line.</p> <ul> <li> <p><code>FIRST_BOOT=1</code> Triggers initialization of the first OS startup. The following actions are performed:</p> <ul> <li>Generates unique <code>/etc/machine-id</code> for internal systemd machinery.</li> <li>Generates unique SSH host keys.</li> <li>Generates unique SSL certificates for HTTPS and VNC.</li> <li>Generates Avahi ZeroConf service <code>/etc/avahi/services/pikvm.service</code> with Pi's serial number. But keeps Avahi disabled by default.</li> <li>Mass Storage image partition is reformatted to fill the available space at the end of SD card (only for V2+).</li> <li>Different minor things are performed like fc-cache update.</li> </ul> <p>Note that this option does not reset the OS to factory defaults. There is no way to do this other than reflashing.</p> </li> <li> <p><code>ENABLE_AVAHI=1</code> Triggers Avahi service generation (if needed) and enables <code>avahi-daemon</code>. It's disabled by default.</p> </li> <li> <p><code>ENABLE_OTG_SERIAL=1</code> Only for V2+. Enables a virtual serial port on a USB emulator, that can be used to log in to PiKVM from the target host side. Disabled for security reasons.</p> </li> <li> <p><code>SSH_PORT=1234</code> Changes SSH server port to 1234 instead of 22.</p> </li> <li> <p><code>ETH_DHCP=1</code> Configures Ethernet port for DHCP. This is a default for PiKVM OS.</p> </li> <li> <p><code>ETH_ADDR=192.168.0.100/24</code><code>ETH_DNS=8.8.8.8</code><code>ETH_GW=192.168.0.1</code> Configures a static IP on the Ethernet port. Only IPv4 is available here. For IPv6 you'll need to change systemd configuration files on the live OS. All three options must be set simultaneously to avoid incorrect configuration.</p> </li> <li> <p><code>WIFI_ESSID=foo</code><code>WIFI_PASSWD=bar</code> Configures Wi-Fi with DHCP, described in more detail in previous paragrpah. Both options must be set simultaneously to avoid incorrect configuration. Can be followed by several options:</p> <ul> <li> <p><code>WIFI_WPA23=1</code> Allows to connect to mixed WPA2/WPA3 network. Available only on new images >= 2025.03.03.</p> </li> <li> <p><code>WIFI_HIDDEN=1</code> Allows to connect to hidden Wi-Fi network. Available only on new images >= 2024.03.12.</p> </li> <li> <p><code>WIFI_ADDR=192.168.0.100/24</code><code>WIFI_DNS=8.8.8.8</code><code>WIFI_GW=192.168.0.1</code> Configures a static IP on the Wifi. Only IPv4 is available here. For IPv6 you'll need to change systemd configuration files on the live OS. All three options must be set simultaneously with <code>WIFI_ESSID</code> and <code>WIFI_PASSWD</code> to avoid incorrect configuration.</p> </li> </ul> </li> <li> <p><code>WIFI_REGDOM=US</code> Changes Wi-Fi regulatory domain to the US. Other domains available by ISO 3166-1 alpha-2 country codes.</p> </li> </ul>"},{"location":"on_boot_config/#advanced-production-deployment","title":"Advanced production deployment","text":"<p>For a production environment, it may be important to integrate PiKVM into an existing infrastructure automatically. Usually, such actions are performed by special scripts written by the administrator.</p> <p>To run such scripts, PiKVM OS suggests placing them in <code>pikvm-scripts.d</code> directory (<code>/boot/pikvm-scripts.d</code> on the system itself) on the same partition next to <code>pikvm.txt</code> file.</p> <p>If <code>pikvm.txt</code> exists, all the parameters described there will be applied, and the contents inside <code>pikvm-scripts.d</code> will be checked if this directory exists. Scripts in this directory are run in alphabetical order, the failure will be ignored, it is assumed that the script author should handle this situation.</p> <p>If the script needs to reboot the OS, it should create an empty file <code>/boot/pikvm-reboot.txt</code>. The reboot is performed once after all scripts.</p> <p>In order not to copy scripts manually on each memory card on each PiKVM, it may make sense to build a custom OS image containing everything you need.</p>"},{"location":"pass/","title":"HDMI Video Passthrough","text":""},{"location":"pass/#hdmi-video-passthrough","title":"HDMI Video Passthrough","text":"<p>This feature allows directing the video stream from the host to a display attached directly to the HDMI output of PiKVM V4 Plus. This simplifies accessing the host locally while retaining the remote access to the host via the Web UI or VNC. This feature is limited to PiKVM V4 Plus because it\u2019s the only PiKVM version with an HDMI Out port. It also works best with USB passthrough enabled.</p> <p>Info</p> <ul> <li>The passthrough feature supports a screen resolution up to 1920x1200 pixels.</li> </ul> <p>This is shown more clearly below:</p> <p></p>"},{"location":"pass/#setting-up-the-passthrough","title":"Setting up the passthrough","text":"<p>Connect the display to <code>OUT2</code> port on the back side of PiKVM V4 Plus. This feature should be enabled by default on new images.</p> <p>If not, follow two simple steps:</p> <ol> <li> <p>Update OS and reboot:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> </li> <li> <p>After rebooting, you will see an image on the physical display.</p> </li> </ol>"},{"location":"pass/#my-monitor-does-not-support-the-1920x1200-mode","title":"My monitor does not support the 1920x1200 mode","text":"<p>PiKVM V4 supports the advanced capture mode of 1920x1200. If your physical monitor is limited to 1920x1080, then part of the image from the bottom will be cropped.</p> <p>To avoid this, you can change the resolution of the host OS, or if the OS does not support this, disable the 1920x1200 mode on PiKVM itself:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# kvmd-edidconf --import-preset=v4plus.no-1920x1200\n[root@pikvm ~]# reboot\n</code></pre>"},{"location":"pass/#current-limitations","title":"Current limitations","text":"<p>Please note the feature is pretty new and will be improved.</p> <ul> <li> <p>Display resolution must be greater than or equal to that used by PiKVM capture. If the maximum display resolution is 720p and the signal has a 1080p resolution, you will not see the image. PiKVM does not perform any downscaling.</p> </li> <li> <p>At the same time, PiKVM will try to show at least something than nothing. If the input signal has a resolution of 1920x1200, and the display supports only 1920x1080, the image will be shown but cropped from the bottom so that you at least have the opportunity to adjust the image parameters of the host.</p> </li> <li> <p>Audio is not supported at the moment.</p> </li> </ul>"},{"location":"pass/#disabling-the-passthrough","title":"Disabling the passthrough","text":"<ol> <li> <p>Add few lines to <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>kvmd:\n streamer:\n forever: false\n cmd_remove:\n - \"--v4p\"\n</code></pre> </li> <li> <p>Perform <code>reboot</code>.</p> </li> </ol>"},{"location":"pico_hid/","title":"The Pico HID","text":"<p>A fast way to get PS/2 on PiKVM V2+</p> <p>If you need PS/2 keyboard & mouse on PiKVM V2, V3 and V4 Plus (but not V4 Mini or DIY based on Zero 2 W boards), you can use a faster and easier way: The Pico HID Bridge.</p> <p>Pico requirements</p> <p>Raspberri Pi Pico (the first model) based on RP2040 microcontroller is required. Pico 2 is not supported right now.</p> <p>The Pico HID is a part of DIY PiKVM V1 platform that performs keyboard and mouse emulation. It has excellent compatibility, and emulates USB by default, including two mouse modes: absolute and relative.</p> <p>Full list of features:</p> Feature Enabled by default USB Keyboard, absolute & relative mouse Yes USB Absolute Mouse for Windows 95 No PS/2 Keyboard & mouse No <p>The scope of the Pico HID is not limited to V1 platform, it can also be used with V2 and V3, if you need to emulate a PS/2 keyboard and mouse or use a legacy multiport KVM switch which does not fully support USB standards.</p> <p>This page explains how to build, connect and use all the features of the Pico HID.</p> <p>Software requirements</p> <p>KVMD >= 3.241 is required for the Pico HID. For new builds, this will be the case, but if you want to use the Pico HID on the old PiKVM, you will need to update OS.</p>"},{"location":"pico_hid/#making-the-pico-hid","title":"Making the Pico HID","text":"<p>If you are building PiKVM V1, then the hardware should already be assembled. Skip this step unless you need PS/2 support.</p> <p>But if you are making the Pico HID for V2 or V3, then follow this guide:</p> The Pico HID from scratch <p>Parts list:</p> <ul> <li> <p>x1 Raspberry Pi Pico board with soldered pins. Pico 2 is not supported right now.</p> </li> <li> <p>x1 USB-A to Micro-USB cable.</p> </li> <li> <p>x10 dupont wires female-female.</p> </li> <li> <p>x1 1N5819 diode. It's optional but strongly recommended. Any similar one will do.</p> <p>Warning</p> <p>The diode is needed to provide power to the Pico HID regardless of the target host state, which prevents the backpowering problem. It will allow you to keep the keyboard buttons pressed during the target host power cycle, which is, for example, important for MacOS to get into the boot menu.</p> <p>Do not connect the red wire (the <code>VSYS (Pico) -> 5V (Pi)</code> line) without a diode. If you can't find a diode, don't connect this wire at all.</p> </li> </ul> <p>Connect all the parts according to this scheme:</p> Simple wiring diagram <p></p> Electrical schematic diagram for advanced users <p></p>"},{"location":"pico_hid/#ps2-keyboard-mouse","title":"PS/2 Keyboard & Mouse","text":"Additional steps for PS/2 support <p>If you need PS/2 keyboard and mouse support, you will need a few additional components. Soldering skills will also come in handy.</p> <ul> <li>x1 3.3V/5V bi-directional logic level shifter like this.</li> <li>x2 PS/2 cable with male connector (can be salvaged from the an keyboard or mouse).</li> </ul> <p>Make sure that the level shifter pinout matches the scheme, and connect everything according to the Pico pinout.</p> <pre><code> >>> To the PC <<<\n _________________\n | |\nPico GP11 ______| LV1 HV1 |______ PS/2 keyboard data\nPico GP12 ______| LV2 HV2 |______ PS/2 keyboard clock\nPico GP13 ______| LV HV |______ PS/2 5V\nPico GND ______| GND GND |______ PS/2 GND\nPico GP14 ______| LV3 HV3 |______ PS/2 mouse data\nPico GP15 ______| LV4 HV4 |______ PS/2 mouse clock\n |_________________|\n</code></pre> <p>You can take the 5V power line from one of the PS/2, for example from the keyboard, or from both at once, but use a multimeter to make sure that both PS/2 female connectors have the same line.</p> <p></p> <p>PS/2 female socket pinout on the motherboard is the same for the keyboard and the mouse. A purple socket usually corresponds to the keyboard, and a green one to the mouse. If your motherboard only has one port, it's probably universal and can be used for both the keyboard and the mouse. Most likely, it will be painted both colors.</p> <p>Use a multimeter to determine the purpose of the wires in your PS/2 cables.</p> <p>A good idea is to mount the level shifter on top of the Pico, as in this photo:</p> <p></p> <p>Note</p> <p>Don't forget to enable PS/2 mode support as described in the next paragraph</p> Optional: PS/2 passthrough <p>This optional addon allows to use a real PS/2 keyboard and mouse together with emulated by PiKVM.</p> <p>These two ports work as PS/2 inputs and are passed through to the PS/2 output ports.</p> <pre><code> >>> To the REAL keyboard and mouse <<<\n _________________\n | |\nPico GP26 ______| LV1 HV1 |______ PS/2 keyboard data\nPico GP27 ______| LV2 HV2 |______ PS/2 keyboard clock\nPico GP13 _____| LV HV |______ PS/2 5V\nPico GND ______| GND GND |______ PS/2 GND\nPico GP16 ______| LV3 HV3 |______ PS/2 mouse data\nPico GP17 ______| LV4 HV4 |______ PS/2 mouse clock\n |_________________|\n</code></pre>"},{"location":"pico_hid/#configuring-the-hid-modes","title":"Configuring the HID modes","text":"<p>By default, Pico HID emulates a USB keyboard and an absolute or relative mouse (read here about the difference between mouse modes). For most cases, nothing needs to be changed here. However, if you need something special (like Windows 98 support), you can do it without reflashing the current firmware.</p> <p>To achieve this, the Pico HID uses a runtime configuration, which is set by connecting some GPIOs with Ground (<code>GND</code>) lines.</p> Pin name on the Pico board Description <code>GP2</code> Enable PS/2 keyboard & mouse support (see below). <code>GP3</code> Prefer the PS/2 keyboard over USB when turning on the HID (if PS/2 is enabled). <code>GP4</code> Prefer the PS/2 mouse over USB (if PS/2 is enabled) <code>GP6</code> Disable USB keyboard & mouse support. This is useful if you only want to use PS/2. <code>GP7</code> Enable the special USB absolute mouse for Windows 98. <code>GP8</code> Prefer the relative USB mouse over the absolute one. <code>GP9</code> Prefer the Windows 98 USB absolute mouse over the regular absolute one (if enabled). <p>Example</p> <p>To enable Windows 98 absolute mouse, just connect pin <code>GP9</code> to any <code>GND</code> on the Pico.</p>"},{"location":"pico_hid/#flashing-the-firmware","title":"Flashing the firmware","text":"<p>To upload the firmware to Pico HID, you can use any computer with a USB port.</p> <ol> <li>Download the latest release of the firmware. The file is called <code>pico-hid.uf2</code>.</li> <li>Press and hold the white button on the Pico board.</li> <li>While still holding the button, plug it in the computer using a USB cable.</li> <li>Release the button.</li> <li>The Pico board appears as a flash drive on your computer.</li> <li>Copy the <code>pico-hid.uf2</code> file to this flash drive.</li> <li>Safely eject the USB device.</li> </ol> <p>If you want to compile the firmware yourself, you can find the source code here.</p>"},{"location":"pico_hid/#the-final-steps","title":"The final steps","text":"<p>Connect the Pico HID to the target host using the USB cable.</p> <p>If you are building PiKVM V1, no further action with the Pico HID is required.</p> <p>If you are making the Pico HID for V2 or V3, add the following lines to the PiKVM configuration and reboot it:</p> <ul> <li> <p><code>/boot/config.txt</code> </p><pre><code>dtoverlay=spi0-1cs\n</code></pre> </li> <li> <p><code>/etc/kvmd/override.yaml</code>: </p><pre><code>kvmd:\n hid:\n type: spi\n chip: 0\n bus: 0\n sw_cs_pin: 7\n sw_cs_per_byte: true\n reset_pin: 25\n reset_inverted: true\n reset_self: true\n power_detect_pin: 16\n power_detect_pull_down: true\n</code></pre> </li> </ul>"},{"location":"pico_hid/#replacing-the-arduino-hid","title":"Replacing the Arduino HID","text":"<p>Warning</p> <p>This section is intended for advanced users of the legacy Arduino HID.</p> <p>It may seem tempting, but don't to use the Arduino HID for new PiKVM builds just because you have it at your fingertips. Connecting and flashing Arduino is much more time consuming than Pico. In addition, different Arduino board work with different voltages, they may or may not have SPI (for the Pico, we use SPI to free up the UART on Raspberry Pi for the console and other useful things), etc.</p> <p>Using the Pico HID is the recommended fast and standard way in the PiKVM world.</p> <p>The Pico HID can be used to replace the legacy Arduino HID. It can use both Serial (UART) port and the SPI. The connection scheme is also much simpler, getting rid of the transistor for the Reset line and the level shifter for RX/TX (MOSI/MISO).</p> For the Arduino HID over SPI <p>Throw away the Reset transistor and level shifter, and follow this guide from the very beginning, as if you were connecting Pico HID to PiKVM V2 or V3.</p> For the classic Serial (UART) HID <p>Get rid of the transistor and level shifter, and follow this guide from the very beginning, but the schemes and configs will be slightly different.</p> <ul> <li> <p>The <code>GP22</code> on the Pico is connected directly to the <code>GND</code>. This enables UART mode instead of the default SPI.</p> </li> <li> <p>In the good old PiKVM V0, <code>GPIO4</code> on the Raspberry Pi was used for the Reset line. Now we recommend to use <code>GPIO25</code> for consistency reasons. However, you can use <code>GPIO4</code> by changing the <code>reset_pin</code> value in the config example below. On the scheme, this is a yellow wire, the <code>RUN (Pico) -> GPIO25 (Pi)</code> line.</p> </li> </ul> Simple wiring diagram <p></p> Electrical schematic diagram <p></p> Configs <ul> <li> <p>Don't add line <code>dtoverlay=spi0-1cs</code> to the <code>/boot/config.txt</code> file. It's only needed for SPI.</p> </li> <li> <p><code>/etc/kvmd/override.yaml</code>: </p><pre><code>kvmd:\n hid:\n type: serial\n device: /dev/kvmd-hid\n reset_pin: 25\n reset_inverted: true\n reset_self: true\n power_detect_pin: 16\n power_detect_pull_down: true\n</code></pre> </li> </ul>"},{"location":"pico_hid_bridge/","title":"The Pico HID - PS/2 Bridge","text":"<p>Pico requirements</p> <p>Raspberri Pi Pico (the first model) based on RP2040 microcontroller is required. Pico 2 is not supported right now.</p> <p>The Pico HID Bridge is a special version of the generic Pico HID. It is a PS/2 keyboard and mouse emulator that connects to PiKVM via USB-A. Unlike generic Pico HID and legacy Arduino HID, it doesn't require SPI wiring with GPIO.</p> <p>It is suitable for all devices except V4 Mini and DIY based on Zero 2 W board.</p> <p>At one end it connects to USB-A on PiKVM, on the other side it has two PS/2 connectors for keyboard and mouse:</p> <p></p> <p>In addition, on PiKVM V2+, the use of Pico the HID Bridge does not exclude the use of a regular USB OTG port with Mass Storage emulation. Thus, on V2+ you will be able to use PS/2 and USB Mass Storage at the same time, and even switch between OTG HID and Pico HID.</p>"},{"location":"pico_hid_bridge/#making-the-bridge","title":"Making the Bridge","text":"<ul> <li>x1 Raspberry Pi Pico board with soldered pins.</li> <li>x1 USB-A to Micro-USB cable.</li> <li>x1 3.3V/5V bi-directional logic level shifter like this.</li> <li>x2 PS/2 cable with male connector.</li> <li>x2 Small dip jumpers.</li> </ul> <p>Make sure that the level shifter pinout matches the scheme, and connect everything according to the Pico pinout.</p> <pre><code> >>> To the PC <<<\n _________________\n | |\nPico GP11 ______| LV1 HV1 |______ PS/2 keyboard data\nPico GP12 ______| LV2 HV2 |______ PS/2 keyboard clock\nPico GP13 ______| LV HV |______ PS/2 5V\nPico GND ______| GND GND |______ PS/2 GND\nPico GP14 ______| LV3 HV3 |______ PS/2 mouse data\nPico GP15 ______| LV4 HV4 |______ PS/2 mouse clock\n |_________________|\n</code></pre> <p>You can take the 5V power line from one of the PS/2, for example from the keyboard, or from both at once, but use a multimeter to make sure that both PS/2 female connectors have the same line.</p> <p></p> <p>PS/2 female socket pinout on the motherboard is the same for the keyboard and the mouse. A purple socket usually corresponds to the keyboard, and a green one to the mouse. If your motherboard only has one port, it's probably universal and can be used for both the keyboard and the mouse. Most likely, it will be painted both colors.</p> <p>Use a multimeter to determine the purpose of the wires in your PS/2 cables.</p> <p>A good idea is to mount the level shifter on top of the Pico, as in this photo:</p> <p></p> <p>Finally, install DIP jumpers to soldered pins of the Pico to enable PS/2 and Bridge modes:</p> <ul> <li><code>GP2 <-> GND</code></li> <li><code>GP5 <-> GND</code></li> </ul> <p>Like this:</p> <p></p>"},{"location":"pico_hid_bridge/#ps2-passthrough","title":"PS/2 passthrough","text":"<p>This optional addon allows to use a real PS/2 keyboard and mouse together with emulated by PiKVM.</p> <p>These two ports work as PS/2 inputs and are passed through to the PS/2 output ports.</p> <pre><code> >>> To the REAL keyboard and mouse <<<\n _________________\n | |\nPico GP26 ______| LV1 HV1 |______ PS/2 keyboard data\nPico GP27 ______| LV2 HV2 |______ PS/2 keyboard clock\nPico GP13 _____| LV HV |______ PS/2 5V\nPico GND ______| GND GND |______ PS/2 GND\nPico GP16 ______| LV3 HV3 |______ PS/2 mouse data\nPico GP17 ______| LV4 HV4 |______ PS/2 mouse clock\n |_________________|\n</code></pre>"},{"location":"pico_hid_bridge/#flashing-the-firmware","title":"Flashing the firmware","text":"<p>To upload the firmware to Pico HID, you can use any computer with a USB port.</p> <ol> <li>Download the latest release of the firmware. The file is called <code>pico-hid.uf2</code>.</li> <li>Press and hold the white button on the Pico board.</li> <li>While still holding the button, plug it in the computer using a USB cable.</li> <li>Release the button.</li> <li>The Pico board appears as a flash drive on your computer.</li> <li>Copy the <code>pico-hid.uf2</code> file to this flash drive.</li> <li>Safely eject the USB device.</li> </ol> <p>If you want to compile the firmware yourself, you can find the source code here.</p>"},{"location":"pico_hid_bridge/#the-final-steps","title":"The final steps","text":"<p>Connect the Pico HID to the target host using PS/2 cable and USB to USB-A port on PiKVM.</p> <p>Add following lines to the PiKVM configuration and reboot it:</p> <ul> <li><code>/etc/kvmd/override.yaml</code>: <pre><code>kvmd:\n hid:\n type: serial\n device: /dev/kvmd-hid-bridge\n reset_pin: -1\n</code></pre></li> </ul>"},{"location":"port_forwarding/","title":"Port forwarding","text":"<p>If you need to make PiKVM accessible from Internet, the easiest way to achieve this is by forwarding a port on the router. In this case, an external (global) IP address must be assigned to the router. This service is provided by the ISP.</p> <p>Tip</p> <p>If using an external IP address is not possible, it is recommended to try the Tailscale VPN.</p> <ul> <li>To configure port forwarding, refer to the documentation of the router.</li> <li>The Web UI listening ports are <code>80</code> (HTTP) and <code>443</code> (HTTPS).</li> <li>By default, port <code>80</code> performs permanent forwarding to <code>443</code> for security reasons.</li> <li>Forwarding the port <code>443</code> is sufficient in most cases.</li> <li>If enabled, the VNC server runs on port <code>5900</code> (disabled by default).</li> </ul> <p>Warning</p> <ul> <li>Set strong passwords and enable two-factor authorization before opening access to PiKVM from the Internet!</li> <li>It is strongly recommended to obtain a valid HTTPS certificate, for example via Let's Encrypt.</li> <li>A good practice is using a custom port number instead of <code>443</code> from the Internet side, for example <code>14438</code>, to avoid common port scanners.</li> <li>If you still decide to use the <code>443</code> port number, you may want to forward port <code>80</code> to get a convenient redirect.</li> </ul> <p>Port forwarding is a powerful and convenient tool, but remember that security depends entirely on your configuration. In most cases, a VPN is a more secure, but less convenient option (since it requires a VPN client on all devices that access PiKVM).</p>"},{"location":"prometheus/","title":"Prometheus metrics","text":"<p>Prometheus is one of the popular monitoring systems. It pulls service's endpoint to get metrics in a simple text format. PiKVM has the ability to export some information to this system such as the server's ATX state, Pi's temperature, GPIO state and some other things.</p>"},{"location":"prometheus/#configure-prometheus","title":"Configure Prometheus","text":"<p>To enable Prometheus getting metrics from pikvm following config could be used:</p> <pre><code>scrape_configs:\n - job_name: \"pikvm\"\n metrics_path: \"/api/export/prometheus/metrics\"\n basic_auth:\n username: admin\n password: admin\n scheme: https\n static_configs:\n - targets: [\"pikvm\"]\n tls_config:\n insecure_skip_verify: true # For self-signed certificate\n</code></pre>"},{"location":"prometheus/#output-example","title":"Output example","text":"<p>This example includes the GPIO from the PiKVM's test config.</p> <pre><code>$ curl -k -HX-KVMD-User:admin -HX-KVMD-Passwd:admin https://pikvm/api/export/prometheus/metrics\n\n# TYPE pikvm_atx_enabled gauge\npikvm_atx_enabled 1\n\n# TYPE pikvm_atx_power gauge\npikvm_atx_power 0\n\n# TYPE pikvm_gpio_input_online_led1 gauge\npikvm_gpio_input_online_led1 0\n\n# TYPE pikvm_gpio_input_state_led1 gauge\npikvm_gpio_input_state_led1 0\n\n# TYPE pikvm_gpio_input_online_led2 gauge\npikvm_gpio_input_online_led2 0\n\n# TYPE pikvm_gpio_input_state_led2 gauge\npikvm_gpio_input_state_led2 0\n\n# TYPE pikvm_gpio_output_online_button1 gauge\npikvm_gpio_output_online_button1 0\n\n# TYPE pikvm_gpio_output_state_button1 gauge\npikvm_gpio_output_state_button1 0\n\n# TYPE pikvm_gpio_output_online_button2 gauge\npikvm_gpio_output_online_button2 0\n\n# TYPE pikvm_gpio_output_state_button2 gauge\npikvm_gpio_output_state_button2 0\n\n# TYPE pikvm_gpio_output_online_relay1 gauge\npikvm_gpio_output_online_relay1 0\n\n# TYPE pikvm_gpio_output_state_relay1 gauge\npikvm_gpio_output_state_relay1 0\n\n# TYPE pikvm_gpio_output_online_relay2 gauge\npikvm_gpio_output_online_relay2 0\n\n# TYPE pikvm_gpio_output_state_relay2 gauge\npikvm_gpio_output_state_relay2 0\n\n# TYPE pikvm_hw_temp_cpu gauge\npikvm_hw_temp_cpu 36.511\n\n# TYPE pikvm_hw_temp_gpu gauge\npikvm_hw_temp_gpu 35.0\n\n# TYPE pikvm_hw_throttling_freq_capped_now gauge\npikvm_hw_throttling_freq_capped_now 0\n\n# TYPE pikvm_hw_throttling_freq_capped_past gauge\npikvm_hw_throttling_freq_capped_past 0\n\n# TYPE pikvm_hw_throttling_throttled_now gauge\npikvm_hw_throttling_throttled_now 0\n\n# TYPE pikvm_hw_throttling_throttled_past gauge\npikvm_hw_throttling_throttled_past 0\n\n# TYPE pikvm_hw_throttling_undervoltage_now gauge\npikvm_hw_throttling_undervoltage_now 0\n\n# TYPE pikvm_hw_throttling_undervoltage_past gauge\npikvm_hw_throttling_undervoltage_past 0\n\n# TYPE pikvm_hw_throttling_raw_flags gauge\npikvm_hw_throttling_raw_flags 0\n* Connection #0 to host localhost left intact\n</code></pre>"},{"location":"pst/","title":"Persistent storage","text":"<p>Note</p> <p>This feature is available on images newer than 2022.06.20</p> <p>Sometimes advanced use of PiKVM requires storing some data on disk like API keys, config files, or something like that. For example, you want to have a script that will update SSL certificates once a week. However, the root file system is in a read-only state and does not involve remounting automatically by user scripts.</p> <p>To solve this problem, new versions of PiKVM have a small 256MiB storage partition that can be used to store that data. A special <code>kvmd-pst</code> daemon makes sure that this partition is mounted in read-only all the time, and remounts it to RW only when some user script requires it. This also solves the problems of simultaneous access, so the RW mode will be kept as long as at least one client is working with the storage.</p>"},{"location":"pst/#usage","title":"Usage","text":"<p>Below is an example of a script <code>/root/test.sh</code> that wants to save a certain file in PST:</p> <pre><code>#!/bin/bash\necho `date` + $@ > $KVMD_PST_DATA/foo\ncat $KVMD_PST_DATA/foo\n</code></pre> <p>To run it use: </p><pre><code># kvmd-pstrun -- /root/test.sh --some --script --args\n-- INFO -- Opening PST session ...\n-- INFO -- PST write is allowed: /var/lib/kvmd/pst/data\n-- INFO -- Running the process ...\nMon Jun 20 04:23:14 MSK 2022 + --some --script --args\n-- INFO -- Process finished: returncode=0\n</code></pre> <p>So, what's going on here:</p> <ol> <li> <p><code>kvmd-pstrun</code> connects to the <code>kvmd-pst</code> daemon, which manages the mounting of the storage.</p> </li> <li> <p>If everything is fine, the daemon will remount the storage to RW mode and report the data root to <code>kvmd-pstrun</code>.</p> </li> <li> <p><code>kvmd-pstrun</code> runs the script and pass the data root path using the environment variable <code>KVMD_PST_DATA</code> (<code>/var/lib/kvmd/pst/data</code>).</p> </li> <li> <p>If the <code>kvmd-pst</code> daemon stops or any other daemon error occurs, the script will be killed.</p> </li> <li> <p>After the script is finished, the daemon will remount the storage to RO mode.</p> </li> </ol> <p>To be able to write to the storage, the user must be a member of <code>kvmd-pst</code> group, or have to be <code>root</code>.</p> <p>The return code will be equal to the script code if it was run, or 1 if a remount error occurred.</p>"},{"location":"reverse_proxy/","title":"Reverse proxy","text":"<p>A reverse proxy allows you to pass requests through your web server to another site or program. The reverse proxy will make it look like PiKVM Web UI is a page within your existing site.</p> <p>This is especially useful if:</p> <ul> <li> <p>You need to access the WebUI on port <code>80</code> or <code>443</code> but you already host a website on the same device.</p> </li> <li> <p>You want to share SSL certificates with an existing site.</p> </li> <li> <p>You want to share authentication with an existing setup.</p> </li> </ul>"},{"location":"reverse_proxy/#pikvm-configuration","title":"PiKVM Configuration","text":"<p>PiKVM supports reverse proxying since KVMD 4.51. For older version, please update OS first:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> <p>By default, PiKVM redirects all requests from HTTP port <code>80</code> to HTTPS port <code>443</code> with self-signed certificate. For the simplest configuration, you can leave it as it is, and terminate SSL traffic from PiKVM on your web server.</p> <p>Alternatively, you can change the HTTP and HTTPS ports on PiKVM or disable HTTPS at all to deliver HTTP-only traffic to your server.</p> <p>In both cases you should take care of your own SSL certificate for your web server because when using HTTP-only access to your website, you will lose the ability to use some features such as Direct H.264 streaming, because browser security policies will require HTTPS for them.</p> Various examples with changing HTTP/HTTPS settings <p>PiKVM uses Nginx internally, so don't be confused by its own configuration, it has nothing to do with your reverse proxy if you're using Nginx too.</p> <ul> <li> <p>Changing HTTP and HTTPS ports. Place this config to <code>/etc/kvmd/override.yaml</code> on PiKVM:</p> <pre><code>nginx:\n https:\n port: 4430\n http:\n port: 8080\n</code></pre> </li> <li> <p>Disabling HTTPS. All requests will be handled via HTTP port <code>80</code>.</p> <pre><code>nginx:\n https:\n enabled: false\n</code></pre> </li> </ul> <p>Don't forget to run <code>systemctl restart kvmd-nginx</code> to apply your changes.</p>"},{"location":"reverse_proxy/#server-configuration","title":"Server Configuration","text":"<p>If you have access to your web server\u2019s configuration use the following examples to pass the location <code>/pikvm</code> on the server to PiKVM Web UI hosted on <code>https://pikvm.local</code> on HTTPS port <code>443</code>.</p>"},{"location":"reverse_proxy/#nginx","title":"Nginx","text":"<p>Nginx does not validate certificates by default and PiKVM's self-signed certificate is fine for it.</p> <pre><code>location /pikvm {\n rewrite ^/pikvm$ / break;\n rewrite ^/pikvm\\?(.*)$ ?$1 break;\n rewrite ^/pikvm/(.*)$ /$1 break;\n proxy_redirect ~^(/.*)$ /pikvm$1;\n proxy_pass https://pikvm.local;\n\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Scheme $scheme;\n proxy_set_header X-Forwarded-Proto $scheme;\n proxy_set_header X-Forwarded-Port $server_port;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n\n # For some handles (like MJPEG) buffering should be disabled\n postpone_output 0;\n proxy_buffering off;\n proxy_ignore_headers X-Accel-Buffering;\n\n # Some handles (ends with /ws) are WebSockets\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection \"upgrade\";\n proxy_connect_timeout 7d;\n proxy_send_timeout 7d;\n proxy_read_timeout 7d;\n\n # Some other handles requires big POST payload\n client_max_body_size 0;\n proxy_request_buffering off;\n}\n</code></pre>"},{"location":"reverse_proxy/#caddy","title":"Caddy","text":"<p>Caddy doesn't like self-signed certificates, so we'll have to convince it that it's okay.</p> <pre><code>handle_path /pikvm/* {\n reverse_proxy https://pikvm.local {\n transport http {\n tls_insecure_skip_verify # Same behaviour as Nginx\n }\n header_up Host {upstream_hostport}\n header_down Location \"^(/.*)$\" \"/pikvm$1\"\n }\n}\n</code></pre>"},{"location":"switch/","title":"PiKVM Switch Multiport Extender Quickstart Guide","text":""},{"location":"switch/#pikvm-switch-multiport-extender","title":"PiKVM Switch Multiport Extender","text":"<p>Where to buy?</p> <ul> <li>International store.</li> <li>Canadian store.</li> <li>EU is coming!</li> </ul> <p></p> <p>PiKVM Switch Datasheet (PDF)</p> <p>The PiKVM Switch Multiport Extender enables one PiKVM device to view and control multiple target computers connected to each port. Target computers are viewed using HDMI video capture and then controlled via USB and ATX connections. Up to five Switch Multiport Extenders can be daisy-chained for a total of 20 ports. This is the maximum number of target computers that can be controlled by each supported PiKVM device.</p> <p>Thanks to the modularity of PiKVM and the new Switch, you can build up your infrastructure gradually, adding new Switches as needed, without replacing the KVM entirely.</p> <p>One target system at a time can be selected for HDMI video capture and USB control. ATX statuses and controls are available for all connected targets simultaneously. Video inputs include dedicated EDID (HDMI information and display parameters) and full control of the video connection state of each port.</p> <p>The PiKVM Switch is fully plug-and-play.</p> <p>It is compatible with PiKVM V4 Plus, PiKVM V3, DIY V2 and DIY V1 devices.</p> <p>Please note that it's not compatible with PiKVM V4 Mini and DIY devices based on Raspberry Pi Zero boards because of the lack of available USB host ports.</p>"},{"location":"switch/#installation-requirements","title":"Installation requirements","text":"<ul> <li> <p>Head device: PiKVM V4 Plus (recommended) or any other PiKVM except V4 Mini and Zero-based DIY.</p> </li> <li> <p>The PiKVM Switch box includes:</p> <ul> <li>Switch device</li> <li>Power supply unit</li> <li>DC Barrel Jack Cable</li> <li>HDMI 2.0 Cable</li> <li>USB-A Male To USB-C Female Adapter</li> <li>2x USB Cable, USB-C Male</li> <li>4x ATX kit with brackets and wires</li> </ul> </li> <li> <p>Some cables are not included in the kit, but are required to connect each target host port:</p> <ul> <li>HDMI 2.0 cable (no shorter than 30 centimeters).</li> <li>USB-A to USB-C cable</li> <li>Straight Ethernet cable for ATX connection.</li> </ul> </li> </ul>"},{"location":"switch/#setup","title":"Setup","text":"<ol> <li> <p>Turn off the head PiKVM device.</p> </li> <li> <p>Unpack the box. Turn Switch in your hands and study the purpose of the ports. Lovingly pat the top cover to show it that you want to be friends.</p> <ul> <li>The numbered ports on the front can be used to connect to the target hosts.</li> <li>UPLINK ports should be connected to PiKVM or to the superior chained Switch.</li> <li>DOWNLINK ports should be connected to a lower-level Switch.</li> </ul> </li> <li> <p>Connect Switch to PiKVM according to the following diagram. Example connections with PiKVM V4 Plus are shown, but similar connections can be made for any supported model.</p> <p></p> <ul> <li>(1) OTG connection for USB emulation (using Type-C cable).</li> <li>(2) Video (using HDMI cable).</li> <li>(3) USB control connection (using Type-C cable and included C-to-A adapter).</li> <li>(4) Optional power chaining. If you're using PiKVM V4 Plus, both PiKVM and Switch can be powered from a single 12V power supply. Use the supplied two-way power cable to connect the PiKVM and Switch.</li> <li>(5) Connect the supplied 12V power supply here.</li> </ul> <p>Double power supply is not allowed</p> <ul> <li> <p>When power chaining (4), never use your own 5V power port on the PiKVM V4.</p> </li> <li> <p>The two 12V connectors on the Switch are designed for chaining only. Never connect two power supplies to your Switch.</p> </li> </ul> <p>If you want to connect multiple Switches in a chain, use the following diagram. Two connected units can be considered as a single device, and the left group of UPLINK ports areused in a similar way: either connect it to a PiKVM as in the previous step, or connect to another Switch to.</p> <p></p> <p>Chaining limit</p> <p>A maximum of 5 Switch units can be connected in a chain.</p> </li> <li> <p>Connect the target hosts to the numbered ports on the front panel of Switch.</p> <ul> <li>HDMI for a video (don't use a cable shorter than 50 centimeters).</li> <li>USB-C for USB emulation.</li> <li>Optional ATX for power management of the host.</li> </ul> </li> <li> <p>PiKVM Switch is a Plug-n-Play device, so you don't need to write any complex configs. All you need is a fresh PiKVM OS and drivers that can be obtained by updating.</p> <p>Check the OS image</p> <p>To store the settings, Switch uses the Persistent Storage feature, which is presented in images older than 2022.06.20. To check if your PiKVM OS supports this, use the following command:</p> <pre><code>[root@pikvm ~]# mount | grep '\\<pst\\>'\n/dev/mmcblk0p2 on /var/lib/kvmd/pst type ext4 (ro,nosuid,nodev,noexec,relatime,errors=remount-ro)\n</code></pre> <p>If the output is similar to the above (<code>/var/lib/kvmd/pst</code>), then everything is fine. Otherwise on empty output, you need to reflash the OS.</p> <p>Do the update anyway (even if you did reflashing):</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> </li> <li> <p>It's done! PiKVM will automatically configure all your Switches.</p> </li> </ol>"},{"location":"switch/#working-with-the-switch","title":"Working with the Switch","text":"<p>All the functions of the Switch are available through the menu, which you will see in the PiKVM interface. The attached example uses two Switches, and switching between their ports works transparently.</p> <p></p> <ul> <li> <p>The menu title shows the current active port (1.4) in unit.port format, and the status of the ATX power and HDD LEDs for its host.</p> </li> <li> <p>(1) The Settings button shows the common chain settings window (see below).</p> </li> <li> <p>(2) The ports are grouped by physical units, the sub-header of the table shows the unit 1 and the ports following it: 1.1, 1.2, 1.3 and 1.4.</p> </li> <li> <p>(3) Beacon activation buttons for the UPLINK and DOWNLINK ports on the back of the Switch unit 1. When activated, the corresponding multifunction LED on the back of the Switch will start flashing to make it easier to find its connectors. This is especially useful if you have several Switches in a chain.</p> </li> <li> <p>(4) The port switching button. The green color indicates the current active port.</p> </li> <li> <p>(5) A button for configuring individual port parameters such as name, EDID, and more.</p> </li> <li> <p>(6) The beacon activation button for the selected port activates the flashing LED on the numbered group of connectors on the front of the Switch unit.</p> <p>There are four indicators to the right: host video detected, USB detected, ATX power and HDD LEDs. Next, three ATX action buttons.</p> </li> <li> <p>(7) The title of the sub-table of the Switch unit 2. The units are numbered according to the closeness to PiKVM device: Switch number 1 is connected directly to PiKVM, unit 2 is connected to downlink of unit 1.</p> </li> </ul> <p>In the settings menu, you can access the EDIDs Collection and customize the color scheme of the Switch LEDs.</p>"},{"location":"switch/#chain-settings","title":"Chain settings","text":"<p>In the settings menu, you can access the EDIDs Collection and customize the color scheme of the Switch LEDs.</p> <p>Each port can use its own EDID which must be preloaded into the Collection, otherwise it will use the default EDID (taken from PiKVM). Binary and text EDID in HEX format are supported.</p> EDIDs Collection Color scheme"},{"location":"switch/#port-settings","title":"Port settings","text":"<p>In the port settings, you can set the display name (can be used for the name of the connected host) and the individual EDID from the Collection.</p> <p>Other parameters relate to the ATX intervals for pressing the power and reset buttons of the target host.</p>"},{"location":"switch/#firmware-updating","title":"Firmware updating","text":"<p>Sometimes we release firmware updates for the Switch, which are distributed along with PiKVM OS updates. When the software detects that your switch has an old firmware, it will inform you about it via the web interface. After that, you will be able update the Switch.</p> <p>If you have several switches in the chain, then all devices will be updated: first, PiKVM uploads the update to the first switch, then it updates the next one, and so on. This is very convenient because you don't have to perform complex manual manipulations to maintain your equipment. The Switches are intelligent and save you time.</p> <p>Warning</p> <p>We recommend updating the firmware only if you have physical access to the hardware.</p> <p>Switches are extremely difficult to brick, but if there is a power failure during updating, you will need physical access to restore the device. So don't worry, it can't be bricked forever.</p> <p>It is also recommended to perform all the operations described below via SSH, and not via a web terminal.</p>"},{"location":"switch/#performing-update","title":"Performing update","text":"<p>Just run these commands via SSH under root:</p> <pre><code>[root@pikvm ~]# cd /usr/share/kvmd/switch\n[root@pikvm switch]# systemctl stop kvmd # This will stop the KVM web service\n[root@pikvm switch]# make install # Flash the first switch\n[root@pikvm switch]# systemctl start kvmd # Start it again\n</code></pre> <p>The switches will show the progress of the update on the front LEDs and will gradually return to service.</p>"},{"location":"switch/#known-issues","title":"Known issues","text":"A DIY PiKVM device based on HDMI-CSI board does not receive a video through the Switch <p>Some HDMI-CSI boards does not follow the HDMI specification correctly. We have provided a special compatibility mode for them, which should be enabled using the following configuration:</p> <ol> <li> <p>Switch filesystem to RW-mode:</p> <pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Add some lines to <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>kvmd:\n switch:\n ignore_hpd_on_top: true\n</code></pre> </li> <li> <p>Restart KVMD:</p> <pre><code>[root@pikvm ~]# systemctl restart kvmd\n</code></pre> </li> <li> <p>Switch filesystem back to RO-mode:</p> <pre><code>[root@pikvm ~]# ro\n</code></pre> </li> </ol>"},{"location":"tailscale/","title":"Tailscale VPN","text":"<p>The Tailscale VPN can be used to access PiKVM from the Internet if configuring port forwarding is not possible or more security is desired. Tailscale is a convenient and free (for private use) tool for organizing a small VPN network.</p> <p>The basic Tailscale configuration commands are shown below. For detailed instructions, refer to Tailscale support.</p>"},{"location":"tailscale/#configuring-the-pikvm","title":"Configuring the PiKVM","text":"<ol> <li> <p>Update OS:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> </li> <li> <p>Install the Tailscale client, run <code>tailscaled</code> service and register it in the network:</p> <pre><code>[root@pikvm ~]# rw\n# If you were afraid to pikvm-update above first run pacman -Syy\n[root@pikvm ~]# pacman -S tailscale-pikvm\n[root@pikvm ~]# systemctl enable --now tailscaled\n[root@pikvm ~]# tailscale up\n</code></pre> </li> <li> <p>Follow the link to authorize this installation. You likely want to disable key expiry!</p> </li> <li> <p>After authorization success, reboot to make sure that everything works correctly:</p> <pre><code>[root@pikvm ~]# reboot\n</code></pre> </li> <li> <p>Now, you can view the IP address of the Tailscale network interface:</p> <pre><code>[root@pikvm ~]# ip addr show tailscale0\n</code></pre> </li> </ol> <p>If everything is successful, PiKVM will become a member of your VPN network.</p> <p>Do not update Tailscale if you don't have access to PiKVM without VPN</p> <p>Unfortunately, sometimes, updating the Tailscale client can cause problems due to breaking changes. These are compatibility issues on the Tailscale side. Remember this when updating.</p>"},{"location":"tailscale/#configuring-a-client-device","title":"Configuring a client device","text":"<ul> <li>Download and install the Tailscale client to the system you are using (not to the system you want to control).</li> <li>Check the Tailscale admin page to view your VPN network.</li> <li>Follow the URL in the web browser: <code>https://<tailscale_kvm_ip></code> and you will see the PiKVM web interface.</li> </ul>"},{"location":"tailscale/#using-tailscale-certificates","title":"Using Tailscale Certificates","text":"<p>PiKVM uses self-signed SSL certificates out of the box. You can also use Tailscale certificates in place of the default one.</p> <p>Warning</p> <p>Tailscale certificates are provided by Let's Encrypt and has a default expiry of 90 days. There is currently no mechanism available to auto-renew Tailscale certificate. You may put the commands below in a script to simplify process.</p> <ol> <li> <p>Switch filesystem to RW if in ReadOnly mode and delete existing PiKVM certificates for nginx and vnc.</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# rm -v /etc/kvmd/{nginx,vnc}/ssl/*.{crt,key}\n</code></pre> </li> <li> <p>Provision new certificates using <code>tailscale cert</code> command. Optionally you may create a directory to store the certificates.</p> <pre><code>[root@pikvm ~]# mkdir .cert\n[root@pikvm ~]# cd .cert\n[root@pikvm .cert]# tailscale cert <tailscale_hostname>\n</code></pre> </li> <li> <p>Copy the certificates to nginx's and vnc's ssl directories.</p> <pre><code>[root@pikvm ~]# cp /root/.cert/<tailscale_hostname>.key /etc/kvmd/nginx/ssl/server.key\n[root@pikvm ~]# cp /root/.cert/<tailscale_hostname>.crt /etc/kvmd/nginx/ssl/server.crt\n</code></pre> <p>Repeat the same steps for vnc if you have configured it.</p> <pre><code>[root@pikvm ~]# cp /root/.cert/<tailscale_hostname>.key /etc/kvmd/vnc/ssl/server.key\n[root@pikvm ~]# cp /root/.cert/<tailscale_hostname>.crt /etc/kvmd/vnc/ssl/server.crt\n</code></pre> </li> <li> <p>Grant file ownership to nginx and vnc services. Switch filesystem to ReadOnly again</p> <pre><code>[root@pikvm ~]# chown :kvmd-nginx /etc/kvmd/nginx/ssl/*\n[root@pikvm ~]# chown :kvmd-vnc /etc/kvmd/vnc/ssl/*\n[root@pikvm ~]# ro\n</code></pre> </li> <li> <p>Restart nginx and vnc services</p> <pre><code>[root@pikvm ~]# systemctl restart kvmd-nginx\n[root@pikvm ~]# systemctl restart kvmd-vnc\n</code></pre> </li> </ol>"},{"location":"tailscale/#automated-ephemeral-tailscale-certificates-renewal","title":"Automated Ephemeral Tailscale Certificates Renewal","text":"<p>Tailscale has a nice option of running an HTTPS on your behalf within your tailnet: <code>tailscale serve</code>. It is using Let's Encrypt certificates and renews them every 90 days. The issue is that PiKVM\u2019s filesystem is read-only. While tailscale will diligently request new certificates, it will fail to write it on the disk and hence will try to request new certificates next time you access your web server. Let's Encrypt has a limit of 5 certificates for the server per week, so you will end up with an inoperable server and rate-limited by Let's Encrypt for a day or so.</p> <p>Here's the command that allows you to seamlessly run HTTPS proxy for your PiKVM: </p><pre><code>[root@pikvm ~]# tailscale serve --bg https+insecure://localhost:443\n</code></pre> And if you want to stop tailscale from serving HTTPS, you can do this by running: <pre><code>[root@pikvm ~]# tailscale serve --https=443 off\n````\n\n### Root cause\nTailscale needs to refresh TLS certificates and write state under `/var/lib/tailscale`. \nOn PiKVM, the root filesystem is read-only, so direct writes fail. \n\nWe can fix this by mounting an **ephemeral overlay filesystem (tmpfs) in RAM** for `/var/lib/tailscale`, backed by a persistent lowerdir (`/root/tailscale-state`).\n\nThis ensures that certificate rotation and state writes work without breaking PiKVM\u2019s read-only state.\n\n!!! warning\n The **caveat** is that renewed certificates exist only in RAM. After a reboot, Tailscale falls back to the older certificates on disk, requests fresh ones, and stores them in RAM again.\n If you reboot PiKVM too frequently, this can trigger Let's Encrypt's rate limits.\n\n### Solution\n\nCore idea:\n- Mount a **tmpfs** over Tailscale's state folder stored in root's home: /root/tailscale-state. \n- Mount the resulting *merged* layer onto the actual Tailscale state folder at /var/lib/tailscale.\n- An **overlayfs** will transparently present this folder to Tailscale, while changes are kept in the RAM-based overlay layer.\n\n**Note**: Overlayfs requires that the upperdir and workdir exist before creating the overlay.\nSince these directories live in RAM, they disappear after every reboot.\nThis means we cannot use fstab to declare the mount points.\nInstead, we implement this with a systemd service that runs a setup script during boot, before tailscaled starts.\n\n1. Switch filesystem to RW and copy Tailscale state:\n\n```console\n[root@pikvm ~]# rw\n[root@pikvm ~]# cp -a /var/lib/tailscale /root/tailscale-state\n````\n\n2. Create a helper script, save as `/usr/local/bin/setup-tailscale-overlay.sh`:\n\n```bash\n#!/bin/bash\nset -e\n\n# Make tmpfs for tailscale overlay\nmkdir -p /tmp/tailscale-tmpfs\nmountpoint -q /tmp/tailscale-tmpfs || mount -t tmpfs tmpfs /tmp/tailscale-tmpfs\n\n# Prepare overlay dirs\nmkdir -p /tmp/tailscale-tmpfs/upper\nmkdir -p /tmp/tailscale-tmpfs/work\nmkdir -p /tmp/tailscale-merged\n\n# Mount overlay (lowerdir = persistent readonly state in /root)\nmountpoint -q /tmp/tailscale-merged || mount -t overlay overlay \\\n -o lowerdir=/root/tailscale-state,upperdir=/tmp/tailscale-tmpfs/upper,workdir=/tmp/tailscale-tmpfs/work \\\n /tmp/tailscale-merged\n\n# Bind merged to /var/lib/tailscale\nmountpoint -q /var/lib/tailscale && umount /var/lib/tailscale || true\nmount --bind /tmp/tailscale-merged /var/lib/tailscale\n</code></pre> <p>Make it executable:</p> <pre><code>[root@pikvm ~]# chmod +x /usr/local/bin/setup-tailscale-overlay.sh\n</code></pre> <ol> <li>Create a systemd unit</li> </ol> <p>We need to run the overlay setup after <code>/tmp</code> is mounted but before <code>tailscaled.service</code>.</p> <p>Save as <code>/etc/systemd/system/tailscale-overlay.service</code>:</p> <pre><code>[Unit]\nDescription=Setup overlayfs for Tailscale\nAfter=local-fs.target tmp.mount\nBefore=tailscaled.service\n\n[Service]\nType=oneshot\nExecStart=/usr/local/bin/setup-tailscale-overlay.sh\nRemainAfterExit=yes\n\n[Install]\nWantedBy=multi-user.target\n</code></pre> <p>Notes:</p> <ul> <li><code>local-fs.target</code> ensures all local filesystems (including <code>/tmp</code> tmpfs from fstab) are mounted.</li> <li><code>tmp.mount</code> is added explicitly in case your system defines it.</li> <li> <p>Overlay is mounted and bound before <code>tailscaled</code> starts.</p> </li> <li> <p>Enable and reload</p> </li> </ul> <pre><code>[root@pikvm ~]# systemctl daemon-reload\n[root@pikvm ~]# systemctl enable tailscale-overlay.service\n[root@pikvm ~]# ro\n</code></pre>"},{"location":"tailscale/#boot-sequence-recap","title":"Boot sequence recap:","text":"<ol> <li>tmpfs is mounted at <code>/tmp/tailscale-tmpfs</code></li> <li><code>upper</code> + <code>work</code> dirs are recreated inside tmpfs</li> <li>overlay is mounted with <code>/root/tailscale-state</code> as lowerdir</li> <li>overlay bind-mounted to <code>/var/lib/tailscale</code></li> <li><code>tailscaled.service</code> starts with writable state</li> </ol>"},{"location":"tailscale/#troubleshooting","title":"Troubleshooting","text":"<ul> <li> <p>If something does not work, the usual advice is to completely remove Tailscale from PiKVM and perform a clean installation:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Rscnd tailscale\n[root@pikvm ~]# rm -rf /var/lib/tailscale /var/cache/tailscale\n[root@pikvm ~]# reboot\n</code></pre> </li> </ul> <p>Now, follow the instructions from the beginning to re-install Tailscale.</p> <ul> <li> <p>In case of certificate issues you can try the following steps to debug and fix.</p> </li> <li> <p>Check if the services are running. If not please start them. For example, web UI service can be checked using:</p> <pre><code>[root@pikvm ~]# systemctl status kvmd-nginx\n</code></pre> <p>For VNC:</p> <pre><code>[root@pikvm ~]# systemctl status kvmd-vnc\n</code></pre> </li> <li> <p>If the services are running but not accessible or showing a warning, check the respective logs. For web UI:</p> <pre><code>[root@pikvm ~]# journalctl -xeu kvmd-nginx\n</code></pre> </li> <li> <p>If the logs shows TLS/certificate/permissions errors, the issue may be with file ownership. The services must have at least the group ownership of the certificates. The ownership should look similar to this:</p> <pre><code>[root@pikvm ~]# ls -l /etc/kvmd/{nginx,vnc}/ssl\n/etc/kvmd/nginx/ssl:\ntotal 8\n-r--r--r-- 1 root kvmd-nginx 2872 Jan 3 16:07 server.crt\n-r--r----- 1 root kvmd-nginx 227 Jan 3 16:07 server.key\n\n/etc/kvmd/vnc/ssl:\ntotal 8\n-r--r--r-- 1 root kvmd-vnc 2872 Jan 3 16:07 server.crt\n-r--r----- 1 root kvmd-vnc 227 Jan 3 16:07 server.key\n</code></pre> </li> </ul>"},{"location":"tesmart/","title":"TESMART managed multiport KVM switch","text":"<p>The TESMART managed switch can be controlled by PiKVM to allow it to connect to multiple hosts. A typical scenario is a single PiKVM device which can control and switch between multiple hosts or servers using the TESMART switch. UI elements can be added to the GPIO dropdown to allow switching between hosts from the PiKVM webpage.</p> <p>The instructions here were tested with the TESMART HKS1601A10 HDMI 16x1 switch. This should work with any of the other TESMART variants which have a LAN port - there is both a 8x1 and 4x1 variant. This was tested with an RPI4, but as this is executed over a network protocol, this should with almost anything.</p>"},{"location":"tesmart/#connections","title":"Connections","text":"<p>From a high level, the TESMART switch uses standard connections to the host machines (USB-A to USB-B and HDMI). The Raspberry Pi OTG connector (the one coming from the USB-C port on a Pi 4 via the custom splitter cable or device) should be connected to one of the USB 2 output ports on the TESMART switch (not the keyboard/mouse port). Based on your specific devices, and to get boot images to mount, you may need to connect this through a USB 2 hub.</p> <ol> <li> <p>Connect the USB-A cable from the Raspberry Pi OTG port to one of the TESMART switch USB 2 output ports on the back of the switch (not the keyboard/mouse ports).</p> </li> <li> <p>Connect the HDMI out from the TESMART switch to the Raspberry Pi CSI-2 to HMDI input.</p> </li> <li> <p>Connect the LAN port on the front of the switch using standard ethernet cable into one of your network switches.</p> </li> <li> <p>Connect host USB and HDMI cables from the TESMART switch to the machines to be managed per the switch instructions.</p> </li> </ol> <p>Warning</p> <p>There is a limitation in the underlying PiKVM software related to plugging video cables from a host which is already powered and connected to a monitor to a Raspberry Pi CSI2-HDMI encoder. These limitations apply equally when using the TESMART KVM switch. If video is not present in PiKVM, try keeping all host machines off and connecting them directly to the TESMART switch before powering the hosts on.</p>"},{"location":"tesmart/#setting-the-ip-address-of-the-tesmart-switch","title":"Setting the IP Address of the TESMART switch","text":"<p>In some ways, this is the most complex part of this. The default IP address of the TESMART switch is 192.168.1.10. If that happens to work with your IP addressing scheme and current set of addresses, then you may be all set. This IP address is not configurable via DHCP or other standard mechanisms. The only way to change it is with a Windows utility available on the TESMART Downloads Page.</p> <p>If you need to change it, you will first need to connect to the switch with a Windows machine, most easily directly through an ethernet cord, with your Windows laptop (or VM) up and assigned to a fixed IP address, such as 192.168.1.5. Once you've launched the utility you will see this screen:</p> <p></p> <p>On this screen, ensure you are on the \"General\" tab. Click the radio button for \"Network control\". Change the IP address to the default for the switch (may already be this -- 192.168.1.10). Press the \"Connect\" button. Should make the status light go green, as well as the selected port. If you do not get a connection here, you cannot proceed to change the IP address. To change the IP address, change to the \"Settings\" tab at the top. You will then see this screen:</p> <p></p> <p>On this screen, change to your desired IP address, gateway, mask, and port. Then press apply. Watch the box on the right to see if it applied OK. Press Query again to double-check. The actual IP address will not be changed until you power off/power on the switch. Make sure you have these settings correct, because if you get them wrong you would have to connect over RS232/serial and not the network.</p> <p>There may be alternatives other than changing the IP address in this manner if you don't have access to a Windows machine or if this address doesn't work for you. See this README for other options (Images and concepts from the bash file were borrowed for creation of this plugin). This also contains a summary of the protocol, which is also available on the TESMART downloads page.</p>"},{"location":"tesmart/#adding-ui-elements-to-control-the-kvm-switch","title":"Adding UI elements to control the KVM switch","text":"<p>The UI can be updated to add buttons to switch between KVM inputs and indicators for which input is currently selected. The instructions below will make these available in the PiKVM UI after clicking the \"Switches\" menu button in the KVM view.</p> <ol> <li> <p>Enable read-write mode on the SD card via <code>rw</code></p> </li> <li> <p>Edit the <code>/etc/kvmd/override.yaml</code> file and include the following:</p> <pre><code>kvmd:\n gpio:\n drivers:\n tes:\n type: tesmart\n host: 10.10.1.10\n port: 5000\n scheme:\n server0_led:\n driver: tes\n pin: 0\n mode: input\n server0_switch:\n driver: tes\n pin: 0\n mode: output\n switch: false \n server1_led:\n driver: tes\n pin: 1\n mode: input\n server1_switch:\n driver: tes\n pin: 1\n mode: output\n switch: false \n server2_led:\n driver: tes\n pin: 2\n mode: input\n server2_switch:\n driver: tes\n pin: 2\n mode: output\n switch: false \n server3_led:\n driver: tes\n pin: 3\n mode: input\n server3_switch:\n driver: tes\n pin: 3\n mode: output\n switch: false \n view:\n table:\n - [\"TESMART Switch\"]\n - []\n - [\"#Server 1\", server0_led, server0_switch|Switch]\n - [\"#Server 2\", server1_led, server1_switch|Switch]\n - [\"#Server 3\", server2_led, server2_switch|Switch]\n - [\"#Server 4\", server3_led, server3_switch|Switch]\n</code></pre> </li> <li> <p>Return to read-only mode for the sd card via <code>ro</code></p> </li> <li> <p>Restart the <code>kvmd</code> service: <code>systemctl restart kvmd</code></p> </li> </ol>"},{"location":"tesmart/#switching-between-hosts-in-the-ui","title":"Switching between hosts in the UI","text":"<p>To switch between hosts, enter the KVM UI and click the \"Switches\" menu. You should see your inputs, one of which will have a green circle indicating it is currently selected. Click the other inputs to change the selected host.</p>"},{"location":"usb/","title":"USB configuration","text":"<p>PiKVM V2+ emulates a small set of USB devices to ensure normal operation: a keyboard, mouse and mass storage drive. However, the possibilities are not limited to this. Optionally, you can add a USB ethernet, serial port, or (exclusive to PiKVM V3 and V4 Mini/Plus) a microphone to support two-way audio.</p> <p>In rare cases, the target host's BIOS/UEFI may not understand such a large number of emulated devices on single USB port, and some of them may need to be disabled.</p> <p>A complete USB configuration changing (adding or removing devices) requires a reboot, but it is possible to temporarily disable and then re-enable existing emulated devices in preset.</p>"},{"location":"usb/#basics","title":"Basics","text":"<p>Each emulated USB device consumes a limited hardware resource called endpoints.</p> <p>Depending on the device, the number of required endpoints varies:</p> Device Endpoints Keyboard, mouse 1 for each Mass Storage Drive 2 for each USB Microphone 2 USB Ethernet, USB Serial 3 for each <p>In total, PiKVM provides 9 endpoints for USB emulation, some of which are used by default:</p> <ul> <li> <p>PiKVM V2-V3 emulates one absolute mouse and one mass storage and uses 4 of 9 endpoints.</p> </li> <li> <p>PiKVM V4 Mini/Plus also adds a relative mouse by default so it uses 5 of 9 endpoints.</p> </li> </ul> <p>You can add other devices remaining endpoints, disable existing ones at all to free some endpoints, or do this only temporarily.</p> <p>Moreover, you can configure the preset with a large number of devices (more than PiKVM allows by endpoints), and then dynamically enable only the necessary ones.</p> <p>If you have configured too many devices that consume more than 9 endpoints in total, the least important of them will be inactive. You can enable them using dynamic configuration.</p> <p>To configure additional devices, please refer to the corresponding pages:</p> <ul> <li> <p>USB Microphone - Two-way audio communication for voice applications on the target host. Exclusive to PiKVM V3 and V4 Mini/Plus.</p> </li> <li> <p>Absolute and relative mouse - The most convenient type of mouse is an absolute mouse, but some BIOSes may not understand it. In this case, the relative one will help you.</p> </li> <li> <p>USB Ethernet - An FTP or Samba server on PiKVM can be configured, and the target host will see this over the network. It is also possible that PiKVM can work as a router to connect a host to a big network.</p> </li> <li> <p>USB Serial Port - It can be used for terminal access from the target host to the PiKVM, or for any other purpose that requires a serial connection.</p> </li> </ul> <p>For information on how emulated devices are represented on the target host and how to change it, read here.</p>"},{"location":"usb/#default-preset","title":"Default preset","text":"<p>Device setup includes two stages: adding to config and starting.</p> <p>When you add a device as described on the pages above, it automatically turns on after PiKVM reboot and becomes available on the target device. This behaviour can be changed: the device will be created, but not active until you turn it on dynamically.</p> <p>The <code>/etc/kvmd/override.yaml</code> file is used for such changes. In the following example, there are USB Serial Port and Microphone enabled, but the serial port is not started by default:</p> <pre><code>otg:\n devices:\n serial:\n enabled: true\n start: false\n audio:\n enabled: true\n</code></pre> <p>The <code>start</code> parameter is also available for all USB devices, see <code>kvmd -m</code> for the entire configuration tree.</p>"},{"location":"usb/#dynamic-configuration","title":"Dynamic configuration","text":""},{"location":"usb/#command-line-utility","title":"Command-line utility","text":"<p>The <code>kvmd-otgconf</code> utility allows you to view and modify the USB configuration on the fly.</p> <p>It will also inform you about the number of endpoints used.</p> <p>Changing requires root permissions.</p> <p>Let's take a look at the configuration:</p> <pre><code>[root@pikvm ~]# kvmd-otgconf \n# Endpoints used: 5 of 9\n# Endpoints free: 4\n+ hid.usb0 # [1] Keyboard # otg/devices/hid/keyboard/start\n+ hid.usb1 # [1] Absolute Mouse # otg/devices/hid/mouse/start\n+ hid.usb2 # [1] Relative Mouse # otg/devices/hid/mouse_alt/start\n+ mass_storage.usb0 # [2] Mass Storage Drive # otg/devices/msd/start\n</code></pre> <p>Each line represents an emulated device, left to right:</p> <ul> <li>Plus or minus sign: the state (enabled or not).</li> <li>The device name (e.g., <code>hid.usb0</code>).</li> <li>The number of required endpoints (e.g., <code>[2]</code>).</li> <li>The description (e.g., <code>Absolute mouse</code>).</li> <li>Path to the relevant configuration parameter (e.g., <code>otg/devices/hid/mouse/start</code>) you can use to boot or not boot a service when <code>kvmd</code> launches.</li> </ul> <p>Sometimes it's impossible to get into the UEFI/BIOS due to their bugs in USB support, and you need to boot from the PiKVM mass storage.</p> <p>In this case, you can disable all devices except keyboard and relative mouse, and enter the BIOS:</p> <pre><code>[root@pikvm ~]# kvmd-otgconf -d mass_storage.usb0 uac2.usb0 hid.usb1\n# Endpoints used: 2 of 9\n# Endpoints free: 7\n+ hid.usb0 # [1] Keyboard # otg/devices/hid/keyboard/start\n- hid.usb1 # [1] Absolute Mouse # otg/devices/hid/mouse/start\n+ hid.usb2 # [1] Relative Mouse # otg/devices/hid/mouse_alt/start\n- mass_storage.usb0 # [2] Mass Storage Drive # otg/devices/msd/start\n</code></pre> <p>Then change the boot order in the BIOS by setting the USB sticks as first priority.</p> <p>Exit the BIOS, and turn on mass storage again. Use it as usual to boot the image from PiKVM mass storage:</p> <pre><code>[root@pikvm ~]# kvmd-otgconf -e mass_storage.usb0\n# Endpoints used: 4 of 9\n# Endpoints free: 5\n+ hid.usb0 # [1] Keyboard # otg/devices/hid/keyboard/start\n- hid.usb1 # [1] Absolute Mouse # otg/devices/hid/mouse/start\n+ hid.usb2 # [1] Relative Mouse # otg/devices/hid/mouse_alt/start\n+ mass_storage.usb0 # [2] Mass Storage Drive # otg/devices/msd/start\n</code></pre> <p>You can also enable <code>uac2.usb0</code> and <code>hid.usb1</code> again.</p>"},{"location":"usb/#web-ui-menu","title":"Web UI menu","text":"<p>Using the pseudo-GPIO driver, you can USB control devices via the menu in the web interface. Read about GPIO basics here.</p> <p>To setup the menu, use <code>kvmd-otgconf --make-gpio-config</code> to generate the configuration, and merge it with your existing one in <code>/etc/kvmd/override.yaml</code> in a usual way.</p> The example of <code>kvmd-otgconf --make-gpio-config</code> output <pre><code># kvmd-otgconf --make-gpio-config\nkvmd:\n gpio:\n drivers:\n otgconf:\n type: otgconf\n scheme:\n hid.usb0:\n driver: otgconf\n mode: output\n pin: hid.usb0\n pulse: false\n hid.usb1:\n driver: otgconf\n mode: output\n pin: hid.usb1\n pulse: false\n hid.usb2:\n driver: otgconf\n mode: output\n pin: hid.usb2\n pulse: false\n mass_storage.usb0:\n driver: otgconf\n mode: output\n pin: mass_storage.usb0\n pulse: false\n view:\n table:\n - [\"#Keyboard\", \"#hid.usb0\", hid.usb0]\n - [\"#Absolute Mouse\", \"#hid.usb1\", hid.usb1]\n - [\"#Relative Mouse\", \"#hid.usb2\", hid.usb2]\n - [\"#Mass Storage Drive\", \"#mass_storage.usb0\", mass_storage.usb0]\n</code></pre> <p>Please note that this menu is not dynamically generated, you need to update the configuration if you added or deleted devices.</p>"},{"location":"usb_ethernet/","title":"Ethernet-over-USB network","text":"<p>Specifically to PiKVM V2+. When combined with configuring a DNS server, FTP, or SMB (for example), this is a powerful way to extend the capabilities of PiKVM.</p>"},{"location":"usb_ethernet/#basic-configuration","title":"Basic configuration","text":"<p>USB limitations</p> <p>Each emulated USB device consumes a limited hardware resource called endpoints.</p> <p>Short info: by default, you can add only one additional USB device.</p> <p>To get more information about the endpoints, add more devices, and flexibly manage the configuration on the fly, see here.</p> <p>Info</p> <p>Before exploring this page, we recommend to read the PiKVM configuration guide so that you understand the terminology and how exactly the parameters described below change.</p> <ol> <li> <p>Edit <code>/etc/kvmd/override.yaml</code> and add these lines:</p> <pre><code>otg:\n devices:\n ethernet:\n enabled: true\n driver: ecm\n host_mac: 48:6f:73:74:50:43\n kvm_mac: 42:61:64:55:53:42\n</code></pre> <p>The <code>enable: true</code> option was used for activation the USB network. The values of the remaining options are described in the tables.</p> Parameter Default Description <code>host_mac</code> <code><random></code> The MAC address of the host's network interface. <code>kvm_mac</code> <code><random></code> The MAC address of the network interface on the PiKVM side called <code>usb0</code>. <code>driver</code> <code>ecm</code> Protocol driver of the USB network. Different drivers are required for different OS. See below. Driver Compatibility with Operating Systems <code>ecm</code> Linux; Mac OS <code>eem</code> Linux <code>rndis5</code> Windows XP...7 <sup>1</sup>; Linux > 2.6.13 <code>rndis</code> Windows >= 7 <sup>2</sup>; Linux > 2.6.13 <code>ncm</code> Windows >= 10; Linux > 2.6.37; Mac OS <p>1: Manual driver installation is required. Download RNDIS 5 Windows 2: Automatic driver installation since KVMD 3.53.</p> </li> <li> <p>To automatically configure the USB network on the host recommended using the service <code>kvmd-otgnet</code>. It configures the firewall, assigns an address to the local PiKVM interface <code>usb0</code> and starts DHCP so the target host can get the IPv4 address.</p> <p>By default, the address <code>172.30.30.1/24</code> to interface <code>usb0</code> will be assigned. One of the other addresses from the network <code>172.30.30.0/24</code> will be assigned to the host when it requests it via DHCP.</p> <p>For security reasons, all incoming connections from the host 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 host to the PiKVM interface, you will need to add ports 80 and 443 to the whitelist using <code>/etc/kvmd/override.yaml</code> file like this:</p> <pre><code>otgnet:\n firewall:\n allow_tcp: [80, 443]\n</code></pre> <p>Other useful firewall options are listed here:</p> Parameter Default Description <code>allow_icmp</code> <code>true</code> Optional ICMP allowed to PiKVM. <code>allow_tcp</code> <code>[]</code> List of allowed TCP connections from the host to PiKVM. <code>allow_udp</code> <code>[]</code> List of allowed UDP connections from the host to PiKVM. <code>forward_iface</code> <code><none></code> Default gateway interface on PiKVM for network forwarding (see below). <p>See other parameters and command hooks in <code>kvmd -m</code>.</p> </li> <li> <p>To enable the service, use the command <code>systemctl enable kvmd-otgnet</code>.</p> </li> <li> <p>Perform <code>reboot</code>.</p> </li> </ol>"},{"location":"usb_ethernet/#routing-via-pikvm","title":"Routing via PiKVM","text":"<p>By default, <code>kvmd-otgnet</code> will configure network connection between PiKVM and the host only. The target host controlled by PiKVM will not be able to reach other hosts beyond PiKVM. If the full network access is required from the host through the USB-Ethernet feature (access all hosts PiKVM can access), additional settings are needed in <code>/etc/kvmd/override.yaml</code>.</p> <ol> <li> <p>Add network interface to forward requests to (default gateway) by adding a line <code>forward_iface: <interface name></code> under the <code>firewall</code> section. Typically it would be <code>eth0</code> if the built-in ethernet port is used::</p> <pre><code>otgnet:\n firewall:\n forward_iface: eth0\n</code></pre> </li> <li> <p>Add DNS server to provide host name resolution service. For example, adding <code>8.8.8.8</code> as DNS server requires addition of <code>dnsmasq</code> dhcp options. This can be done by adding following lines:</p> <pre><code>otgnet:\n commands:\n post_start_cmd_append:\n - \"--dhcp-option=6,8.8.8.8\"\n</code></pre> </li> <li> <p>Combining above two together::</p> <pre><code>otgnet:\n firewall:\n forward_iface: eth0\n commands:\n post_start_cmd_append:\n - \"--dhcp-option=6,8.8.8.8\"\n</code></pre> </li> <li> <p>To enable internet access for the target host, add the following to the otgnet configuration::</p> <pre><code> otgnet:\n iface:\n net: 10.65.0.0/28\n</code></pre> <p>The 'net' parameter defines the network address range of the <code>usb0</code> network. The host will automatically receive an IP address within this network including the DNS servers defined under 'post_start_cmd_append'. Note: This network should not be same as the network PiKVM is connected to.</p> <p>See other parameters and command hooks in <code>kvmd -m</code>.</p> </li> <li> <p>Don't forget to <code>reboot</code>.</p> </li> </ol> An example of what the config would look like for a host that can access PiKVM and has internet access: <pre><code>otgnet:\n firewall:\n allow_tcp: [80, 443]\n forward_iface: wlan0\n commands:\n post_start_cmd_append:\n - \"--dhcp-option=6,1.1.1.1,1.0.0.1\"\n iface:\n ip_cmd:\n - /usr/bin/ip\n net: 10.65.0.0/28\n</code></pre>"},{"location":"usb_ethernet/#working-with-windows-computers","title":"Working with Windows Computers","text":"<p>This has been proven to work with Windows:</p> <ol> <li> <p>Set the driver type to rndis (see above).</p> </li> <li> <p>Download this driver on the Windows machine and unzip it somewhere.</p> </li> <li> <p>Open the devices manager: </p> </li> <li> <p>Select Properties of the Composite KVM Device: </p> </li> <li> <p>Select the RNDIS Device and click properties: </p> </li> <li> <p>Switch to the Driver tab and then click Update driver.</p> </li> <li> <p>Click Browse my computer for driver software: </p> </li> <li> <p>Click Let me pick from a list of available drivers on my Computer: </p> </li> <li> <p>From the list of available hardware types, scroll down and select Network adapters, then click Next: </p> </li> <li> <p>Click Have disk: </p> </li> <li> <p>Click Browse, navigate to the folder where you've stored the driver and select the RNDIS.inf, press Open and then OK: </p> </li> <li> <p>Select Acer Netchip RNDIS/Ethernet Gadget and click Next: </p> </li> <li> <p>Dismiss the warning about non-compatible drivers by clicking Yes: </p> </li> <li> <p>You're done - the device should now be recognized: </p> </li> <li> <p>Verify the card is working by pinging your PiKVM in a console: <code>ping 172.30.30.1</code>: </p> </li> </ol>"},{"location":"usb_pass/","title":"USB Passthrough","text":""},{"location":"usb_pass/#usb-passthrough","title":"USB Passthrough","text":"<p>For USB keyboards and mice connected to PiKVM directly, USB passthrough allows forwarding their input to the host system. This feature is available for all versions of PiKVM except the v4 Mini (no available USB ports) or a DIY version based on Pi Zero/Pi Zero 2 (using a USB hub prevents utilizing the OTG which the passthru expects to be available). It works best with HDMI passthrough available on PiKVM V4 Plus.</p> <p>Let's consider this setup:</p> <ul> <li>PiKVM V4 Plus connected to PiKVM switch;</li> <li>A keyboard and a mouse connected to USB A ports on the PiKVM;</li> <li>An external display connected to the PiKVM directly using HDMI out.</li> </ul> <p></p> <p>With both HDMI passthrough and USB passthrough enabled, you would be able to do this:</p> <ul> <li>Switch between Computer 1 and Computer 2 connected to PiKVM Switch;</li> <li>Control them directly from this single keyboard/mouse pair (in addition to remote control);</li> <li>See the video output from the selected host on the local display.</li> </ul>"},{"location":"usb_pass/#enabling-usb-passthrough","title":"Enabling USB passthrough","text":"<p>Follow these steps to enable USB passthrough on your PiKVM:</p> <ol> <li> <p>Log into your PiKVM as <code>root</code>, either via SSH, web console, or USB serial connection.</p> </li> <li> <p>You need KVMD 4.74+ to be able to use this feature. Update the PiKVM OS as <code>root</code>:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> </li> <li> <p>PiKVM will reboot, log in as <code>root</code> again.</p> </li> <li> <p>Run the following command to change acces to read-write, enable USB passthrough, and change acces to read-only again:</p> <pre><code>[root@pikvm ~]# rw; systemctl enable --now kvmd-localhid; ro\n</code></pre> </li> </ol> <p>Once you've done that, you should be able to use your USB keyboard and mouse connected directly to your PiKVM to control the host.</p>"},{"location":"usb_pass/#toggling-usb-passthrough","title":"Toggling USB passthrough","text":"<p>Every once in a while you may want using keyboard/mouse to control your PiKVM instead of controlling a host. Once USB passthrough is enabled in the system, you can switch it on and off with shortcuts:</p> <ul> <li> <p><code>LeftAlt, LeftAlt, K</code> (mnemonic KVM) disables keyboard/mouse grabbing and allows using the input devices with PiKVM locally, for example, for the console operating.</p> </li> <li> <p><code>LeftAlt, LeftAlt, H</code> (mnemonic Host) switches back to the passthrough mode and passes keyboard-mouse events to the host.</p> </li> </ul> <p>Press these keys immediately one after another: <code>LeftAlt</code>, then <code>LeftAlt</code> again, then the mnemonic key. </p>"},{"location":"usb_pass/#switching-the-pikvm-switch-channels","title":"Switching the PiKVM Switch channels","text":"<p>If you have one or two PiKVM Switches, you can use <code>LeftAlt, LeftAlt, 1</code> (1-8) to switch between up to 8 channels.</p> <p>For three or more PiKVM Switches, you need to use double numbers, e.g., <code>LeftAlt, LeftAlt, 3, 2</code> (unit 3, channel 2).</p>"},{"location":"usb_serial/","title":"Serial-over-USB connection","text":"<p>Specifically to V2+. This can be used for terminal access from the target host 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.</p> <p>USB limitations</p> <p>Each emulated USB device consumes a limited hardware resource called endpoints.</p> <p>Short info: by default, you can add only one additional USB device.</p> <p>To get more information about the endpoints, add more devices, and flexibly manage the configuration on the fly, see here.</p> <ol> <li> <p>Edit <code>/etc/kvmd/override.yaml</code> and add these lines:</p> <pre><code>otg:\n devices:\n serial:\n enabled: true\n</code></pre> </li> <li> <p>Run the following command:</p> <pre><code># echo ttyGS0 >> /etc/securetty\n</code></pre> </li> <li> <p>Create the directory <code>/etc/systemd/system/getty@ttyGS0.service.d</code> and add a file file named <code>override.conf</code> into it. Afterwards edit the file and copy this into it:</p> <pre><code>[Service]\nTTYReset=no\nTTYVHangup=no\nTTYVTDisallocate=no\n</code></pre> </li> <li> <p>Run these comands:</p> <pre><code># systemctl enable getty@ttyGS0.service\n# reboot\n</code></pre> </li> <li> <p>Once PiKVM 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 <code>/dev/ttyAMA0</code>.</p> </li> </ol>"},{"location":"v1/","title":"DIY PiKVM V1 quickstart guide","text":""},{"location":"v1/#diy-pikvm-v1-quickstart-guide","title":"DIY PiKVM V1 quickstart guide","text":"<p>So many choices!</p> <p>There are many different options with sub-items, so you can choose what will suit you. However, we marked the recommended way by sign <code>\u272e \u272e \u272e</code></p>"},{"location":"v1/#required-parts","title":"Required parts","text":"<ol> <li> <p>MicroSD card minimum 8Gb class 10.</p> </li> <li> <p>Official USB-Micro Power Supply.</p> </li> <li> <p>Raspberry Pi board:</p> <ul> <li>\u272e \u272e \u272e Raspberry Pi 3.</li> <li>... or Raspberry Pi 2. Does not support H.264 even with HDMI-CSI bridge.</li> <li>... or Raspberry Pi Zero 2 W. Compact and cheap, but not so reliable solution because of lack of the wired Ethernet. Note that the better way to use Pi Zero is making PiKVM V2 - it supports more USB features.</li> </ul> </li> <li> <p>Video capture device:</p> <ul> <li>\u272e \u272e \u272e HDMI-CSI bridge based on TC358743 chip. Supports H.264 video encoding on Raspberry Pi 3, automatic resolution selection and the lowest possible latency.</li> <li>... or HDMI-USB dongle. Only heavy MJPEG video, no resolution detection, big latency compared to HDMI-CSI. Some users report hardware problems: the dongle may not work in the BIOS or simply stop working after a while. It's a black box, and no one knows what's inside it. If you have problems with it, it will not be possible to fix them.</li> </ul> </li> <li> <p>The Pico HID Keyboard & mouse emulator:</p> <ul> <li> <p>x1 Raspberry Pi Pico board with soldered pins. Pico 2 is not supported right now.</p> </li> <li> <p>x1 USB-A to Micro-USB cable.</p> </li> <li> <p>x10 dupont wires female-female.</p> </li> <li> <p>x1 1N5819 diode. It's optional but strongly recommended. Any similar one will do.</p> <p>Warning</p> <p>The diode is needed to provide power to the Pico HID regardless of the target host state, which prevents the backpowering problem. It will allow you to keep the keyboard buttons pressed during the target host power cycle, which is, for example, important for MacOS to get into the boot menu.</p> <p>Do not connect the red wire (the <code>VSYS (Pico) -> 5V (Pi)</code> line) without a diode. If you can't find a diode, don't connect this wire at all.</p> </li> </ul> </li> <li> <p>Board-specific parts:</p> <p>\u272e \u272e \u272e \"Nothing special for Raspberry Pi 2 or 3</p> Raspberry Pi Zero 2 W \u272e \u272e \u272e HDMI-CSI bridge <ul> <li>x1 Raspberry Pi Zero Camera Cable. Not compatible with Auvidea B101.</li> </ul> ... or HDMI-USB dongle <ul> <li>x1 USB-A socket to USB-Micro adapter (female-male).</li> </ul> </li> <li> <p>Optional features:</p> \u272e \u272e \u272e ATX controller to manage the target host's power <p>With this part, you will be able to remotely turn on, turn off and restart your computer!</p> <ul> <li>x4 optocouplers TLP241BF(F or PC817X2NSZ9F (the input polarity must be observed) or OMRON G3VM-61A1 or OMRON G3VM-61AY1 Don't use random relay modules or random optocouplers! Some of these may not be sensitive enough for the Raspberry Pi, some others may be low-level controlled. Either use relays that are activated by a high logic level, or follow the design provided. See details here.</li> <li>x4 390 Ohm resistors (see here for alternatives).</li> <li>2x 4.7 kOhm resistors.</li> <li>x10+ dupont wires male-male.</li> <li>x1 a breadboard.</li> <li>various wires for the breadboard.</li> </ul> <p>This can be partially replaced by using Wake-on-LAN in the software, but it will not allow to reboot a hung system, and it is not as reliable as an ATX controller. Sometimes the Wake-on-LAN on the host just stops working, for its own or network reasons.</p> PS/2 Keyboard & mouse <p>The use of PS/2 is intended for advanced users. Check out the additional list of details in advance in the corresponding paragraph of the Pico HID manual.</p> VGA video capture <p>If you want to capture VGA from your server instead of HDMI, buy the VGA-to-HDMI converter. Some converters have issues with not supporting all resolutions and refresh rates.</p> </li> </ol>"},{"location":"v1/#setting-up-the-hardware","title":"Setting up the hardware","text":"<ol> <li> <p>Video capture device:</p> \u272e \u272e \u272e HDMI-CSI bridge <p>Insert the flexible flat cable of the HDMI-CSI bridge into the narrow white connector on the Raspberry Pi (the closest one to big USB sockets). It is labeled <code>CAMERA</code>. To insert you need to open the connector first. On the Raspberry Pi side you can gently lift the black part up and a little bit sideways:</p> Opening the MIPI CSI slot on the Raspberry Pi <p>For the HDMI-CSI bridge this operation depends on the version you bought. Either pull it gently up as on the Raspberry or push it sideways. Make sure that the cable is inserted on the correct side and until it stops, and then push the black latch back. Avoid using force when pushing the cable in, as the slots bond to the PCB is quite fragile. Never connect or disconnect the flat cable from a powered device. This is not Plug-and-Play, and you can damage it. Also use only the cable that was included with the device package, or make sure that the third-party cable has the correct pinout.</p> HDMI-CSI bridge connected to Raspberry Pi 4 HDMI-CSI bridge connected to Raspberry Pi 2 W (using the adapter cable) ... or HDMI-USB dongle Raspberry Pi 2 & 3 <p>Connect USB dongle to exactly this port. It is bound in the software so the OS does not confuse the video device with something else.</p> Raspberry Pi 2 and 3 Raspberry Pi 4 <p>There are many revisions of the Raspberry Pi boards and you may come across one that we haven't tested. If the binding fails, the device will be available for all ports. Everything will work, but if you use a webcam and Linux mistakes it for a dongle, write to us and we will fix it.</p> Raspberry Pi Zero 2 W <p>Connect the USB dongle to USB-to-Micro adapter, and connect it to the USB port marked as <code>USB</code> (not <code>PWR</code>) on the Pi Zero board:</p> <p></p> </li> <li> <p>The Pico HID and ATX controller:</p> <p>Connect all the parts according to this scheme:</p> \u272e \u272e \u272e With ATX controller Simple wiring diagram <p></p> Electrical schematic diagram for advanced users <p></p> ... or without ATX controller Simple wiring diagram <p></p> Electrical schematic diagram for advanced users <p></p> </li> <li> <p>Flash firmware to the Pico HID.</p> </li> <li> <p>Flash the memory card with PiKVM OS and insert it to Raspberry Pi.</p> </li> </ol>"},{"location":"v1/#wiring","title":"Wiring","text":"<p>Warning</p> <p>Double check that the circuit is assembled correctly to avoid any damage of the hardware.</p> <p>PiKVM V1 requires several items available separately:</p> <ul> <li> <p>Ethernet cable (Raspberry Pi 2 and 3 only)</p> </li> <li> <p>HDMI cable</p> </li> </ul> <p>Let's connect all the wires before you power up the device.</p> <ol> <li> <p>Connect the HDMI video capture device to the video output port on the target host.</p> </li> <li> <p>Connect the Pico HID to the USB port on the target host.</p> </li> <li> <p>Raspberry Pi 2/3: connect Ethernet to the network, e.g., to the Wi-Fi router.</p> </li> <li> Connect the ATX controller if you built it <p>To control the power, two display LEDs (power and HDD activity) and two buttons (power and reset) are provided on the front panel of the computer case. They are connected by wires to pins on the motherboard.</p> <p></p> <p>All you have to do is connect the PiKVM ATX controller to their wires by making a parallel connection. Please note that the pinout differs on different motherboards, so before you continue, check the documentation on your motherboard for correct pinout.</p> <p>The following illustration shows how the connection between the power LED and the power button should be performed:</p> <p></p> <p>On the left are the wires from the PiKVM ATX controller, the pad in the middle indicates the pins on the motherboard, and on the right are the LED and button of the target host. The implementation of this scheme is left to your discretion and can be performed, for example, by cutting wires and performing twisting, followed by insulation with duct tape.</p> <p>Be careful and respect the polarity of the LEDs. The polarity of the button does not matter (they have no polarity at all). The connection of HDD LED and reset switch is performed in the same way.</p> </li> </ol>"},{"location":"v1/#power-up","title":"Power up","text":"<p>If everything is assembled correctly, attach the power supply to the Raspberry Pi.</p> <p>After turning on the power, PiKVM OS generates unique SSH keys and certificates and performs all necessary operations on the memory card. It takes a few minutes.</p> <p>Do not turn off the device until it's fully booted for the first time.</p>"},{"location":"v1/#configure-the-display","title":"Configure the display","text":"<p>The operating system on your remote computer will treat PiKVM as an additional display and use it in the Extend mode by default. That's why you will see an empty desktop when you first connect.</p> <p>To avoid that, go to the display settings in your remote computer's operating system and enable the mirror mode for the external screen that you operating system identifies as PiKVM. Refer to your operating system's documentation on that.</p>"},{"location":"v1/#access-pikvm","title":"Access PiKVM","text":"<p>You need to know PiKVM's IP address in the network to be able to access it. Unlike PiKVM V3 and V4, PiKVM V1 doesn't have an OLED to display the IP address it receives automatically. You need to discover it manually. There are several ways to do that.</p> <ul> <li>Common way: Open the web interface of your router and find the list of issued IP addresses there.</li> <li>Linux-only: Use the <code>arp-scan --localnet</code> command.</li> <li>Linux, MacOS, Windows: Download and run Angry IP Scanner.</li> <li>Windows PowerShell: Use the <code>arp -a</code> command.</li> </ul> <p>Let's assume that PiKVM has received the address <code>192.168.0.26</code> and has also been assigned a hostname <code>pikvm</code>.</p> <p>Type the URL in the browser's address bar and press Enter: https://192.168.0.26/ or https://pikvm/.</p> <p></p> <p>Submit the default credentials and click Login:</p> <ul> <li>Username: <code>admin</code></li> <li>Password: <code>admin</code></li> <li>2FA Code: disabled by default, skip this field</li> </ul> <p>You will see the initial dashboard screen of the PiKVM where you can access the remote host, connect to the PiKVM command line, or log out:</p> <p></p>"},{"location":"v1/#change-the-default-passwords","title":"Change the default passwords","text":"<p>For security's sake, it's best to change the default passwords immediately after running PiKVM for the first time.</p> <p>Passwords are important!</p> <p>Please ensure that you change both passwords: for Web UI access and for the Linux superuser (root).</p> <p>To do that:</p> <ol> <li> <p>On the initial dashboard screen, click the Terminal button to open the web terminal. You will see this command line interface:</p> <p></p> </li> <li> <p>Gain Linux superuser privileges:</p> <pre><code>$ su -\n</code></pre> <p>When prompted for password, use <code>root</code>.</p> </li> <li> <p>Run <code>rw</code> to change the access to the SD card to the write mode:</p> <pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Change the password for the Linux superuser:</p> <pre><code>[root@pikvm ~]# passwd root\n</code></pre> <p>Submit the new password, retype it the second time to confirm, press Enter, and you should see this:</p> <pre><code>passwd: password updated successfully\n</code></pre> </li> <li> <p>Change the password for web access:</p> <pre><code>[root@pikvm ~]# kvmd-htpasswd set admin\n</code></pre> <p>Submit the new password, retype it the second time to confirm, and press Enter.</p> </li> <li> <p>Run <code>ro</code> to change the access to the SD card back to the read-only mode:</p> <pre><code>[root@pikvm ~]# ro\n</code></pre> </li> <li> <p>Press Ctrl+D or type \"exit\" and press Enter to drop the root privileges.</p> </li> <li> <p>Go back one page in the browser. You should be back to the initial dashboard screen.</p> </li> </ol>"},{"location":"v1/#access-the-remote-system","title":"Access the remote system","text":"<ol> <li> <p>On the initial dashboard screen, click the KVM button to access the remote host.</p> </li> <li> <p>You should now see the host system's display and interact with it remotely using a keyboard and a mouse.</p> <p></p> </li> </ol>"},{"location":"v1/#important-next-steps","title":"Important next steps","text":"<ul> <li> <p>We strongly recommend to update the PiKVM OS after the first launch:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> </li> <li> <p>Learn about basics of PiKVM OS Configuration: where to find configs, how to edit the, etc.</p> Configuring PiKVM OS <p>Need more info? We have it!</p> <p>The following is a brief guide to configuring PiKVM. For more information (including the basics of YAML syntax and how to use a text editor in the Linux console), please refer to this page.</p> <p>Most of the PiKVM configuration files are located in the <code>/etc/kvmd</code> directory.</p> <p>The <code>/usr/lib/kvmd/main.yaml</code> file defines the platform configuration, and you should never edit it. To redefine system parameters use the file <code>/etc/kvmd/override.yaml</code>. All other files that are also not recommended for editing have read-only permissions.</p> <p>You can also create several files with the <code>.*yaml</code> suffix and put then into <code>/etc/kvmd/override.d</code> directory to split your customization into logical parts. The <code>override.yaml</code> file definitions takes precedence over the <code>override.d</code> directory.</p> <p>A complete list of all parameters can be viewed using the <code>kvmd -m</code> command.</p> <p>Files with the <code>*.yaml</code> suffix uses the YAML syntax and describes a parameter tree with key-value pairs of different types. To define the parameters within one section, an indent of 4 spaces is used. Comments starts with the <code>#</code> symbol.</p> <p>Only 4 spaces should be used for indentation</p> <p>Be careful when editing YAML and follow this rule. Invalid indentation or tabs instead of spaces will cause an error when starting the services.</p> <p>Sections under the same keys should be merged:</p> <ul> <li> <p>Wrong:</p> <pre><code>kvmd:\n gpio:\n drivers: ...\nkvmd:\n gpio:\n scheme: ...\n</code></pre> </li> <li> <p>Correct:</p> <pre><code>kvmd:\n gpio:\n drivers: ...\n scheme: ...\n</code></pre> </li> </ul> <p>In the <code>/etc/kvmd/meta.yaml</code> file you can specify some information regarding this PiKVM installation in an almost free YAML format.</p> </li> <li> <p>Get to know PiKVM Web UI: read this help section to better understand all the possibilities of the web user interface.</p> </li> <li> <p>Tune the HDMI dongle capture device if you're using it:</p> Persistent HDMI cable connection with USB dongle <p>Many USB video capture devices tell the server's video card that the HDMI cable is supposedly disconnected. This may lead to the fact that if you boot the server without an active stream, the server will not detect your capture card. This is easy to fix:</p> <ul> <li> <p>Switch filesystem to RW-mode: </p><pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Edit file <code>/etc/kvmd/override.yaml</code> and add these lines: </p><pre><code>kvmd:\n streamer:\n forever: true\n cmd_append: [--slowdown]\n</code></pre> </li> <li> <p>Finish: </p><pre><code>[root@pikvm ~]# ro\n[root@pikvm ~]# systemctl restart kvmd\n</code></pre> </li> <li> <p>Check that everything is working.</p> </li> </ul> </li> </ul>"},{"location":"v1/#further-recommendations","title":"Further recommendations","text":"<ul> <li>Harden the remote access by enabling 2FA and setting session expiration time.</li> <li>Configure access to PiKVM from the Internet using port forwarding or Tailscale VPN.</li> <li>Learn how configuration files are structured.</li> <li>Read how PiKVM is identified on the target host.</li> </ul>"},{"location":"v1/#known-issues-and-limitations","title":"Known issues and limitations","text":"<ul> <li>Max resolution.PiKVM V1 with CSI bridge can only handle the maximum resolution 1920x1080@50Hz, 60Hz is not supported due hardware limitation. You can use any other resolution less than the specified one, for example 1280x720@60Hz. If you have any problems with video on CSI bridge, follow this guide.</li> </ul>"},{"location":"v1/#basic-troubleshooting","title":"Basic troubleshooting","text":"<ul> <li> <p>Ensure that you are using the right OS image for your platform by running the following command: <code>pacman -Q | grep kvmd-platform</code>.</p> </li> <li> <p>If you are not getting a display, run the two following commands:</p> <ul> <li><code>dmesg | egrep 'tc35|1-1.4|uvc'</code></li> <li><code>systemctl status kvmd-tc358743</code></li> </ul> <p>If you see a failed message on that output, be sure verify the orientation of the CSI cable or try reseating it.</p> <p>Note that this is not a hotplug device, and you must first turn off the power.</p> </li> </ul>"},{"location":"v1/#getting-user-support","title":"Getting user support","text":"<p>If something doesn't work, check out our FAQ. Otherwise, head straight to our Support.</p>"},{"location":"v2/","title":"DIY PiKVM V2 quickstart guide","text":""},{"location":"v2/#diy-pikvm-v2-quickstart-guide","title":"DIY PiKVM V2 quickstart guide","text":"<p>So many choices!</p> <p>There are many different options with sub-items, so you can choose what will suit you. However, we marked the recommended way by sign <code>\u272e \u272e \u272e</code></p>"},{"location":"v2/#required-parts","title":"Required parts","text":"<ol> <li> <p>MicroSD card minimum 16Gb class 10.</p> </li> <li> <p>Raspberry Pi board:</p> <ul> <li>\u272e \u272e \u272e Raspberry Pi 4 2Gb. It makes no sense to buy a Pi 4 with more memory than 2Gb, since PiKVM software uses very few resources.</li> <li>... or Raspberry Pi Zero 2 W. Compact and cheap, but not so reliable solution because of lack of the wired Ethernet.</li> <li>... Raspberry Pi 5 is not supported right now. It doesn't have GPU video encoders, therefore, there is no point in using it for PiKVM, it will not give any performance boost for this case. The Pi 5 is a great device, just not suitable for PiKVM.</li> </ul> </li> <li> <p>Video capture device:</p> <ul> <li>\u272e \u272e \u272e HDMI-CSI bridge based on TC358743 chip. Supports H.264 video encoding, automatic resolution selection and the lowest possible latency.</li> <li>... or HDMI-USB dongle (not available for Pi Zero 2). Only heavy MJPEG video, no resolution detection, big latency compared to HDMI-CSI. Some users report hardware problems: the dongle may not work in the BIOS or simply stop working after a while. It's a black box, and no one knows what's inside it. If you have problems with it, it will not be possible to fix them.</li> </ul> </li> <li> <p>Board-specific: Power supply, USB connectivity, etc.</p> \u272e \u272e \u272e Raspberry Pi 4 <p>On a Raspberry Pi 4 only the USB-C port that receives power is capable of acting as a USB Device. The other USB ports are capable only of acting as USB Hosts. Therefore a special cable must be used on the USB power port that it can simultaneously act as USB Device for the target host and receive external power from an power supply.</p> \u272e \u272e \u272e Variant #1: Power supply + ready-made Y-splitter module <ul> <li>x1 USB-C/Power Splitter Module (US/UK/CA).</li> <li>x1 USB-C to USB-C cable (male-male) for connecting the Raspberry Pi to the splitter.</li> <li>x1 USB-A to USB-C cable (male-male) for connecting the target host to the splitter.</li> <li>x1 Official USB-C Power Supply.</li> </ul> ... or Variant #2: Power supply + Y-splitter based on power blocker <ul> <li>x1 USB-A to USB-C cable (male-male).</li> <li>x1 USB splitter.</li> <li>x1 USB Power Blocker - Will go into the USB-A end towards the target host.</li> <li>x1 Raspberry Pi Official USB-C Power Supply.</li> </ul> ... or Variant #3: Power supply + DIY Y-splitter for soldering <ul> <li>x1 USB-A to USB-C cable (male-male).</li> <li>x1 Another cable USB-A to any (male-any).</li> <li>x1 Any 5V 3A power supply with USB-A socket.</li> </ul> ... or Raspberry Pi Zero 2 W <ul> <li>x1 USB-A to USB-Micro cable (male-male).</li> <li>x1 Raspberry Pi Zero Camera Cable. Not compatible with Auvidea B101.</li> <li>x1 Raspberry Pi Official USB-Micro Power Supply.</li> </ul> </li> <li> <p>Optional features:</p> \u272e \u272e \u272e ATX controller to manage the target host's power <p>With this part, you will be able to remotely turn on, turn off and restart your computer!</p> <ul> <li>x4 optocouplers TLP241BF(F or PC817X2NSZ9F (the input polarity must be observed) or OMRON G3VM-61A1 or OMRON G3VM-61AY1 Don't use random relay modules or random optocouplers! Some of these may not be sensitive enough for the Raspberry Pi, some others may be low-level controlled. Either use relays that are activated by a high logic level, or follow the design provided. See details here.</li> <li>x4 390 Ohm resistors (see here for alternatives).</li> <li>2x 4.7 kOhm resistors.</li> <li>x10+ dupont wires male-male.</li> <li>x1 a breadboard.</li> <li>various wires for the breadboard.</li> </ul> <p>This can be partially replaced by using Wake-on-LAN in the software, but it will not allow to reboot a hung system, and it is not as reliable as an ATX controller. Sometimes the Wake-on-LAN on the host just stops working, for its own or network reasons.</p> VGA video capture <p>If you want to capture VGA from your server instead of HDMI, buy the VGA-to-HDMI converter. Some converters have issues with not supporting all resolutions and refresh rates.</p> </li> </ol> <p>Kit parts suitable for assembly are also on sale in Poland.</p>"},{"location":"v2/#setting-up-the-hardware","title":"Setting up the hardware","text":"<ol> <li> <p>Video capture device:</p> \u272e \u272e \u272e HDMI-CSI bridge <p>Insert the flexible flat cable of the HDMI-CSI bridge into the narrow white connector on the Raspberry Pi (the closest one to big USB sockets). It is labeled <code>CAMERA</code>. To insert you need to open the connector first. On the Raspberry Pi side you can gently lift the black part up and a little bit sideways:</p> Opening the MIPI CSI slot on the Raspberry Pi <p>For the HDMI-CSI bridge this operation depends on the version you bought. Either pull it gently up as on the Raspberry or push it sideways. Make sure that the cable is inserted on the correct side and until it stops, and then push the black latch back. Avoid using force when pushing the cable in, as the slots bond to the PCB is quite fragile. Never connect or disconnect the flat cable from a powered device. This is not Plug-and-Play, and you can damage it. Also use only the cable that was included with the device package, or make sure that the third-party cable has the correct pinout.</p> HDMI-CSI bridge connected to Raspberry Pi 4 HDMI-CSI bridge connected to Raspberry Pi 2 W (using the adapter cable) ... or HDMI-USB dongle <p>Connect USB dongle to exactly this port. It is bound in the software so the OS does not confuse the video device with something else.</p> Raspberry Pi 2 and 3 Raspberry Pi 4 <p>There are many revisions of the Raspberry Pi boards and you may come across one that we haven't tested. If the binding fails, the device will be available for all ports. Everything will work, but if you use a webcam and Linux mistakes it for a dongle, write to us and we will fix it.</p> </li> <li> <p>USB cable and power supply</p> \u272e \u272e \u272e Raspberry Pi 4 \u272e \u272e \u272e Variant #1: Power supply + ready-made Y-splitter module <p></p> ... or Variant #2: Power supply + Y-splitter based on power blocker <p></p> ... or Variant #3: Power supply + DIY Y-splitter for soldering <p>It is assumed that if you have followed this path, you know how to handle a soldering iron and a multimeter.</p> <p>The Y-splitter can be soldered from two suitable USB cables. Check the attached diagram. The appropriate USB pinout(s) can easily be found on Google.</p> <p>Please note that if you make a Y-cable from two no-name cables, the colors of the wires may not match those shown. Use a multimeter to make sure the connections are correct.</p> <p></p> <p>Video How-To: Making a USB Y-splitter cable</p> ... or Raspberry Pi Zero 2 W <p>This board has two USB micro connectors: one for power supply (marked as <code>PWR</code>) and the second for emulating a USB gadget (marked as <code>USB</code>). Both connectors have a common power line, so to prevent Raspberry power from entering the USB port of the target host, it is required to make a special USB A-to-Micro cable without power line.</p> <p>One way is to physically cut the power wire inside the USB cable.</p> <p>An easier way is to stick a piece of duct tape, as shown in this picture:</p> <p></p> <p>Connect the power supply to the <code>PWR</code>, and your magic cable to the <code>USB</code>. The magic cable will be used to connect the device to the target host.</p> </li> <li> <p>\u272e \u272e \u272e Optional feature: ATX controller</p> <p>Connect all the parts according to this scheme:</p> Simple wiring diagram <p></p> Electrical schematic diagram for advanced users <p></p> </li> <li> <p>Flash the memory card with PiKVM OS and insert it to Raspberry Pi.</p> </li> </ol>"},{"location":"v2/#wiring","title":"Wiring","text":"<p>Warning</p> <p>Double check that the circuit is assembled correctly to avoid any damage of the hardware.</p> <p>PiKVM V2 requires several items available separately:</p> <ul> <li>Ethernet cable (Raspberry Pi 4 only)</li> <li>HDMI cable</li> </ul> <p>Let's connect all the wires before you power up the device.</p> <ol> <li> <p>Connect the HDMI video capture device to the video output port on the target host.</p> </li> <li> <p>Using the Y-cable, connect the Pi's OTG port to the USB on the target host.</p> </li> <li> <p>Raspberry Pi 4: connect Ethernet to the network, e.g., to the WiFI router.</p> </li> <li> Connect the ATX controller if you built it <p>To control the power, two display LEDs (power and HDD activity) and two buttons (power and reset) are provided on the front panel of the computer case. They are connected by wires to pins on the motherboard.</p> <p></p> <p>All you have to do is connect the PiKVM ATX controller to their wires by making a parallel connection. Please note that the pinout differs on different motherboards, so before you continue, check the documentation on your motherboard for correct pinout.</p> <p>The following illustration shows how the connection between the power LED and the power button should be performed:</p> <p></p> <p>On the left are the wires from the PiKVM ATX controller, the pad in the middle indicates the pins on the motherboard, and on the right are the LED and button of the target host. The implementation of this scheme is left to your discretion and can be performed, for example, by cutting wires and performing twisting, followed by insulation with duct tape.</p> <p>Be careful and respect the polarity of the LEDs. The polarity of the button does not matter (they have no polarity at all). The connection of HDD LED and reset switch is performed in the same way.</p> </li> </ol>"},{"location":"v2/#power-up","title":"Power up","text":"<p>If everything is assembled correctly, attach the power supply to the Raspberry Pi.</p> <p>After turning on the power, PiKVM OS generates unique SSH keys and certificates and performs all necessary operations on the memory card. It takes a few minutes.</p> <p>Do not turn off the device until it's fully booted for the first time.</p>"},{"location":"v2/#configure-the-display","title":"Configure the display","text":"<p>The operating system on your remote computer will treat PiKVM as an additional display and use it in the Extend mode by default. That's why you will see an empty desktop when you first connect.</p> <p>To avoid that, go to the display settings in your remote computer's operating system and enable the mirror mode for the external screen that you operating system identifies as PiKVM. Refer to your operating system's documentation on that.</p>"},{"location":"v2/#access-pikvm","title":"Access PiKVM","text":"<p>You need to know PiKVM's IP address in the network to be able to access it. Unlike V3 and V4, PiKVM V2 doesn't have an OLED to display the IP address it receives automatically. You need to discover it manually. There are several ways to do that.</p> <ul> <li>Common way: Open the web interface of your router and find the list of issued IP addresses there.</li> <li>Linux-only: Use the <code>arp-scan --localnet</code> command.</li> <li>Linux, MacOS, Windows: Download and run Angry IP Scanner.</li> <li>Windows PowerShell: Use the <code>arp -a</code> command.</li> </ul> <p>Let's assume that PiKVM has received the address <code>192.168.0.26</code> and has also been assigned a hostname <code>pikvm</code>.</p> <p>Type the URL in the browser's address bar and press Enter: https://192.168.0.26/ or https://pikvm/.</p> <p></p> <p>Submit the default credentials and click Login:</p> <ul> <li>Username: <code>admin</code></li> <li>Password: <code>admin</code></li> <li>2FA Code: disabled by default, skip this field</li> </ul> <p>You will see the initial dashboard screen of the PiKVM where you can access the remote host, connect to the PiKVM command line, or log out:</p> <p></p>"},{"location":"v2/#change-the-default-passwords","title":"Change the default passwords","text":"<p>For security's sake, it's best to change the default passwords immediately after running PiKVM for the first time.</p> <p>Passwords are important!</p> <p>Please ensure that you change both passwords: for Web UI access and for the Linux superuser (root).</p> <p>To do that:</p> <ol> <li> <p>On the initial dashboard screen, click the Terminal button to open the web terminal. You will see this command line interface:</p> <p></p> </li> <li> <p>Gain Linux superuser privileges:</p> <pre><code>$ su -\n</code></pre> <p>When prompted for password, use <code>root</code>.</p> </li> <li> <p>Run <code>rw</code> to change the access to the SD card to the write mode:</p> <pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Change the password for the Linux superuser:</p> <pre><code>[root@pikvm ~]# passwd root\n</code></pre> <p>Submit the new password, retype it the second time to confirm, press Enter, and you should see this:</p> <pre><code>passwd: password updated successfully\n</code></pre> </li> <li> <p>Change the password for web access:</p> <pre><code>[root@pikvm ~]# kvmd-htpasswd set admin\n</code></pre> <p>Submit the new password, retype it the second time to confirm, and press Enter.</p> </li> <li> <p>Run <code>ro</code> to change the access to the SD card back to the read-only mode:</p> <pre><code>[root@pikvm ~]# ro\n</code></pre> </li> <li> <p>Press Ctrl+D or type \"exit\" and press Enter to drop the root privileges.</p> </li> <li> <p>Go back one page in the browser. You should be back to the initial dashboard screen.</p> </li> </ol>"},{"location":"v2/#access-the-remote-system","title":"Access the remote system","text":"<ol> <li> <p>On the initial dashboard screen, click the KVM button to access the remote host.</p> </li> <li> <p>You should now see the host system's display and interact with it remotely using a keyboard and a mouse.</p> <p></p> </li> </ol>"},{"location":"v2/#important-next-steps","title":"Important next steps","text":"<ul> <li> <p>We strongly recommend to update the PiKVM OS after the first launch:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> </li> <li> <p>Learn about basics of PiKVM OS Configuration: where to find configs, how to edit the, etc.</p> Configuring PiKVM OS <p>Need more info? We have it!</p> <p>The following is a brief guide to configuring PiKVM. For more information (including the basics of YAML syntax and how to use a text editor in the Linux console), please refer to this page.</p> <p>Most of the PiKVM configuration files are located in the <code>/etc/kvmd</code> directory.</p> <p>The <code>/usr/lib/kvmd/main.yaml</code> file defines the platform configuration, and you should never edit it. To redefine system parameters use the file <code>/etc/kvmd/override.yaml</code>. All other files that are also not recommended for editing have read-only permissions.</p> <p>You can also create several files with the <code>.*yaml</code> suffix and put then into <code>/etc/kvmd/override.d</code> directory to split your customization into logical parts. The <code>override.yaml</code> file definitions takes precedence over the <code>override.d</code> directory.</p> <p>A complete list of all parameters can be viewed using the <code>kvmd -m</code> command.</p> <p>Files with the <code>*.yaml</code> suffix uses the YAML syntax and describes a parameter tree with key-value pairs of different types. To define the parameters within one section, an indent of 4 spaces is used. Comments starts with the <code>#</code> symbol.</p> <p>Only 4 spaces should be used for indentation</p> <p>Be careful when editing YAML and follow this rule. Invalid indentation or tabs instead of spaces will cause an error when starting the services.</p> <p>Sections under the same keys should be merged:</p> <ul> <li> <p>Wrong:</p> <pre><code>kvmd:\n gpio:\n drivers: ...\nkvmd:\n gpio:\n scheme: ...\n</code></pre> </li> <li> <p>Correct:</p> <pre><code>kvmd:\n gpio:\n drivers: ...\n scheme: ...\n</code></pre> </li> </ul> <p>In the <code>/etc/kvmd/meta.yaml</code> file you can specify some information regarding this PiKVM installation in an almost free YAML format.</p> </li> <li> <p>Get to know PiKVM Web UI: read this help section to better understand all the possibilities of the web user interface.</p> </li> <li> <p>Tune the HDMI dongle capture device if you're using it:</p> Persistent HDMI cable connection with USB dongle <p>Many USB video capture devices tell the server's video card that the HDMI cable is supposedly disconnected. This may lead to the fact that if you boot the server without an active stream, the server will not detect your capture card. This is easy to fix:</p> <ul> <li> <p>Switch filesystem to RW-mode: </p><pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Edit file <code>/etc/kvmd/override.yaml</code> and add these lines: </p><pre><code>kvmd:\n streamer:\n forever: true\n cmd_append: [--slowdown]\n</code></pre> </li> <li> <p>Finish: </p><pre><code>[root@pikvm ~]# ro\n[root@pikvm ~]# systemctl restart kvmd\n</code></pre> </li> <li> <p>Check that everything is working.</p> </li> </ul> </li> </ul>"},{"location":"v2/#further-recommendations","title":"Further recommendations","text":"<ul> <li>Harden the remote access by enabling 2FA.</li> <li>Configure access to PiKVM from the Internet using port forwarding or Tailscale VPN.</li> <li>Learn how configuration files are structured.</li> <li>Read how PiKVM is identified on the target host.</li> </ul>"},{"location":"v2/#known-issues-and-limitations","title":"Known issues and limitations","text":"<ul> <li> <p>Max resolution.PiKVM V2 with CSI bridge can only handle the maximum resolution 1920x1080@50Hz, 60Hz is not supported due hardware limitation. You can use any other resolution less than the specified one, for example 1280x720@60Hz. If you have any problems with video on CSI bridge, follow this guide.</p> </li> <li> <p>Motherboards compatibility.There may be compatibility issues with some motherboards, such as HP or DELL. If there is no image from the BIOS, you can fine-tune the HDMI settings, but it is possible that the mass storage devices will not be available in the BIOS. In the latter case, USB dynamic configuration will solve the problem.</p> </li> </ul>"},{"location":"v2/#basic-troubleshooting","title":"Basic troubleshooting","text":"<ul> <li> <p>Ensure that you are using the right OS image for your platform by running the following command: <code>pacman -Q | grep kvmd-platform</code>.</p> </li> <li> <p>If you are not getting a display, run the two following commands:</p> <ul> <li><code>dmesg | egrep 'tc35|1-1.4|uvc'</code></li> <li><code>systemctl status kvmd-tc358743</code></li> </ul> <p>If you see a failed message on that output, be sure verify the orientation of the CSI cable or try reseating it.</p> <p>Note that this is not a hotplug device, and you must first turn off the power.</p> </li> </ul>"},{"location":"v2/#getting-user-support","title":"Getting user support","text":"<p>If something doesn't work, check out our FAQ. Otherwise, head straight to our Support.</p>"},{"location":"v3/","title":"PiKVM V3 HAT & pre-assembled quickstart guide","text":""},{"location":"v3/#pikvm-v3-hat-pre-assembled-quickstart-guide","title":"PiKVM V3 HAT & pre-assembled quickstart guide","text":"<p>PiKVM is a feature-rich, production-grade, open-source, Raspberry Pi based KVM-over-IP device. It allows you to turn your computer on or off, restart it, configure the UEFI/BIOS, and even reinstall the OS using the Virtual CD-ROM or flash drive.</p> <p>PiKVM uses your remote keyboard and mouse to simulate a local keyboard, mouse, and monitor, which are then presented in a web browser as if you were working on a remote system directly.</p> <p>PiKVM V3 is available in two version:</p> <ul> <li>An assembly kit (HAT).</li> <li>A pre-assembled unit in a metallic box.</li> </ul> <p>The two versions have the same ports and functionality.</p>"},{"location":"v3/#whats-in-the-box","title":"What's in the box","text":"HATPre-Assembled <ul> <li>The PiKVM V3 HAT for Raspberry Pi 4</li> <li>USB-C bridge board</li> <li>ATX adapter board with mounting brackets and motherboard interface wiring</li> <li>2x Flat CSI-2 cables</li> <li>7x jumpers</li> <li>8x brass standoffs</li> <li>8x screws</li> </ul> <ul> <li>PiKVM V3.3 pre-assembled</li> <li>ATX adapter board with mounting brackets and motherboard interface wiring </li> <li>A 32 GB MicroSD card pre-imaged with the PiKVM OS</li> </ul>"},{"location":"v3/#hat-setup","title":"HAT setup","text":"<p>If you have an assembly kit without a metal case, you can use our free 3D printing case drawing:</p> <ul> <li>V3.2 is the pre-release model.</li> <li>V3.3 is the Kickstarter/Store model.</li> </ul> <p>Once you have that, do the following:</p> <ol> <li> <p>Flash the memory card. Please use the V3 image, V2 image is not compatible.</p> </li> <li> <p>Build PiKVM according to the illustrated instructions.</p> </li> </ol>"},{"location":"v3/#interface","title":"Interface","text":"Front viewRear viewLeft viewTop view <ol> <li>2x USB 2.0 </li> <li>2x USB 3.0 </li> <li>RJ45 1Gb Ethernet port</li> <li>RJ45 Serial console port</li> <li>Serial console active LED / Beacon LED (Green)</li> <li>USB 2.0 Serial console port </li> <li>Activity LED (Red)</li> <li>Power LED (Green)</li> <li>Power Input 5.1V 3A </li> </ol> <ol> <li>Micro SD card slot</li> <li>HDMI video input port</li> <li>USB 2.0 OTG connector</li> <li>RJ45 ATX control port</li> </ol> <ol> <li>Mini-HDMI output port</li> </ol> <ol> <li>Display</li> </ol>"},{"location":"v3/#flashing-the-os","title":"Flashing the OS","text":"<p>Most of the time, this step is not necessary. However, if there is a possibility that your device had a previous owner (e.g. \"Used - Like New\" on Amazon), we recommend reflashing the OS to ensure a clean start. Please follow this guide.</p>"},{"location":"v3/#wiring","title":"Wiring","text":"<p>Both the HAT and the pre-assembled V3 require several items available separately:</p> <ul> <li>Ethernet cable</li> <li>RJ-45 cable for ATX (optional)</li> <li>USB-C cable</li> <li>HDMI cable</li> <li>5V USB power adapter</li> </ul> <p>Let's connect all the wires before you power up the device.</p>"},{"location":"v3/#network","title":"Network","text":"<p>Connect Ethernet (bottom right on the front side) to the network, e.g., to the WiFI router.</p>"},{"location":"v3/#hdmi-and-usb-c","title":"HDMI and USB-C","text":"<p>HDMI input (the top right on the rear side) and OTG port (USB emulation) should be connected to the computer.</p> <p>Optionally, the ATX port can be connected to control the power. There should be no USB hub between PiKVM and the computer, as some UEFI/BIOS cannot detect them at the boot stage.</p>"},{"location":"v3/#power-up","title":"Power up","text":"<p>V3 comes has a USB-C 5V power supply. Attach the appropriate connector on the front side (top left). Do not block the ventilation holes on the sides of the device.</p> <p>After turning on the power, PiKVM OS generates unique SSH keys and certificates and performs all necessary operations on the memory card. It takes a few minutes. Do not turn off the device until it's fully booted for the first time. Once it's done, the PiKVM will show a greeting on the built-in display.</p>"},{"location":"v3/#connect-and-set-up","title":"Connect and set up","text":""},{"location":"v3/#configure-the-display","title":"Configure the display","text":"<p>The operating system on your remote computer will treat PiKVM as an additional display and use it in the Extend mode by default. That's why you will see an empty desktop when you first connect.</p> <p>To avoid that, go to the display settings in your remote computer's operating system and enable the mirror mode for the external screen that you operating system identifies as PiKVM. Refer to your operating system's documentation on that.</p>"},{"location":"v3/#access-pikvm","title":"Access PiKVM","text":"<p>By default, PiKVM receives a dynamic IP address via DHCP and shows it in the top row of the OLED display:</p> <pre><code>192.168.0.26\n(|) iface: eth0\ncpu: 1% mem: 13%\n</code></pre> <p>Let's assume that PiKVM has received the address <code>192.168.0.26</code> and has also been assigned a hostname <code>pikvm</code>.</p> <p>Type the URL in the browser's address bar and press Enter: https://192.168.0.26/ or https://pikvm/.</p> <p></p> <p>Submit the default credentials and click Login:</p> <ul> <li>Username: <code>admin</code></li> <li>Password: <code>admin</code></li> <li>2FA Code: disabled by default, skip this field</li> </ul> <p>You will see the initial dashboard screen of the PiKVM where you can access the remote host, connect to the PiKVM command line, or log out:</p> <p></p>"},{"location":"v3/#change-the-default-passwords","title":"Change the default passwords","text":"<p>For security's sake, it's best to change the default passwords immediately after running PiKVM for the first time.</p> <p>Passwords are important!</p> <p>Please ensure that you change both passwords: for Web UI access and for the Linux superuser (root).</p> <p>To do that:</p> <ol> <li> <p>On the initial dashboard screen, click the Terminal button to open the web terminal. You will see this command line interface:</p> <p></p> </li> <li> <p>Gain Linux superuser privileges:</p> <pre><code>$ su -\n</code></pre> <p>When prompted for password, use <code>root</code>.</p> </li> <li> <p>Run <code>rw</code> to change the access to the SD card to the write mode:</p> <pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Change the password for the Linux superuser:</p> <pre><code>[root@pikvm ~]# passwd root\n</code></pre> <p>Submit the new password, retype it the second time to confirm, press Enter, and you should see this:</p> <pre><code>passwd: password updated successfully\n</code></pre> </li> <li> <p>Change the password for web access:</p> <pre><code>[root@pikvm ~]# kvmd-htpasswd set admin\n</code></pre> <p>Submit the new password, retype it the second time to confirm, and press Enter.</p> </li> <li> <p>Run <code>ro</code> to change the access to the SD card back to the read-only mode:</p> <pre><code>[root@pikvm ~]# ro\n</code></pre> </li> <li> <p>Press Ctrl+D or type \"exit\" and press Enter to drop the root privileges.</p> </li> <li> <p>Go back one page in the browser. You should be back to the initial dashboard screen.</p> </li> </ol>"},{"location":"v3/#access-the-remote-system","title":"Access the remote system","text":"<ol> <li> <p>On the initial dashboard screen, click the KVM button to access the remote host.</p> </li> <li> <p>You should now see the host system's display and interact with it remotely using a keyboard and a mouse.</p> <p></p> </li> </ol>"},{"location":"v3/#important-next-steps","title":"Important next steps","text":"<ul> <li> <p>We strongly recommend to update the PiKVM OS after the first launch:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> </li> <li> <p>Learn about basics of PiKVM OS Configuration: where to find configs, how to edit the, etc.</p> Configuring PiKVM OS <p>Need more info? We have it!</p> <p>The following is a brief guide to configuring PiKVM. For more information (including the basics of YAML syntax and how to use a text editor in the Linux console), please refer to this page.</p> <p>Most of the PiKVM configuration files are located in the <code>/etc/kvmd</code> directory.</p> <p>The <code>/usr/lib/kvmd/main.yaml</code> file defines the platform configuration, and you should never edit it. To redefine system parameters use the file <code>/etc/kvmd/override.yaml</code>. All other files that are also not recommended for editing have read-only permissions.</p> <p>You can also create several files with the <code>.*yaml</code> suffix and put then into <code>/etc/kvmd/override.d</code> directory to split your customization into logical parts. The <code>override.yaml</code> file definitions takes precedence over the <code>override.d</code> directory.</p> <p>A complete list of all parameters can be viewed using the <code>kvmd -m</code> command.</p> <p>Files with the <code>*.yaml</code> suffix uses the YAML syntax and describes a parameter tree with key-value pairs of different types. To define the parameters within one section, an indent of 4 spaces is used. Comments starts with the <code>#</code> symbol.</p> <p>Only 4 spaces should be used for indentation</p> <p>Be careful when editing YAML and follow this rule. Invalid indentation or tabs instead of spaces will cause an error when starting the services.</p> <p>Sections under the same keys should be merged:</p> <ul> <li> <p>Wrong:</p> <pre><code>kvmd:\n gpio:\n drivers: ...\nkvmd:\n gpio:\n scheme: ...\n</code></pre> </li> <li> <p>Correct:</p> <pre><code>kvmd:\n gpio:\n drivers: ...\n scheme: ...\n</code></pre> </li> </ul> <p>In the <code>/etc/kvmd/meta.yaml</code> file you can specify some information regarding this PiKVM installation in an almost free YAML format.</p> </li> <li> <p>Get to know PiKVM Web UI: read this help section to better understand all the possibilities of the web user interface.</p> </li> <li> <p>Set up ATX connection if you need to control the power of the remote system.</p> </li> </ul>"},{"location":"v3/#further-recommendations","title":"Further recommendations","text":"<ol> <li> <p>Customize the system:</p> <ul> <li>Harden the remote access by enabling 2FA.</li> <li>Configure access to PiKVM from the Internet using port forwarding or Tailscale VPN.</li> <li>Enable a microphone for two-way audio.</li> <li>Learn how configuration files are structured.</li> <li>Read how PiKVM is identified on the target host.</li> </ul> </li> <li> <p>Configure hardware:</p> <ul> <li> <p>If you bought V3 HAT Assembly Kit and it includes the OLED display and/or the fan, you'll need to turn them on. Note this is only needed for the older V3 image for the HAT, in the box image everything is enabled by default:</p> Enabling the OLED and the fan <p>Log in to PiKVM and run these commands:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# systemctl enable --now kvmd-oled kvmd-oled-reboot kvmd-oled-shutdown\n[root@pikvm ~]# systemctl enable --now kvmd-fan\n[root@pikvm ~]# ro\n</code></pre> </li> <li> <p>Choose Fahrenheit over Celsius to display on the OLED:</p> How to set up Fahrenheit on the OLED <p>Create a directory for a configuration file:</p> <pre><code>[root@pikvm ~]# mkdir -p /etc/systemd/system/kvmd-oled.service.d\n</code></pre> <p>Create file <code>/etc/systemd/system/kvmd-oled.service.d/override.conf</code>:</p> <pre><code>[Service]\nExecStart=\nExecStart=/usr/bin/kvmd-oled --clear-on-exit --fahrenheit\n</code></pre> </li> </ul> </li> </ol>"},{"location":"v3/#known-issues-and-limitations","title":"Known issues and limitations","text":"<ul> <li> <p>Max resolution.PiKVM V3 supports maximum resolution 1920x1080@50Hz, 60Hz will not work. You can use any other resolution less than the specified one, for example: 1600x1200@60Hz, 1280x720@60Hz, etc. If you have problems with the video, follow this guide.</p> </li> <li> <p>Motherboards compatibility.There may be compatibility issues with some motherboards, such as HP or DELL. If there is no image from the BIOS, you can fine-tune the HDMI settings, but it is possible that the mass storage devices will not be available in the BIOS. In the latter case, USB dynamic configuration will solve the problem.</p> </li> <li> <p>HDMI backpowering.Under specific circumstances, PiKVM may hang during the boot. Turn off the PiKVM, disconnect all cables from it, take a close look at the diagram of its ports and jumpers below, and remove jumper #14 (it is to the right of the CSI connector, not available on the V3.2 board). Then you can connect and power up PiKVM again. (Technical background s described here.)</p> </li> <li> <p>IO ports.Before using GPIO pins to control a relay, KVM switch, or anything else, be sure to check the HAT pinout below. Many ports are busy with internal functions. Before using them for your own use, you must disable them, otherwise you may damage the PiKVM WebTerm</p> </li> </ul> The ports and jumpers diagram <p></p> <ol> <li>ATX controller interface (power on/off, reboot control, PWR and HDD ACT LEDs).</li> <li>HDMI reset jumper. Connects GPIO 17 and RESET pin to HDMI capture chip. Currently not used, don't touch it.</li> <li>SPI and GPIO for the custom extension boards.</li> <li>Audio capture jumpers. Connects I2S pins 18, 19, 20 to HDMI capture chip.</li> <li>UART access jumpers. Connects GPIO 14 and 15 to the RJ-45 and USB console ports.</li> <li>Serial console port (default: /dev/ttyAMA0, RS232 input, outputs +6V/-6V, for the Raspberry Pi or server console access, use the Cisco/Mikrotik-style cable).</li> <li>USB-C console port (shared with #6 above, takes priority over RJ45).</li> <li>Power and activity LEDs. On the left of the LEDs the watchdog jumper is located. Don't touch it.</li> <li>USB-C power input.</li> <li>I2C display connector.</li> <li>Alternate +5V power input/output header pins.</li> <li>RTC clock supercapacitor (rechargeable).</li> <li>FAN connector - PWM controlled.</li> <li>CSI-2 interface and HDMI backpowering jumper, see Step 9 of the Basic Setup. Open: (jumper removed) diode will stop current from HDMI input (backpower will be fixed), closed: (jumper connected to both pins) will allow current from HDMI device. </li> <li>Built-in power splitter port.</li> <li>HDMI capture port (max 1080p @ 50Hz) with sound capture support.</li> <li>USB emulation pins for alternative access.</li> <li>USB-C emulation port - this port is doing the emulation of a USB keyboard, mouse, Virtual CD-ROM or USB Flash Drive, USB-Ethernet, USB-Serial port and a lot of other Linux-supported features.</li> <li>1-Wire & Neo-pixel interface (under, advanced user feature).</li> </ol> The GPIO pinout <p>Warning</p> <p>Before proceeding, make sure that the mb you are using has normal ATX headers</p> <ul> <li>ATX control</li> <li><code>power led = GPIO 24</code> - Used for reading the host power state.</li> <li><code>hdd led = 22</code> - Same for the HDD activity.</li> <li><code>power switch = 23</code> - Used for pressing the power button of the host.</li> <li><code>reset switch = 27</code> - Same for the reset button.</li> </ul> <p>These pins can't be used for any other purposes even if ATX function is disabled.</p> <ul> <li> <p>I2C bus - <code>GPIO 2, 3</code> - Can be used as I2C ONLY (OLED/RTC).</p> </li> <li> <p>1-Wire [19] - <code>GPIO 4</code> - Also available under ATX RJ-45 port (point [19] on the above) as bi-directional buffered open-drain 5V for regular 1-Wire usage.</p> </li> <li> <p>UART - <code>GPIO 14, 15</code> - Can be used as UART only for the serial console. When jumpers [5] are removed, you can connect to pins 14 and 15 directly using GPIO header. Also you can remove jumper [5] and disable UART console in the <code>/boot/config.txt</code> and <code>/boot/cmdline.txt</code> to use this pins for any purpose. But it's not recommended.</p> </li> <li> <p>Red activity led on the front [8] - <code>GPIO 13</code> - Can be disabled in <code>/boot/config.txt</code> and available on the Neo-pixel port [19].</p> </li> <li> <p>PWM fan controller - <code>GPIO 12</code>. Can be used for custom purposes if the fan disconnected and <code>kvmd-fan</code> service is stopped.</p> </li> <li> <p>I2S HDMI sound - <code>GPIO 18, 19, 20, 21</code>. Can be used for custom purposes if the <code>tc358743-audio</code> overlay in <code>/boot/config.txt</code> is disabled AND jumpers [4] are removed.</p> </li> <li> <p>USB breaker - <code>GPIO 5</code> - Can't be used for any other purposes.</p> </li> </ul> <p>The standard Raspberry Pi HDMI output (marked as <code>VIDEO OUT</code> on the PiKVM case) displays its own PiKVM OS console.</p>"},{"location":"v3/#basic-troubleshooting","title":"Basic troubleshooting","text":"<ul> <li> <p>Ensure that you are using the right OS image for your platform by running the following command: <code>pacman -Q | grep kvmd-platform</code>.</p> </li> <li> <p>If you are not getting a display, run the two following commands:</p> <ul> <li><code>dmesg | egrep 'tc35|1-1.4|uvc'</code></li> <li><code>systemctl status kvmd-tc358743</code></li> </ul> </li> </ul>"},{"location":"v3/#getting-user-support","title":"Getting user support","text":"<p>If something doesn't work, check out our FAQ. Otherwise, head straight to our Support.</p>"},{"location":"v3_illustrated_install_instructions/","title":"Assembling PiKVM V3 HAT","text":""},{"location":"v3_illustrated_install_instructions/#assembling-pikvm-v3-hat","title":"Assembling PiKVM V3 HAT","text":"<p>PiKVM V3 HAT is an assembly kit. You can build it without any case whatsoever, order a metallic case separately, or 3D-print a case yourself. These videos cover all those use cases.</p> Video guide: Assembly with a metal case <p>NOTE: OLED will not light up till step 5 is performed, video was performed after it was already configured, heat sinks NOT included. </p><p></p> Video guide: Assembly with or without a 3D-printed case <p></p><p></p>"},{"location":"v3_illustrated_install_instructions/#step-1","title":"Step 1","text":"<p>Get the parts that are not in the assembly kit:</p> <ul> <li>Raspberry Pi 4 with 1Gb RAM or more</li> <li>Heat sinks (Optional)</li> <li>MicroSD card (at least 16Gb, class 10 recommended)</li> <li>USB-C to USB-A cable</li> <li>HDMI cable</li> <li>Straight Ethernet cable</li> <li>Power supply unit (5.1V 3A USB-C, recommended by the Raspberry Pi)</li> </ul> <p>Tip</p> <ul> <li>Please review the back of the box. All parts are required before the HAT is fully functional.</li> <li>The USB-C bridge is located in with the ATX end which includes a pink foam spacer.</li> <li>Please assemble the HAT onto the RPi and test all of the parts before installing in the case, it's easier to install in the case than to dissasemble it.</li> <li>If going from a V2 to a V3, the splitter is no longer needed.</li> </ul>"},{"location":"v3_illustrated_install_instructions/#step-2","title":"Step 2","text":"<p>Remove contents from assembly kit box:</p> <ul> <li>8x M.2 5x12mm screws for the case</li> <li>4x M.2 5x12mm screws for the fan</li> <li>4x bolts for the fan</li> <li>1x fan (30x30x7mm 5v)</li> <li>1x case top</li> <li>1x case bottom</li> <li>1x OLED display (0.91 IIC 128x32 LCD)</li> <li>2x bottom plastic risers</li> <li>1x plastic top riser</li> <li>1x plastic OLED holder that is also a front riser</li> <li>2x small FCC ribbon cables</li> <li>1x small rubber square that break out to 4x small rubber feet</li> </ul> <p>OLED is sensitive to pressure, do NOT push down on the very thin glass as it will crack and become non-functional</p>"},{"location":"v3_illustrated_install_instructions/#step-3","title":"Step 3","text":"<p>Take bottom part of the case, insert the RPI4 into the bottom case at an angle, you will need to flex the other side ever so slightly to get it to slot in.</p> <p></p> IF you bought heatsink's (sold seperatly), it's advised to install them now before installing the HAT"},{"location":"v3_illustrated_install_instructions/#step-4","title":"Step 4","text":"<p>Insert HAT at the same angle, take care to line up the pins on the Rpi with the HAT pin sleeve, the trick to this is to push the Rpi all of the way to the left then all of the way to the right for proper alignment, do NOT force till the pins are aligned. If properly aligned the pins will match up without issue.</p> <p></p> <p></p> ALTERNATIVE: As an alternative to the above, you can pre assemble the hat+fcc cable onto the RPI4, then insert them into the bottom portion of the case however you will need to flex the sides more whereby creating a bigger gap when fully assembled."},{"location":"v3_illustrated_install_instructions/#step-5","title":"Step 5","text":"<p>There are 2 ways to insert the FCC cable, you can add it when you insert the RPI in Step 2 OR wait till you also have the HAT installed and slide it into the slot.</p> <p></p> The blue stripes on the ends of the cable will ALWAYS face the side that will be used to tighten the FCC to the camera port or have it positioned towards the power - Ignore the smaller FCC cable that plugs into the USB, was phased out during the KS campaign. This image was used as a means of illustrating FCC placement and orientation"},{"location":"v3_illustrated_install_instructions/#step-6","title":"Step 6","text":"<p>Install the USB-C bridge.</p> This is packaged with the ATX board <p></p> <p></p> If you do not install this bridge, mouse/kb will not work HAT will still power on without this bridge installed"},{"location":"v3_illustrated_install_instructions/#step-7","title":"Step 7","text":"<p>Turn the bottom of the case upside down, install the 2 bottom plastic risers, it's best to install in a wing formation. Top first by inserting the top screws then slide the bottom part aligning the plastic to the holes then inserting the screws. At this point its OK to tighten the bottom screws. There is no need to use force, just tighten enough to prohibit movement.</p> <p></p>"},{"location":"v3_illustrated_install_instructions/#step-8","title":"Step 8","text":"<p>Take the plastic OLED holder, turn the OLED over where the back side is facing you and insert at an angle so as to create a space between the OLED and holder arm, take a flat head screwdriver (medium normal) and twist it enough so you can clear the electronics on the bottom of the OLED and continue to gently slide in the remaining OLED till its fully inserted.</p> <p></p> <p>Be careful on handling this display, slight pressure will damage the OLED, however in the event that this does happen, replacements are cheap and can be found in most electronic stores or Amazon, look for any IIC (I2C) .91 inch display for Arduino</p>"},{"location":"v3_illustrated_install_instructions/#step-9","title":"Step 9","text":"<p>Insert the OLED holder with the OLED display into the plug by gently rocking it back and forth till it's fully inserted.</p> <p></p>"},{"location":"v3_illustrated_install_instructions/#step-10","title":"Step 10","text":"<p>Install plastic spacer.</p> <p></p>"},{"location":"v3_illustrated_install_instructions/#step-11","title":"Step 11","text":"<p>Install the screws and bolts to secure the fan, it does not matter the orientation of the fan, push or pulling air will result in the same behavior, its personal preference.</p> <p></p>"},{"location":"v3_illustrated_install_instructions/#step-12","title":"Step 12","text":"<p>Insert the fan leads and align Red with positive and Black with negative.</p> <p></p> <p>You can damage the fan if installed incorrectly</p>"},{"location":"v3_illustrated_install_instructions/#step-13","title":"Step 13","text":"<p>Install the top of the case to the bottom, use the 4 remaining screws to secure the top.</p> <p></p>"},{"location":"v3_illustrated_install_instructions/#step-14","title":"Step 14","text":"<p>Please follow the V3 quick start guide to activate your PiKVM.</p>"},{"location":"v4/","title":"PiKVM V4 Mini & Plus quickstart guide","text":""},{"location":"v4/#pikvm-v4-mini-plus-quickstart-guide","title":"PiKVM V4 Mini & Plus quickstart guide","text":"<p>PiKVM is a feature-rich, production-grade, open-source, Raspberry Pi based KVM-over-IP device. It allows you to turn your computer on or off, restart it, configure the UEFI/BIOS, and even reinstall the OS using the Virtual CD-ROM or flash drive.</p> <p>PiKVM uses your remote keyboard and mouse to simulate a local keyboard, mouse, and monitor, which are then presented in a web browser as if you were working on a remote system directly.</p> <p>Datasheets:</p> <p>PiKVM V4 Mini PiKVM V4 Plus</p>"},{"location":"v4/#whats-in-the-box","title":"What's in the box","text":"<ul> <li>PiKVM V4 Mini or Plus device</li> <li>Micro SD card with pre-imaged PiKVM software</li> <li>ATX control board</li> <li>ATX connection cables</li> <li>ATX installation brackets</li> <li>1 x Ethernet cable</li> <li>1 x ATX cable</li> <li>1 x USB C to USB A cable</li> <li>12V 2A Power Supply (international adapters)</li> </ul>"},{"location":"v4/#interface","title":"Interface","text":"Front viewRear viewRight viewTop view <ol> <li>Power LED (Green)</li> <li>Power Input 5.1V 3A</li> <li>Activity LED (Red)</li> <li>Micro SD card slot</li> <li>USB 2.0 Serial console port</li> <li>Serial console active LED / Beacon LED (Green)</li> <li>RJ45 1Gb Ethernet port</li> <li>RJ45 Serial console port (V4 Plus only)</li> <li>USB 3.0 port 1 (V4 Plus only)</li> <li>Power Input 12V 2A (V4 Plus only)</li> </ol> <ol> <li>RJ45 ATX control port</li> <li>USB 2.0 OTG connector</li> <li>Beacon LED</li> <li>Video source ready status LED</li> <li>HDMI video input port</li> <li>Video capture ready status LED</li> <li>Optional antenna mounting hole (only one in V4 Mini)</li> <li>HDMI video output port 2 (V4 Plus only)</li> <li>HDMI video output port 1 (V4 Plus only)</li> <li>USB 3.0 port 2 (V4 Plus only)</li> <li>Optional antenna mounting hole (only one in V4 Mini)</li> </ol> <ol> <li>Service switches</li> <li>Kensington Security Slot</li> </ol> <ol> <li>Display</li> </ol>"},{"location":"v4/#flashing-the-os","title":"Flashing the OS","text":"<p>Most of the time, this step is not necessary. However, if there is a possibility that your device had a previous owner (e.g. \"Used - Like New\" on Amazon), we recommend reflashing the OS to ensure a clean start. Please follow this guide.</p>"},{"location":"v4/#wiring","title":"Wiring","text":"<p>Let's connect all the wires before you power up the device.</p>"},{"location":"v4/#network","title":"Network","text":"<p>Connect Ethernet (bottom right on the front side) to the network using the cable from the kit. The kit includes two Ethernet cables of different colors: one for the network, the second for ATX. Use whichever one you like best.</p>"},{"location":"v4/#hdmi-and-usb-c","title":"HDMI and USB-C","text":"<p>HDMI input (the bottom right on the rear side) and OTG port (USB emulation) should be connected to the computer.</p> <p>Optionally, the ATX port can be connected to control the power. There should be no USB hub between PiKVM and the computer, as some UEFI/BIOS cannot detect them at the boot stage.</p>"},{"location":"v4/#power-up","title":"Power up","text":"<p>V4 Mini and V4 Plus have different power supplies:</p> <ul> <li>The Mini comes with USB-C 5V power supply</li> <li>The Plus comes with with Barrel 12V</li> </ul> <p>The Plus can also work from 5V. In that case, avoid creating a significant power load on USB (external flash sticks, cameras, and so on).</p> <p>Attach the appropriate connector on the front side. Do not block the ventilation holes on the sides of the device.</p> <p>After turning on the power, PiKVM OS generates unique SSH keys and certificates and performs all necessary operations on the memory card. It takes a few minutes. Do not turn off the device until it's fully booted for the first time. Once it's done, the PiKVM will show a greeting on the built-in display.</p>"},{"location":"v4/#connect-and-set-up","title":"Connect and set up","text":""},{"location":"v4/#configure-the-display","title":"Configure the display","text":"<p>The operating system on your remote computer will treat PiKVM as an additional display and use it in the Extend mode by default. That's why you will see an empty desktop when you first connect.</p> <p>To avoid that, go to the display settings in your remote computer's operating system and enable the mirror mode for the external screen that your operating system identifies as PiKVM. Refer to your operating system's documentation on that.</p>"},{"location":"v4/#access-pikvm","title":"Access PiKVM","text":"<p>By default, PiKVM receives a dynamic IP address via DHCP and shows it in the top row of the OLED display:</p> <pre><code>192.168.0.26\n(|) iface: eth0\ncpu: 1% mem: 13%\n</code></pre> <p>Let's assume that PiKVM has received the address <code>192.168.0.26</code> and has also been assigned a hostname <code>pikvm</code>.</p> <p>Type the URL in the browser's address bar and press Enter: https://192.168.0.26/ or https://pikvm/.</p> <p></p> <p>Submit the default credentials and click Login:</p> <ul> <li>Username: <code>admin</code></li> <li>Password: <code>admin</code></li> <li>2FA Code: disabled by default, skip this field</li> </ul> <p>You will see the initial dashboard screen of the PiKVM, where you can access the remote host, connect to the PiKVM command line, or log out:</p> <p></p>"},{"location":"v4/#change-the-default-passwords","title":"Change the default passwords","text":"<p>For security's sake, it's best to change the default passwords immediately after running PiKVM for the first time. </p> <p>Passwords are important!</p> <p>Please ensure that you change both passwords: for Web UI access and for the Linux superuser (root).</p> <p>To do that:</p> <ol> <li> <p>On the initial dashboard screen, click the Terminal button to open the web terminal. You will see this command line interface:</p> <p></p> </li> <li> <p>Gain superuser privileges:</p> <pre><code>$ su -\n</code></pre> <p>When prompted for a password, use <code>root</code>.</p> </li> <li> <p>Run <code>rw</code> to change the access to the SD card to the write mode:</p> <pre><code>[root@pikvm ~]# rw\n</code></pre> </li> <li> <p>Change the password for the superuser:</p> <pre><code>[root@pikvm ~]# passwd root\n</code></pre> <p>Submit the new password, retype it the second time to confirm, press Enter, and you should see this:</p> <pre><code>passwd: password updated successfully\n</code></pre> </li> <li> <p>Change the password for web access:</p> <pre><code>[root@pikvm ~]# kvmd-htpasswd set admin\n</code></pre> <p>Submit the new password, retype it the second time to confirm, and press Enter.</p> </li> <li> <p>Run <code>ro</code> to change the access to the SD card back to the read-only mode:</p> <pre><code>[root@pikvm ~]# ro\n</code></pre> </li> <li> <p>Press Ctrl+D or type \"exit\" and press Enter to drop the root privileges.</p> </li> <li> <p>Go back one page in the browser. You should be back to the initial dashboard screen.</p> </li> </ol>"},{"location":"v4/#access-the-remote-system","title":"Access the remote system","text":"<ol> <li> <p>On the initial dashboard screen, click the KVM button to access the remote host.</p> </li> <li> <p>You should now see the host system's display and interact with it remotely using a keyboard and a mouse.</p> <p></p> </li> </ol>"},{"location":"v4/#important-next-steps","title":"Important next steps","text":"<ul> <li> <p>We strongly recommend updating the PiKVM OS after the first launch:</p> Updating PiKVM OS <p>To update, run following commands under the <code>root</code> user:</p> <pre><code>[root@pikvm ~]# pikvm-update\n</code></pre> <p>If you encounter an error like:</p> <pre><code>[root@pikvm ~]# pikvm-update\nbash: pikvm-update: command not found\n</code></pre> <p>It's most likely you have an old OS release. You can update the OS as follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# pacman -Syy\n[root@pikvm ~]# pacman -S pikvm-os-updater\n[root@pikvm ~]# pikvm-update\n</code></pre> <p>Next time you will be able to use the usual method with <code>pikvm-update</code>.</p> </li> <li> <p>Learn the basics of PiKVM OS Configuration: where to find configs, how to edit the, etc.</p> Configuring PiKVM OS <p>Need more info? We have it!</p> <p>The following is a brief guide to configuring PiKVM. For more information (including the basics of YAML syntax and how to use a text editor in the Linux console), please refer to this page.</p> <p>Most of the PiKVM configuration files are located in the <code>/etc/kvmd</code> directory.</p> <p>The <code>/usr/lib/kvmd/main.yaml</code> file defines the platform configuration, and you should never edit it. To redefine system parameters use the file <code>/etc/kvmd/override.yaml</code>. All other files that are also not recommended for editing have read-only permissions.</p> <p>You can also create several files with the <code>.*yaml</code> suffix and put then into <code>/etc/kvmd/override.d</code> directory to split your customization into logical parts. The <code>override.yaml</code> file definitions takes precedence over the <code>override.d</code> directory.</p> <p>A complete list of all parameters can be viewed using the <code>kvmd -m</code> command.</p> <p>Files with the <code>*.yaml</code> suffix uses the YAML syntax and describes a parameter tree with key-value pairs of different types. To define the parameters within one section, an indent of 4 spaces is used. Comments starts with the <code>#</code> symbol.</p> <p>Only 4 spaces should be used for indentation</p> <p>Be careful when editing YAML and follow this rule. Invalid indentation or tabs instead of spaces will cause an error when starting the services.</p> <p>Sections under the same keys should be merged:</p> <ul> <li> <p>Wrong:</p> <pre><code>kvmd:\n gpio:\n drivers: ...\nkvmd:\n gpio:\n scheme: ...\n</code></pre> </li> <li> <p>Correct:</p> <pre><code>kvmd:\n gpio:\n drivers: ...\n scheme: ...\n</code></pre> </li> </ul> <p>In the <code>/etc/kvmd/meta.yaml</code> file you can specify some information regarding this PiKVM installation in an almost free YAML format.</p> </li> <li> <p>Get to know PiKVM Web UI: read this help section to better understand all the possibilities of the web user interface.</p> </li> <li> <p>Set up an ATX connection if you need to control the power of the remote system.</p> </li> </ul>"},{"location":"v4/#further-recommendations","title":"Further recommendations","text":"<ol> <li> <p>Customize the system:</p> <ul> <li>Harden the remote access by enabling 2FA.</li> <li>Configure access to PiKVM from the Internet using port forwarding or Tailscale VPN.</li> <li>Enable a microphone for two-way audio.</li> <li>Enable HDMI pass-through and USB passthrough.</li> <li>Learn how configuration files are structured.</li> <li>Read how PiKVM is identified on the target host.</li> </ul> </li> <li> <p>Configure hardware:</p> <ul> <li> <p>Install and set up the Wi-Fi antenna:</p> Quick WiFi antenna how-to <p>The PiKVM V4 has a robust metal case that protects your device from physical damage and electromagnetic interference. This also means that an external antenna must be used for Wi-Fi. We recommend the official Antenna Kit for Raspberry Pi.</p> <p>To install the antenna, fix it in the round hole in the back side of the PiKVM, and connect the wire to the connector on the Compute Module 4, as described in the instructions.</p> <p>Next, to activate the antenna, add line <code>dtparam=ant2</code> to the <code>/boot/config.txt</code> file on PiKVM.</p> <p>Here is a video:</p> <p></p><p></p> <p>Follow this guide to configure Wi-Fi in PiKVM OS.</p> </li> <li> <p>Install and set up LTE/5G modem (only for PiKVM V4 Plus).</p> </li> <li> <p>Set up internal USB port for USB 3.0 (only for PiKVM V4 Plus):</p> Enable USB 3.0 on the internal port <p>PiKVM V4 Plus has an internal USB port. It supports USB 3.0, but only works with USB 2.0 devices by default to minimize the power consumption. You need to flash the USB controller to enable USB 3.0. To do so, follow these steps:</p> <ol> <li> <p>Open a terminal window and log into the PiKVM via SSH:</p> <pre><code>$ ssh user@host\n</code></pre> </li> <li> <p>Flash the USB controller using the built-in <code>flashrom</code> utility. Choose <code>usb3</code> for USB 3.0 support:</p> <pre><code>[root@pikvm ~]# flashrom-vl805 usb3\n</code></pre> <p>If you need to disable USB 3.0 support at any time later, run the same command, but use <code>default</code> instead:</p> <pre><code>[root@pikvm ~]# flashrom-vl805 default\n</code></pre> </li> <li> <p>Perform the soft reboot:</p> <pre><code>[root@pikvm ~]# reboot\n</code></pre> </li> <li> <p>After the soft reboot, perform the reboot by power: unplug and plug again the power cable.</p> </li> </ol> </li> <li> <p>Learn about DIP switches:</p> DIP switches purpose The left switch [1]: When pulled down (ON state), the advanced backpower protection is used. On the default state is OFF (up), \"diode protection\" is used. This is required for debugging at the request of technical support. Under normal conditions, it is not necessary to change the mode. The right switch [2]: When pulled down (ON state), the Power Delivery chip is activated on the USB OTG port. The default state is OFF (up). <p>To change the position of switches:</p> <ol> <li>Turn the PiKVM off.</li> <li>Change the position of the switched.</li> <li>Turn the PiKVM on.</li> </ol> <p>Warning</p> <p>Do not do that change the state of the DIP switched while the device is turned on. This may cause irreparable damage.</p> </li> <li> <p>Choose Fahrenheit over Celsius to display on the OLED:</p> How to set up Fahrenheit on the OLED <p>Create a directory for a configuration file:</p> <pre><code>[root@pikvm ~]# mkdir -p /etc/systemd/system/kvmd-oled.service.d\n</code></pre> <p>Create file <code>/etc/systemd/system/kvmd-oled.service.d/override.conf</code>:</p> <pre><code>[Service]\nExecStart=\nExecStart=/usr/bin/kvmd-oled --clear-on-exit --fahrenheit\n</code></pre> </li> </ul> </li> </ol>"},{"location":"v4/#known-issues-and-limitations","title":"Known issues and limitations","text":"<ul> <li> <p>There may be compatibility issues with certain motherboards, such as HP or DELL. If there is no image from the BIOS, you can fine-tune the HDMI settings, but it is possible that mass storage devices may not be available in the BIOS. In the latter case, USB dynamic configuration will solve the problem.</p> </li> <li> <p>While the V4 Plus features a Mini-PCIe slot, it was only designed for LTE modems. An NVME card will not work.</p> </li> </ul>"},{"location":"v4/#basic-troubleshooting","title":"Basic troubleshooting","text":"<ul> <li> <p>Ensure that you are using the right OS image for your platform by running the following command: <code>pacman -Q | grep kvmd-platform</code>.</p> </li> <li> <p>If you are not getting a display, run the two following commands:</p> <ul> <li><code>dmesg | egrep 'tc35|1-1.4|uvc'</code></li> <li><code>systemctl status kvmd-tc358743</code></li> </ul> </li> </ul>"},{"location":"v4/#getting-user-support","title":"Getting user support","text":"<p>If something doesn't work, check out our FAQ. Otherwise, head straight to our Support.</p>"},{"location":"video/","title":"Video modes","text":""},{"location":"video/#video-modes","title":"Video modes","text":"<p>PiKVM V3, V4 Plus/Mini and all DIY devices based on HDMI-CSI bridge provides three video streaming modes. This page explains the key differences between them and helps you to achieve optimal video performance.</p> <p>The video mode can be switched in the System menu in the Web UI. If you don't see the switch, probably your browser does not support H.264 video.</p> <p></p> <p>Quick tips</p> <ul> <li> <p>Good network: use <code>WebRTC</code> or <code>Direct</code> mode, set <code>H.264 gop = 0</code>.</p> </li> <li> <p>Bad network and <code>WebRTC</code> mode: Set <code>H.264 gop = 30</code>.</p> </li> <li> <p>Bad network and <code>Direct</code> mode: Set <code>H.264 gop = 0</code>.</p> </li> <li> <p>If the <code>WebRTC</code> mode is not working, try the <code>Direct</code>.</p> </li> <li> <p>The <code>Direct</code> mode doesn't support audio yet. If you need audio, but <code>WebRTC</code> is not working, follow this guide.</p> </li> </ul>"},{"location":"video/#settings","title":"Settings","text":"<ul> <li> <p>H.264 kbps (Bitrate) - with a large value, the video quality will be better, but the network traffic will increase.</p> </li> <li> <p>H.264 gop (Group of Pictures) - the number of frames between which a reference frame must be forcibly added. The recommended values are described above.</p> </li> </ul>"},{"location":"video/#webrtc-h264-mode","title":"WebRTC H.264 mode","text":"<p>This is the default mode. It'is using the efficient H.264 encoding to save traffic. The video is streamed over WebRTC protocol which you may have encountered when you used video calls in Discord or Google Chat. Since WebRTC does not use HTTP for video, establishing a connection is quite tricky (but PiKVM automates 99% of cases). If you have problems with the WebRTC mode, please check this guide.</p> <p>Advantages / Disadvantages</p> <ul> <li> <p>\u2705 Supported by all modern browsers.</p> </li> <li> <p>\u2705 Provides two-way audio on PikVM V3 and V4 Plus/Mini.</p> </li> <li> <p>\u274c The video may be lost due to a poor connection (like mobile internet, bad Wi-Fi, etc.), or because of the router settings, when WebRTC is given low priority.</p> </li> <li> <p>\u274c It may be blocked at all in some networks.</p> </li> <li> <p>\u274c Sometimes the latency may increase slightly due to the peculiarities of WebRTC processing in all browsers.</p> </li> </ul>"},{"location":"video/#direct-h264-mode","title":"Direct H.264 mode","text":"<p>The new experimental mode for real-time streaming, introduced by PiKVM. It also uses H.264 encoding, but streams the video over regular HTTP (WebSocket).</p> <p>Advantages / Disadvantages</p> <ul> <li> <p>\u2705 Very stable on poor networks, better than WebRTC (based on our tests and user reviews).</p> </li> <li> <p>\u2705 It is not blocked by firewalls because it appears to be regular HTTPS traffic.</p> </li> <li> <p>\u2705 The latency is low and stable too.</p> </li> <li> <p>\u274c No audio support right now (but it will).</p> </li> <li> <p>\u274c Some older browsers doesn't have the WebCodes support needed for this mode.</p> </li> </ul>"},{"location":"video/#legacy-mjpeg-mode","title":"Legacy MJPEG mode","text":"<p>Good old Motion JPEG. This is the way IP cameras have been streaming videos to browsers since ancient times. The stream is just infinite queue of JPEGs that replace each other in <code><img></code> HTML tag. There is no point in using it now if one of the previous modes is working.</p> <p>Advantages / Disadvantages</p> <ul> <li> <p>\u2705 Sometimes the H.264 is disabled in a browser by OS license limitations (for example, in Red Had Linux or Debian). But MJPEG is working always.</p> </li> <li> <p>\u2705 It is not blocked by firewalls because it appears to be regular HTTPS traffic.</p> </li> <li> <p>\u2705 Low latency if you have a good network.</p> </li> <li> <p>\u274c No audio support.</p> </li> <li> <p>\u274c\u274c\u274c Consumes a HUGE amount of traffic. No Wi-Fi, no mobile, nothing but cable connection will work.</p> </li> </ul>"},{"location":"video/#what-if-h264-is-not-supported-by-browser-at-all","title":"What if H.264 is not supported by browser at all","text":"<p>There are some Linux distro's that require more work to be able to use H.264, this may include any RedHat or Debian variant. Here some examples:</p> <ul> <li> <p>In case of Chromium on Fedora, you can connect the RPM Fusion repo and then install the <code>chromium-freeworld</code> package instead of <code>chromium</code>.</p> </li> <li> <p>On Debian GNU/Linux and Firefox, make sure the OpenH264 Plugin both exists and is enabled. Press <code>Ctrl+Shift+A</code> to open the <code>Add-on Manager</code>, then press <code>Plugins</code>. There you should see OpenH264 Video Codec provided by Cisco Systems, Inc. Make sure it is enabled by pressing the \"more options\" button (tree dots), then pressing <code>Always Activate</code>.</p> </li> </ul>"},{"location":"video/#video-recording","title":"Video recording","text":"<p>At the moment, it is not possible to record videos in a convenient way from the Web UI, but a small trick in the console can be used to record videos without sound. It's only available on all PiKVM models which support H.264 video.</p> <p>Available since KVMD 4.110</p> Recording video from terminal on Linux or Mac OS <ol> <li> <p>Install <code>ffmpeg</code> and <code>websocat</code>.</p> </li> <li> <p>Let's assume that your PiKVM is located on <code>https://pikvm</code> and uses a self-signed certificate. Request the stream from it from the first opened console on your PC (not PiKVM):</p> <pre><code>[user@host ~]$ websocat -k wss://pikvm/api/ws?stream=1 -H X-KVMD-User:admin -H X-KVMD-Passwd:admin\n</code></pre> </li> <li> <p>Keeping the previous command running, open a new terminal and run the video recording process:</p> <pre><code>[user@host ~]$ websocat -b -B 10000000 -k wss://pikvm/api/media/ws?video=h264 -H X-KVMD-User:admin -H X-KVMD-Passwd:admin | ffmpeg -use_wallclock_as_timestamps 1 -i pipe: -c:v copy my_captured_video.mp4\n</code></pre> </li> <li> <p>Same can be done on PiKVM itself, locally.</p> </li> <li> <p>Press <code>Ctrl+C</code> to stop the recording.</p> </li> </ol> Take a screenshot from terminal on PiKVM <p>To take a screenshot, switch filesystem to RW-mode like in previous example and run the stream.</p> <p>Next, take a screenshot:</p> <pre><code>[root@pikvm ~]# curl --unix-socket /run/kvmd/ustreamer.sock http://localhost/snapshot -o /tmp/screen.jpg\n</code></pre>"},{"location":"vnc/","title":"VNC","text":""},{"location":"vnc/#vnc","title":"VNC","text":"<p>As an alternative to the Web UI, a regular VNC client can be used to access to the PiKVM.</p> <p>The main advantage of VNC over the browser is the ability to expand the image to the full screen, as well as complete interception of all keyboard shortcuts. In some cases, VNC will be more responsive than the browser, especially on weak client computers.</p> <p>Warning</p> <p>Don't use VNC without X.509 or TLS encryption on untrusted networks! Otherwise your password will be transmitted over the network in plain text. Unfortunately, this is the reality of the VNC protocol.</p> <p>Note</p> <p>The performance of VNC on PiKVM does not make sense to compare with regular VNC servers or a similar remote access tool at the OS level. PiKVM will run a little slower due to the fact that access is done at the hardware level.</p> <p>A typical video processing chain looks like this:</p> <ul> <li>Regular VNC/RDP/TeamViewer/Etc: <code>OS -> Remote access server -> Network -> Client</code>.</li> <li>PiKVM: <code>OS -> Video card -> PiKVM video capture -> PiKVM server -> Network -> Client</code>.</li> </ul>"},{"location":"vnc/#enabling-vnc-on-the-pikvm-side","title":"Enabling VNC on the PiKVM side","text":"<ol> <li> <p>The recommended client is TigerVNC.</p> </li> <li> <p>Switch the PiKVM filesystem to read-write mode using command <code>rw</code>.</p> </li> <li> Optional for non-TigerVNC clients: Change the keybobard layout for non-US keyboard <p>This step is nessessory if you're using a client that does not support the direct keyboard access.</p> <p>In this case you can force the client layout in <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>vnc:\n keymap: /usr/share/kvmd/keymaps/ru\n</code></pre> <p>All available keymaps are located in <code>/usr/share/kvmd/keymaps</code>:</p> <p></p> </li> <li> Optional for non-TigerVNC and NOT RECOMMENDED: Enable VNCAuth method <p>This step is nessessory if you're using a client that does not support the user/password auth method like TightVNC (don't confuse it with TigerVNC).</p> <p>In this case you can enable VNCAuth passphrases mode in <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>vnc:\n auth:\n vncauth:\n enabled: true\n</code></pre> <p>To set passphrases edit the file <code>/etc/kvmd/vncpasswd</code>.</p> <p>But once again: THIS IS AN UNSAFE AUTHORIZATION METHOD and it is better to use TigerVNC.</p> </li> <li> <p>Enable <code>kvmd-vnc</code> daemon. VNC will be available on the port 5900: <code>systemctl enable --now kvmd-vnc</code>.</p> </li> <li> <p>Switch filesystem back to read-only: <code>ro</code>.</p> </li> </ol> <p>Note</p> <p>With enabled 2FA, you will need to append the one-time code to the password without spaces. That is, if the password is <code>foobar</code> and the code is <code>123456</code>, then the string <code>foobar123456</code> should be used as a password.</p>"},{"location":"vnc/#configuring-the-client","title":"Configuring the client","text":"<p>We recommend TigerVNC for a better experience on a desktop.</p> <p>If you're using PiKVM V3+ or DIY based on CSI bridge, you can try the latest version (>= 1.13.0) of TigerVNC with H.264 support. It will improve performance and save traffic.</p> <p>H.264 video mode is available in binary builds for Windows, for other OS it needs to be compiled manually (<code>ffmpeg</code> libraries required to build).</p> <p>Here are our recommended settings for TigerVNC:</p> Compression tab Security tab If your client does not support H.264, choose Tight <p>For iOS and Android the recommended application is bVNC:</p> <ul> <li>Google Play</li> <li>App Store</li> </ul>"},{"location":"vnc/#hotkeys","title":"Hotkeys","text":"<p>Inside a VNC session, you can use several hotkeys related to PiKVM, independent of the VNC client. Hotkeys are triggered by quickly pressing and releasing each key sequentially (that is, you don't need to hold them down like <code>Ctrl+Alt+Del</code>).</p> <ul> <li> <p><code>LeftAlt, LeftAlt, P</code> - Paste text from the clipboard. PiKVM does not have access to the clipboard, so pasting works as if you had typed this text. ASCII always works, layout switching is not supported. To type text in a different language, you need the layout on the host to match the one you are using (and keymap is also configured as described above for some VNC clients)</p> </li> <li> <p><code>LeftAlt, LeftAlt, 1</code> (1-8) - Switch to channel 1 with PiKVM Switch, when you have one or two switches.</p> </li> <li> <p><code>LeftAlt, LeftAlt, 3, 2</code> - Switch to unit 3, channel 2 of PiKVM Switch chain, when you have more than two switches. Single-key port numbers do not work if there are more than two candles.</p> </li> </ul>"},{"location":"vnc/#unsupported-clients","title":"Unsupported clients","text":"<ul> <li>RealVNC - Does not support most widely used open VNC protocol extensions.</li> <li>Remmina - Slightly imperfect algorithms for matching settings with the server, we are working on it.</li> <li>Guacamole - Incorrectly implements vencrypt, no JPEG compression.</li> <li>Vinagre - Incorrectly implements vencrypt, dead.</li> </ul>"},{"location":"webrtc_config/","title":"WebRTC H.264","text":""},{"location":"webrtc_config/#webrtc-h264","title":"WebRTC H.264","text":"<p>This is the default mode. It'is using the efficient H.264 encoding to save traffic. The video is streamed over WebRTC protocol which you may have encountered when you used video calls in Discord or Google Chat.</p> <p>It is available on PiKVM V3, V4 Plus/Mini and all DIYdevices based on HDMI-CSI bridge.</p> <p>The video mode can be switched in the System menu in the Web UI. If you don't see the switch, probably your browser does not support H.264 video.</p>"},{"location":"webrtc_config/#how-its-working","title":"How it's working","text":"<p>The Direct H.264 or MJPEG video is streaming video using the similar HTTP connection like to get the Web UI. This means that for remote access, you just need to forward only ports <code>80</code> and <code>443</code> on your router it has public external IP address.</p> <p>In contrast, WebRTC is a completely different way of transmitting video. It uses a P2P connection and UDP. This reduces network load, but makes it difficult to connect\u2014the PiKVM needs to know your network configuration in order to use it correctly: public IP, NAT type and so on.</p> <p>To achieve this, the PiKVM checks which of the network interfaces is used for the default gateway, and tries to find out your external IP address using the Google STUN server.</p> <p>Tip</p> <p>Google STUN servers was choosen for reliability reasons.</p> <p>If you don't want to use it, you can choose any other public STUN server you like, or set up your own.</p> <p>To change the STUN server, edit <code>/etc/kvmd/override.yaml</code> (an example):</p> <pre><code>janus:\n stun:\n host: stun.stunprotocol.org\n port: 3478\n</code></pre> <p>... and restart <code>kvmd-janus</code> service using <code>systemctl restart kvmd-janus</code>.</p>"},{"location":"webrtc_config/#custom-janus-config","title":"Custom Janus config","text":"<p>Janus is a WebRTC gateway that is used to transmit the video from PiKVM uStreamer. PiKVM has a special service named <code>kvmd-janus</code> which is a wrapper for Janus that monitors the network configuration and applies changes.</p> <p>However, if your PiKVM is not connected to the Internet and/or you want to use a custom Janus configuration, you should run the <code>kvmd-janus-static</code> service instead.</p> <p>The configuration is located in <code>/etc/kvmd/janus/janus.jcfg</code>. You can change all you need according to the Janus Documentation, stop the <code>kvmd-janus</code> and start the <code>kvmd-janus-static</code> service:</p> <pre><code>[root@pikvm ~]# systemctl disable --now kvmd-janus\n[root@pikvm ~]# systemctl enable --now kvmd-janus-static\n</code></pre>"},{"location":"webrtc_config/#troubleshooting","title":"Troubleshooting","text":"<p>In some cases, WebRTC may not work. Here some common tips:</p> <ul> <li> <p>Clear the browser cache.</p> </li> <li> <p>Try any other browser, incognito or private window without any extensions.</p> </li> <li> <p>Tricky IPv6 configuration on the network can be a problem. IPv6 support for WebRTC in PiKVM is still in its infancy, so if your network has IPv4, it will be easiest to disable IPv6 on PiKVM. To do this, switch the file system to write mode using <code>rw</code> command, add option <code>ipv6.disable_ipv6=1</code> to <code>/boot/cmdline.txt</code> and perform <code>reboot</code>. Also see here.</p> </li> <li> <p>A paranoid firewall can interfere too when you try to connect to the PiKVM by forwarding port 443 to the Internet from the internal network. WebRTC is not enough of this, it uses UDP on ports 20000-40000 for a P2P connection. Make sure that the Firewall does not block them.</p> </li> <li> <p>If nothing helps, open the browser's JavaScript console, look at the log and contact our Support. Developers and/or experienced users will definitely help you.</p> </li> </ul>"},{"location":"webui/","title":"Getting to know the web UI","text":""},{"location":"webui/#logging-in","title":"Logging in","text":"<p>After following the first steps document on setup, you will be presented with the following pages (Chrome is being used in the following examples)</p> <p></p> <p>Click Advanced</p> <p></p> <p>Click Proceed</p> <p>Credentials are found in the first steps document that is located to the left</p> <p></p> <p>This is where you fill in the login credentials, please be sure to review the first steps document first. This is also where you configure the 2FA token.</p>"},{"location":"webui/#initial-screen","title":"Initial screen","text":"Please expand to see what each number represents <ol> <li>This is where your PiKVM name will go - Please reference the first steps document on how to change this</li> <li>This is where you can access the display for the Target system</li> <li>You can open a web terminal and put in commands that you will find within these documents</li> <li>By default this will not show up till its activated, this will tell you the VNC address you need to use</li> <li>This is so you can logout of your PiKVM</li> <li>Please read carefully</li> <li>These are links to the PiKVM project, current documentation and support</li> <li>NOT SHOWN, in the lower left of the KVM screen is some information that when you mouse over, will let you know what they are for</li> </ol>"},{"location":"webui/#web-ui-toolbar","title":"Web UI toolbar","text":"Please expand to see what each number represents <ol> <li>This is the system setting, more details will be shown below</li> <li>This is the interface to controlling the ATX, will ONLY work if wired up correctly</li> <li>This is part of the MSD and will show you what images/iso's are available</li> <li>This is where you can program in a Macro (Ex. Hitting F2 to get into the bios, setting Infinite loop playback to on and doing other tasks)</li> <li>This is where you can SEND text to the Target or using OCR, you can copy FROM the target, be mindful that OCR can make mistakes, please review before finalizing</li> <li>This is where you can find most Shortcuts (Windows only, for now) (Not editable)</li> <li>This is placed here to give you an idea what you can achieve if you make your own menu item</li> </ol>"},{"location":"webui/#the-system-menu","title":"The System menu","text":"<p>The following is self explanatory but will highlight the important parts</p> Please expand to see what each number represents <ol> <li> <p>System Icons</p> <p>ETH Icon = PiKVM network connectivity</p> <p>Monitor Icon = Shows if the target is sending an active signal</p> <p>KeyBoard Icon = Shows if data for the KB is active, will likely show Orange/Green as data is passed and goes idle</p> <p>Mouse Icon = Same as above</p> </li> <li> <p>These are additional buttons for important acitivies</p> <p>Term = Can launch a quick Web Terminal along with the active KVM</p> <p>About = Shows everything About your PiKVM, including PiKVM Hardware and version</p> <p>Log = Shows the current log from your PiKVM</p> </li> <li> <p>ONLY for MJPEG mode</p> </li> <li>ONLY for H.264 (WebRTC) mode</li> </ol>"},{"location":"webui/#the-atx-menu","title":"The ATX menu","text":"<p>This ONLY works if you have the hardware connected to the MB, otherwise will not work</p>"},{"location":"webui/#the-drive-menu","title":"The Drive menu","text":"<p>This is where you can select the IMG or ISO's that are stored</p>"},{"location":"webui/#the-macro-menu","title":"The Macro menu","text":"<ol> <li>Please read and understand this section</li> <li>This is where you can upload or download your scripts</li> </ol>"},{"location":"webui/#the-text-menu","title":"The Text menu","text":"<p>Note</p> <p>This is not like VNC/AnyDesk/TeamViewer as these are software solutions, this is a hardware solution therefor cannot change the behavior of the target system. This does not act like a clipboard</p> <ol> <li> <p>This will allow you to paste text to the target system\u2014be mindful whats being pasted to the target and how.</p> </li> <li> <p>This will allow you to ONLY copy text from the target\u2014be mindful that OCR will do its best to recognize text but may fail at it.</p> </li> </ol>"},{"location":"webui/#the-shortcuts-menu","title":"The Shortcuts menu","text":"<p>This is an expanded view and shows the shortcuts mostly for Windows.</p>"},{"location":"wifi/","title":"Setting up Wi-Fi","text":"<p>Tip</p> <ul> <li>There is nothing more reliable than wired Ethernet, so it's better to use it. Wi-Fi with the steel case (on PiKVM V3 and V4) results in poor performance. But who are we to stop you... :)</li> <li>Devices based on Raspberry Pi Zero 2 W does not support 5GHz Wi-Fi.</li> </ul> <p>The following describes how to setup a Wi-Fi connection. We recommend to do this while having a display and keyboard or a serial console connected directly to the Raspberry Pi as you will loose network connectivity once you connect to a Wi-Fi. Alternatively you can connect to the PiKVM via SSH. The built-in Web Terminal (available through the browser) should also work.</p> <p>Take a look at the easiest way</p> <p>This guide describes how to manually set up a Wi-Fi. An easier way is to use On-boot config. It is also mandatory for Zero 2 W board.</p>"},{"location":"wifi/#setting-up-wi-fi-manually","title":"Setting up Wi-Fi manually","text":"<ol> <li> <p>Make filesystem writable using the <code>rw</code> command.</p> </li> <li> <p>Create the Wi-Fi settings file <code>/etc/systemd/network/wlan0.network</code> with the following content:</p> <pre><code>[Match]\nName=wlan0\n\n[Network]\nDHCP=yes\nDNSSEC=no\n\n[DHCP]\nClientIdentifier=mac\nRouteMetric=50\n</code></pre> </li> <li> <p>Set network ESSID and password:</p> <pre><code>[root@pikvm ~]# wpa_passphrase 'MyNetwork' 'P@assw0rd' > /etc/wpa_supplicant/wpa_supplicant-wlan0.conf\n[root@pikvm ~]# chmod 640 /etc/wpa_supplicant/wpa_supplicant-wlan0.conf\n</code></pre> <p>WPA2 and WPA3 support</p> <p>Add options <code>key_mgmt=WPA-PSK-SHA256 WPA-PSK</code> and <code>ieee80211w=1</code> to <code>/etc/wpa_supplicant/wpa_supplicant-wlan0.conf</code></p> <p>Using Wi-Fi with hidden ESSID</p> <p>Add option <code>scan_ssid=1</code> to <code>/etc/wpa_supplicant/wpa_supplicant-wlan0.conf</code></p> <p>Using 5GHz Wi-Fi in the USA</p> <p>Add option <code>country=US</code> to <code>/etc/wpa_supplicant/wpa_supplicant-wlan0.conf</code></p> <p>Block 2ghz or 5ghz</p> <p>Add option <code>bssid=xx:xx:xx:xx:xx:xx</code> to <code>/etc/wpa_supplicant/wpa_supplicant-wlan0.conf</code> within the <code>network={</code> block</p> </li> <li> <p>Enable WPA-supplicant service:</p> </li> </ol> <pre><code>[root@pikvm ~]# systemctl enable wpa_supplicant@wlan0.service\n</code></pre> <ol> <li>Make filesystem read-only again using <code>ro</code> command</li> </ol>"},{"location":"wifi/#multiple-wi-fi-networks","title":"Multiple Wi-Fi networks","text":"<p>You can configure PiKVM to connect to one of several known Wi-Fi networks. To do this, just simply add the configuration of these networks. Pay attention to the symbol <code>>></code>, it is used to append at the end of configuration, while a single <code>></code> will overwrite the entire configuration.</p> <ol> <li> <p>Make the filesystem writeble with <code>rw</code> command.</p> </li> <li> <p>Add some new networks:</p> <pre><code>[root@pikvm ~]# wpa_passphrase 'Wifi1' 'P@assw0rd' >> /etc/wpa_supplicant/wpa_supplicant-wlan0.conf\n[root@pikvm ~]# wpa_passphrase 'Wifi2' 'P@assw0rd' >> /etc/wpa_supplicant/wpa_supplicant-wlan0.conf\n[root@pikvm ~]# wpa_passphrase 'Wifi3' 'P@assw0rd' >> /etc/wpa_supplicant/wpa_supplicant-wlan0.conf\n</code></pre> </li> <li> <p>Restart the service: <code>systemctl restart wpa_supplicant@wlan0.service</code>.</p> </li> <li> <p>Make the filesystem read-only again using <code>ro</code> command</p> </li> </ol>"},{"location":"wifi/#useful-console-commands","title":"Useful console commands","text":"<ul> <li><code>iwconfig</code> - Manipulate the basic wireless parameters.</li> <li><code>iwlist</code> - Allow's you to initiate scanning and list frequencies, bit-rates, encryption keys, etc.</li> <li><code>iwspy</code> - Displays per node link quality.</li> <li><code>iwpriv</code> - Allow's you to manipulate the Wireless Extensions specific to a driver (private).</li> </ul> Some examples <pre><code>[root@pikvm ~]# iw dev wlan0 scan | egrep \"signal:|SSID:\" | sed -e \"s/\\tsignal: //\" -e \"s/\\tSSID: //\" | awk '{ORS = (NR % 2 == 0)? \"\\n\" : \" \"; print}' | sort\n</code></pre> <pre><code>[root@pikvm ~]# iwlist wlan0 scan | egrep \"Cell|ESSID|Signal|Rates\"\n</code></pre> <pre><code>[root@pikvm ~]# iwlist wlan0 scan\n</code></pre> <pre><code>[root@pikvm ~]# iw wlan0 info\n</code></pre>"},{"location":"wifi/#additional-resources","title":"Additional resources","text":"<ul> <li>Arch Linux Wiki for systemd-networkd</li> </ul>"},{"location":"wiring_examples/","title":"Some example wiring setups","text":""},{"location":"wiring_examples/#hdmi-csi","title":"HDMI-CSI","text":"<p>List of items: (WARNING! Links may dissappear or no longer work, this just gives you an idea)</p> <ul> <li>USB-A male to USB-A male (For data)</li> <li>PortaPow USB Power Blocker</li> <li>USB C OTG Splitter</li> <li>Normal HDMI Cable</li> <li>DisplayPort TO HDMI pigtail (Cable) (Pic is displayed wrong)</li> <li>TARGET (Anything you want to control)</li> </ul>"},{"location":"wiring_examples/#another-csi-example-using-the-pcb-splitter","title":"Another CSI example using the PCB splitter","text":""},{"location":"wiring_examples/#hdmi-usb","title":"HDMI-USB","text":""},{"location":"wiring_examples/#direct-connect-to-target","title":"Direct connect to target","text":"<p>Explanation of pic - USB-C from PI to USB-A onto target which also powers the PI</p> <p>Use case: - Trying to determine if the data cable is truly a data cable and not just a power cable - Testing to see if the splitter or cable is defective - Basic troubleshooting</p>"},{"location":"wiring_examples/#ezcoo-wiring-example","title":"EZCOO wiring example","text":""},{"location":"wol/","title":"Wake-on-LAN","text":""},{"location":"wol/#wake-on-lan","title":"Wake-on-LAN","text":""},{"location":"wol/#simplified-method-one-host","title":"Simplified method (one host)","text":"<p>To use Wake-on-LAN with your server you must define some options such as the server's MAC address and (optionally) IP address. Use <code>/etc/kvmd/override.yaml</code>. The format is:</p> <pre><code>kvmd:\n wol:\n mac: ff:ff:ff:ff:ff:ff\n</code></pre> <p>Replace <code>ff:ff:ff:ff:ff:ff</code> with the MAC of your server. By default, a packet is sent via a broadcast request to the entire IPv4 network (<code>255.255.255.255</code>, port <code>9</code>), but you can address it to a specific static address:</p> <pre><code>kvmd:\n wol:\n mac: ff:ff:ff:ff:ff:ff\n ip: 192.168.0.100\n # port: 9 # By default\n</code></pre> <p>... then restart <code>kvmd</code> using <code>systemctl restart kvmd</code>. It will now show up in the system button in the upper right corner.</p>"},{"location":"wol/#gpio-method-multiple-hosts","title":"GPIO method (multiple hosts)","text":"<p>Follow the manual for building the GPIO menu and use the <code>wol</code> driver to build a menu with many buttons tied to different hosts.</p>"},{"location":"xh_hk4401/","title":"XH-HK4401 4-port HDMI USB KVM Switch","text":""},{"location":"xh_hk4401/#xh-hk4401-4-port-hdmi-usb-kvm-switch","title":"XH-HK4401 4-port HDMI USB KVM Switch","text":"<p>This document was supplied by a community member, thus it is not officially endorsed or supported.</p> <p>PiKVM + Multiport Switches compatibility</p> <p>Please note that this switch requires a USB port for control. The following devices can provide this:</p> <ul> <li>PiKVM V3 & V4 Plus.</li> <li>DIY devices based on Raspberry Pi 2, 3 and 4.</li> </ul> <p>The following devices are not compatible:</p> <ul> <li>PiKVM V4 Mini - it doesn't have a USB host port and cannot control switches, it's a single-host device.</li> <li>DIY based on Raspberry Pi Zero 2 W - it doesn't have USB host port too.</li> </ul> <p></p> <p>This KVM is sold under many names, and comes in two versions. The only way these two versions differ is that one has one of its USB ports replaced with a PS/2 port. The identifying feature is that they come with a small external control unit with 4 buttons. This controller is connected to the main KVM via a micro USB cable, however this is NOT as USB connection.</p> <p>Warning</p> <p>Audio was not tested, it is assumed to be non-functional</p>"},{"location":"xh_hk4401/#connections","title":"Connections","text":"<ol> <li> <p>Connect the USB-A cable from the Raspberry Pi OTG port to to any of the USB ports on the XH-HK4401 switch. All 3/4 USB ports work exactly the same, internally they are just connected to a USB HUB.</p> </li> <li> <p>Connect the HDMI out from the XH-HK4401 switch to the Raspberry Pi CSI-2 to HDMI input.</p> </li> <li> <p>Connect host USB and HDMI cables from the XH-HK4401 switch to the machines to be managed per the switch instructions.</p> </li> <li> <p>Finally see below for details about connecting to the control micro USB port. This it not a normal USB micro port.</p> </li> </ol> <p>Warning</p> <p>There is a limitation in the underlying PiKVM software related to plugging video cables from a host which is already powered and connected to a monitor to a Raspberry Pi HDMI-CSI bridge. These limitations apply equally when using the XH-HK4401 KVM switch. If video is not present in PiKVM, try keeping all host machines off and connecting them directly to the XH-HK4401 switch before powering the hosts on.</p>"},{"location":"xh_hk4401/#rs-232-control-cable","title":"RS-232 control cable","text":"<p>The control unit communicates to the KVM using the RS-232 protocol (at 5v) not USB, and one of the following solutions must be used.</p>"},{"location":"xh_hk4401/#inverting-usb-uart-adapter-ft-232-the-easy-way","title":"Inverting USB UART adapter (FT-232) - The easy way","text":"<p>Some USB UART adapters have the rare feature to invert the logic level of the RX/TX signals. For example the FTDI FT232 can be configured via the FTDI configuration GUI to do this. With such an adapter, the circuit above is not required. All you need is to connect it to a micro-USB connector.</p> <p>Warning</p> <p>These options will only work on UART adapters with genuine FTDI chips. There are a lot of cheap fakes on the market that either lack this option, or will prevent you from changing the settings. To avoid getting a fake ensure you always purchase from a reputable store and brand (Adafruit, Sparkfun, etc.), Amazon is not a reputable store.</p>"},{"location":"xh_hk4401/#linux-instructions","title":"Linux Instructions","text":"References I used to get my FTDIs working: <ul> <li>https://waterpigs.co.uk/articles/ftdi-configure-mac-linux/</li> <li>https://manpages.debian.org/testing/ftdi-eeprom/ftdi_eeprom.1.en.html</li> <li>https://manpages.ubuntu.com/manpages/bionic/man1/ftdi_eeprom.1.html</li> <li>http://developer.intra2net.com/git/?p=libftdi;a=blob;f=src/ftdi.h</li> <li>http://developer.intra2net.com/git/?p=libftdi;a=blob;f=src/ftdi.c</li> <li>http://developer.intra2net.com/git/?p=libftdi;a=tree;f=ftdi_eeprom</li> <li>http://developer.intra2net.com/git/?p=libftdi;a=blob;f=ftdi_eeprom/example.conf</li> <li>http://developer.intra2net.com/git/?p=libftdi;a=blob;f=ftdi_eeprom/main.c</li> </ul> <p>Warning</p> <p>Steps were performed on Debian-like installation (Pop!_OS 21.10)</p> <p>This workflow has worked for a self-described NON-genuine FTDI FT232RL chip. The other MAY be genuine, but it is also working.</p> <p>Neither of the following FTDI UART adapters are recommended. Purchasing both chips was an error (only 1 intended). However, having two (potentially non-genuine) FTDI UART adapters helped to create these instructions.</p> <ul> <li> <p>Possibly genuine, but working regardless, (DSD TECH) FTDI</p> </li> <li> <p>Not genuine (HiLetGo) FTDI</p> </li> </ul> <p>Warning</p> <p>The HiLetGo UART adapter comes with a USB MINI female connector and necessitates another adapter/cable for interfacing with the Pi.</p> <ol> <li> Get info from FTDI <ul> <li>Plug the FTDI into a USB port on your Linux device and run <code>lsusb</code> to verify that the device is found <pre><code>lsusb\n</code></pre></li> <li>Ensure the device is recognized as FTDI <pre><code>sudo lshw | grep -B 10 ftdi\n</code></pre></li> <li>Record hardware information (not sure if needed, but was saved to prevent overwriting critical data in the EEPROM)</li> </ul> </li> <li> Blacklist ftdi_sio kernel module <ul> <li>The kernel module ==ftdi_sio== is currently enabled (and how you saw the device in the previous step). We need to disable this module to read/write to the EEPROM.</li> <li>The following command creates a file to blacklist the ==ftdi_sio== module. <pre><code>echo \"blacklist ftdi_sio\" | sudo tee /etc/modprobe.d/bl-ftdi.conf > /dev/null\n</code></pre></li> </ul> </li> <li> Reboot machine <ul> <li>We need to reboot into an environment without ftdi_sio active. <pre><code>shutdown -r 0\n</code></pre></li> </ul> </li> <li> Install ftdi_eeprom if not already installed <ul> <li>Install ==ftdi_eeprom== with the following command. <pre><code>sudo apt install ftdi_eeprom\n</code></pre></li> </ul> </li> <li> Make a folder to work from and change it to our working directory <pre><code>mkdir ./ftdi_config\ncd ./ftdi_config\n</code></pre> </li> <li> Create a valid FTDI configuration file for ftdi_eeprom consumption <ul> <li>The below command (copy/paste all lines) will create a valid configuration file. Change parameters as required. <pre><code>tee ./ftdi.conf > /dev/null <<EOF\nfilename=eeprom.bin\nvendor_id=0x0403\nproduct_id=0x6001\nmanufacturer=\"FTDI\"\nproduct=\"FT232 Serial (UART)\"\nserial=\"SERIAL\"\nuse_serial=true\nmax_power=500\nself_powered=false\ninvert_txd=true\ninvert_rxd=true\ncha_type=\"UART\"\nEOF\n</code></pre></li> <li>This configuration is trimmed from the example due to size of the EEPROM on the FTDIs used.</li> <li>The example configuration at ==/usr/share/doc/ftdi-eeprom/example.conf== describes possible configuration options for the FTDI and is well-documented.</li> <li>The above configuration worked for the mentioned devices. The ==filename==, ==vendor_id==, ==product_id==, ==invert_txd==, and ==invert_rxd== variables are required. The others might not be, but seemed applicable.</li> <li>If you're using a different FTDI chip than used here, please update that in the above configuration. Ensure that vendor_id and product_id are what was obtained from the output of the initial <code>lsusb</code> command.</li> <li>==max_power==, ==serial==, and ==product== were updated to reflect the output of the initial <code>lshw</code>. These updates may not be required and were done to avoid overwriting anything important. ==cha_type== was updated to ==UART== where both of the devices were originally designated as FIFO.</li> </ul> </li> <li> Test the configuration and read the eeprom initially before flashing <ul> <li>Read the EEPROM with the following command <pre><code>sudo ftdi_eeprom --read-eeprom ./ftdi.conf\n</code></pre></li> <li>If you get an error here, there's something wrong with your configuration. Check that the device is properly identified and try again.</li> </ul> </li> <li> Rename/preserve and review the contents of the binary read from the EEPROM <ul> <li>First, rename the output binary file so we don't overwrite it when we flash (flashing writes the flashed binary to the ==filename== path) <pre><code>mv ./eeprom.bin ./original_eeprom.bin\n</code></pre></li> <li>Then, display the outputs of the binary <pre><code>hexdump -C original_eeprom.bin\n</code></pre></li> <li>You can rename the binary in the configuration file by editing the ==filename== variable. If you can't be bothered to edit the file, rename it as detailed above.</li> </ul> </li> <li> Flash the configuration <ul> <li>Run the following command to flash the EEPROM of the FTDI <pre><code>sudo ftdi_eeprom --flash-eeprom ./ftdi.conf\n</code></pre></li> <li>Optional: compare the flashed configuration to the initial configuration with the below command. If there is no output, the files are the same. You will likely need to re-flash. <pre><code>diff <(xxd original_eeprom.bin) <(xxd eeprom.bin)\n</code></pre></li> <li>Alternatively, you can manually compare the files by running <code>hexdump -C original_eeprom.bin</code> and <code>hexdump -C eeprom.bin</code></li> </ul> </li> <li> Your FTDI should be flashed and working to control the KVM! <ul> <li>Plug it into one of the Pi's USB slots (if not already), and it's good to go.</li> <li>The KVM will sink power from the FTDI (Pi) if Vcc is connected. If Vcc is disconnected, ensure that grounds between the Pi and KVM are tied.</li> </ul> </li> <li> Clean up the ftdi blacklist to reenable the ftdi_sio module <ul> <li>Comment out the line but leave the file with the following command: <pre><code>sudo sed -i 's/blacklist ftdi_sio/#blacklist ftdi_sio/g' /etc/modprobe.d/bl-ftdi.conf\n</code></pre></li> <li>If you'd need to read/flash FTDI EEPROM in the future, you can use the following command (followed by a reboot) to blacklist the ==ftdi_sio== module again. <pre><code>sudo sed -i 's/#blacklist ftdi_sio/blacklist ftdi_sio/g' /etc/modprobe.d/bl-ftdi.conf\n</code></pre></li> <li>If you want to wash your hands of FTDI flashing, then delete the blacklist file with the following command: <pre><code>sudo rm /etc/modprobe.d/bl-ftdi.conf\n</code></pre></li> </ul> </li> <li> Reboot the machine to reset to initial state (with ftdi_sio loaded) <ul> <li>==ftdi_sio== should reload as the driver, and the FTDI should be able to be seen with <code>lshw</code> / <code>dmesg</code> once again. If you tried to run either command while ==ftdi_sio== was blacklisted, you probably would have come up empty.</li> </ul> </li> </ol>"},{"location":"xh_hk4401/#windows-instructions","title":"Windows Instructions","text":"<p>In order to invert the RX/TX signals, you can use ft_prog and set the following settings:</p> <p></p> <p>Once the UART is configured, please fully disconnect it and connect it back to the computer. Relaunch <code>ft_prog</code> and ensure the settings are still set. If they are not, you have a fake FTDI chip.</p>"},{"location":"xh_hk4401/#ftdi-terminal-configuration","title":"FTDI Terminal Configuration","text":"<p>Finally, you will need to connect it to the micro USB port (This it not a normal USB micro port.) like so:</p> Signal Colour FT232 Pin Vbus Red 5v (if you want to power the KVM from the Pi's USB) D- White RX D+ Green TX Gnd Black GND"},{"location":"xh_hk4401/#an-inverter-circuit-the-cheap-way","title":"An inverter circuit - The cheap way","text":"<p>For this you will need:</p> <ul> <li>1x 74HC14</li> <li>1x USB A socket, or sacrificial micro USB cable</li> <li>Optional 1x Diode - If you want to power the KVM from the Raspberry Pi</li> <li>1x 5-pin header</li> <li>5x Female - Female jumper cables</li> </ul> <p></p> <p>Note</p> <p>Please search online for USB pinouts to ensure you connect it properly.</p>"},{"location":"xh_hk4401/#adding-ui-elements-to-control-the-kvm-switch","title":"Adding UI elements to control the KVM switch","text":"<p>The UI can be updated to add buttons to switch between KVM inputs and indicators for which input is currently selected. The instructions below will make these available in the PiKVM UI after clicking the \"GPIO\" menu button in the KVM view.</p> <ol> <li> <p>SSH into PiKVM</p> </li> <li> <p>Enable read-write mode on the sd card via <code>rw</code></p> </li> <li> <p>Edit the <code>/etc/kvmd/override.yaml</code> file and include the following. </p> </li> </ol> Method Device FT-232 <code>/dev/ttyUSB0</code> Inverter <code>/dev/ttyAMA0</code> <pre><code>kvmd:\n gpio:\n drivers:\n hk:\n type: xh_hk4401\n device: /dev/ttyUSB0\n scheme:\n ch0_led:\n driver: hk\n pin: 0\n mode: input\n ch1_led:\n driver: hk\n pin: 1\n mode: input\n ch2_led:\n driver: hk\n pin: 2\n mode: input\n ch3_led:\n driver: hk\n pin: 3\n mode: input\n ch0_button:\n driver: hk\n pin: 0\n mode: output\n switch: false\n ch1_button:\n driver: hk\n pin: 1\n mode: output\n switch: false\n ch2_button:\n driver: hk\n pin: 2\n mode: output\n switch: false\n ch3_button:\n driver: hk\n pin: 3\n mode: output\n switch: false\n view:\n table:\n - [\"#Input 1\", ch0_led, ch0_button]\n - [\"#Input 2\", ch1_led, ch1_button]\n - [\"#Input 3\", ch2_led, ch2_button]\n - [\"#Input 4\", ch3_led, ch3_button]\n</code></pre> <ol> <li> <p>Return to read-only mode for the sd card via <code>ro</code></p> </li> <li> <p>Restart the kvmd service: <code>systemctl restart kvmd</code></p> </li> </ol>"},{"location":"xh_hk4401/#switching-between-hosts-in-the-ui","title":"Switching between hosts in the UI","text":"<p>To switch between hosts, enter the KVM UI and click the \"GPIO\" menu. You should see 4 inputs, one of which will have a green circle indicating it is currently selected. Click the other inputs to change the selected host.</p> <p>Please review this latest issue for an update to the existing instructions</p>"},{"location":"blog/","title":"Blog","text":""},{"location":"blog/#blog","title":"Blog","text":"<p>Welcome to the PiKVM Blog. Here you'll find updates, tutorials, release notes, and insights into KVM-over-IP development.</p>"},{"location":"blog/2020/06/01/kvmd-1-65-vnc-improvements-and-new-api/","title":"KVMD 1.65: VNC improvements and new API","text":"<p>What time is it? Release time! Meet the new version of KVMD: 1.65</p> <ul> <li> <p>If you haven't updated to previous intermediate builds, this release will provide many VNC improvements: for example, you can now insert text from the client to the server. In addition, we fixed an annoying bug related to interrupting the broadcast when it is impossible to resume it without restarting the server.</p> </li> <li> <p>A new API was added for inserting text with the ability to select the keyboard layout of the target computer. For example: <code>curl -k -X POST -H 'Content-Type: text/plain' -H 'X-KVMD-User: admin' -H 'X-KVMD-Passwd: admin' --data \"some text\" https://pikvm/api/hid/print?keymap=en-us</code>. To get a list of supported layouts, use <code>/api/hid/keymaps</code>. You can change the default layout in the settings using <code>/etc/kvmd/override.yaml</code> like this:</p> </li> </ul> <pre><code>kvmd:\n hid:\n keymap: /usr/share/kvmd/keymaps/en-gb\n</code></pre> <p>This does not currently affect the virtual keyboard in the web interface, but this issue will be resolved in the future. Also please note that language switching is not supported yet.</p> <ul> <li> <p>Extended API for getting screenshots and previewing screenshots: /api/streamer/snapshot. The last screenshot can be saved in the memory of the KVM. Unfortunately, we have not yet reached the stage of drawing up detailed documentation, so you can find the full list of parameters in the sources: https://github.com/pikvm/kvmd/blob/master/kvmd/apps/kvmd/api/streamer.py#L57</p> </li> <li> <p>A large refactoring of internal libraries has been carried out, so that now it is easier to add an alternative protocol for communication with KVM, such as RDP.</p> </li> <li> <p>Work has been carried out to improve security. No vulnerabilities were found in the process, but the added additional checks will help me avoid them in the future.</p> </li> </ul> <p>And this is the first release in which I included a list of all those who decided to support the Pi-KVM project. Just as I promised. Thank you again to all these kind people. You make the world of open source a better place and help me survive \ud83d\ude04</p> <p>To update use <code>rw; pacman -Syu; reboot</code>. If pacman will report a problem with kernel dependencies, you will need to add them to <code>IgnorePkg</code> in <code>/etc/pacman.conf</code>. Find the IgnorePkg string, uncomment it, and add two packages that pacman swore at, like <code>IgnorePkg = linux-raspberrypi linux-raspberrypi-headers</code> for zero or <code>IgnorePkg = linux-raspberrypi4 linux-raspberrypi4-headers</code>. After that re-run <code>pacman -Syu</code> again and reboot.</p>"},{"location":"blog/2020/06/08/kvmd-1-67-numpad-support/","title":"KVMD 1.67: NumPad support","text":"<p>We added NumPad support, including for configurations with Arduino HID.</p> <p>The Arduino firmware is backward compatible so nothing will break if you don't update it, but it's still worth rewiring your device. You can find out how to do this in the user's guide: https://github.com/pikvm/pikvm. </p> <p>KVM on the basis of the ZeroW parameter and RPi4 will receive support NumPad once after upgrading and rebooting.NumPad also works in VNC, but the keys are not represented in the web interface, because there is no space for them now. I'm saving this issue for the future when I'm improving the UI.</p> <p>For Arduino HID, communication logging over the serial port has been reworked, so that the log shows fewer unimportant connection errors. The logic there is quite complex, and although I have checked everything ten times, please let me know if there are any problems with the Arduino.</p> <p>IPMI and VNC logs are made slightly more readable. The IPMI log shows the IP address of the client from which the request was sent.</p> <p>This release also includes improvements to the About window of the web interface, which now shows more information about the system.</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre> <p>If you have problems installing packages, see the previous news.</p> <p>PS: The situation with the new kernel has become a little clearer. Another bug that I found has been fixed, so there is a chance for a quick system update. In the meantime, we'll continue enjoying the stability of the 4.x branch </p>"},{"location":"blog/2020/06/20/kvmd-1-71-vnc-improvements/","title":"KVMD 1.71: Improved IPMI server","text":"<p>The new version comes with two improvements.</p> <p>First off, we improved the IPMI server. The <code>ipmiutil health</code> command is now supported.</p> <p>Secondly, in the web interface, you can now record a macro of your keyboard and mouse actions on the server, save it, and play it back.</p> <p>This is convenient if you need to perform a sequence of similar actions. The downloaded macro has a convenient json format, so you can independently write scripts with macros in any convenient language to play them remotely.</p> <p>For example, this is a Python script that plays a macro on the specified PiKVM.</p>"},{"location":"blog/2020/07/17/kvmd-1-75-hardware-health-monitoring/","title":"KVMD 1.75: Hardware health monitoring","text":"<p>Today's big release KVMD 1.75 includes several important features.</p> <p>1) Hardware health monitoring. If your Pi-KVM suffers from overheating or lack of power, you will see the corresponding icons and messages in the interface. Don't ignore them! The problems, if any, are not caused by the update, they have always been there, but you have not seen them before, because they were hidden in the kernel logs.</p> <p>2) Partially fixed an issue with the jumping stream quality slider in the Web UI. This is sometimes found on FireFox. The slider still jumps, but it doesn't lose your settings.</p> <p>3) Hand-written HTML has finally been eradicated in favor of Pug templates (here is one example. Future commiters will find it easier to live.</p> <p>4) Reworked streamer settings\u2014preparing for official support of the USB-HDMI dongle. Since it does not know how to adjust the stream quality and determine resolutions, the corresponding submenus will be and added to the Web UI.</p> <p>5) Fixed a bug that caused the mouse to work incorrectly on the Arduino HID. Update the firmware (see https://github.com/pikvm/pikvm).</p> <p>6) Added a handler for the Power key, which is sometimes found on the keyboard. There is no such button in the interface (yet?) it is not necessary, but if necessary, you can call it via the websocket API.</p> <p></p>"},{"location":"blog/2020/07/23/kvmd-1-78-vnc-improvements/","title":"KVMD 1.78: VNC improvements","text":"<p>Two important VNC improvements: client connections that have hung up are now terminated correctly using <code>TCP_KEEPALIVE</code>; applying the <code>TCP_NODELA</code>Y parameter slightly improved responsiveness.</p> <ul> <li> <p>Improved compatibility with FireFox.</p> </li> <li> <p>Minor fixes and codebase cleanup.</p> </li> </ul> <p>This release also updated the list of project sponsors, who donated via Patreon (https://patreon.com/pikvm) or PayPal (https://www.paypal.me/mdevaev). The names of these good people are forever immortalized on the project page and in the web interface in the About window.</p> <p>Thanks to them, I was able to buy a couple of new devices, support for which will appear in one of the next releases of Pi-KVM, and also bought food for my cat!</p>"},{"location":"blog/2020/07/26/kvmd-1-82-hdmi-usb-dongle-support/","title":"KVMD 1.82: HDMI-USB dongle support","text":"<p>The main change is to add support for an HDMI-USB dongle out of the box.</p> <p>For the dongle, the quality settings option was removed from the interface (does not supported by the device) and dropdown was added with manual resolution selection.</p> <p>The best way to use a dongle is to rebuild the operating system with <code>PLATFORM=v2-hdmiusb</code>. This way you will get a configuration that can be easily updated. The use of HDMI-CSI bridge and USB dongle is also available for RPi and RPi3 (with Arduino HID).</p> <p>Please note that the video capture device is linked to a strictly defined USB port. This is necessary so that the OS does not confuse the USB device with something else.</p> <p>Check the updated instructions.</p> <p></p>"},{"location":"blog/2020/07/31/kvmd-1-83-security-fix-for-the-v2-platform/","title":"KVMD 1.83: Security fix for the V2 platform","text":"<p>After a little discussion, I decided to disable OTG Serial Console for security reasons.</p> <p>The option <code>otg.acm.enabled</code> now is <code>false</code> by default. Additionally, the new OS build environment does not perform the steps for setting up the console.</p> <p>It is important to note that if you set a strong password on your Pi-KVM, this problem is not so significant. Attackers will not be able to exploit it from the outside. However, I want to provide the most secure default settings. I'm sorry about this mess. This feature was very useful for development and users of ZeroW devices that don't have Ethernet, but it's not good enough for general installations.</p> <ul> <li> <p>To disable this feature permanently on older Pi-KVMs, follow the instructions above (the <code>override.yaml</code> will not need to be edited after KVMD is updated).</p> </li> <li> <p>If you have an old Pi-KVM installation and you want to continue using this feature, use <code>override.yaml</code> and set option <code>otg.acm.enabled</code> to <code>true</code>.</p> </li> <li> <p>To enable this feature for the v2 platform again in the build environment, add to the <code>config.mk</code> this line: <code>STAGES ?= __init__ os pikvm-repo watchdog ro no-audit pikvm pikvm-otg-console ssh-keygen __cleanup__</code></p> </li> </ul> <p>As a new feature, you can disable VNC TLS if you need compatibility with strange VNC clients. Use <code>/etc/kvmd/override.yaml</code> for this (remove {} before):</p> <pre><code>vnc:\n server:\n tls:\n ciphers: \"\"\n</code></pre> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2020/07/31/security-note-for-v2/","title":"Security note for v2","text":"<p>After installation, Pi-KVM will be available via USB OTG from the managed server via the virtual serial console port.</p> <p>This is very helpful if SSH is unavailable (and you don't have a UART cable), so you can login to the device using something like mingetty or PuTTY and find out what's wrong. The login is protected by the same password that is used for the root login. In some cases (if different networks are used for servers and KVM for security reasons), you may want to disable this feature. To do this:</p> <ul> <li>Run rw.</li> <li>Edit file /etc/securetty and remove line ttyGS0.</li> <li>Edit file /etc/kvmd/override.yaml and add these lines (remove {} before):</li> </ul> <pre><code>otg:\n acm:\n enabled: false\n</code></pre> <ul> <li>Run:</li> </ul> <pre><code>[root@pikvm ~]# systemctl enable getty@ttyGS0.service\n[root@pikvm ~]# rm -rf /etc/systemd/system/getty@ttyGS0.service.d\n[root@pikvm ~]# reboot\n</code></pre> <p>This setting is enabled by default so that you are not left alone with an unmanaged device if it does not receive an address on the network for some reason\u2014for example, if you choose a Wi-Fi connection.</p> <p>If you have a reasonable argument for disabling default, I will be happy to hear it. </p>"},{"location":"blog/2020/08/02/ready-made-images-for-raspberry-pi4/","title":"Ready-made images for Raspberry Pi4","text":"<p>The big update! Now we provide the ready-made images for Raspberry Pi 4. You no longer need to build OS manually!</p> <p>You can flash the Pi-KVM OS to SD card under Linux, Mac, and Windows using the graphical installer.</p> <p>Downloads are here: https://pikvm.org/download/.</p> <p>The manual is here: https://docs.pikvm.org/flashing_os/.</p> <p>Oh, and as you can see, now we have a small website: https://pikvm.org/. I would appreciate it if you share this link with your colleagues or friends in social networks.</p>"},{"location":"blog/2020/08/07/kvmd-1-86-ps2-keyboards-support/","title":"KVMD 1.86: PS/2 keyboards support","text":"<p>Great news for fans of retro computers and tech priests. Now Pi-KVM supports PS/2 keyboard. </p> <p>This is useful for older hardware KVM switches and industrial computers. It is very simple to use, I wrote a small guide: https://github.com/pikvm/pikvm/blob/master/pages/arduino_hid.md</p> <p>Over the past few days, many people have supported my work on Pi-KVM, and I am very grateful to them. The names of all sponsors are included in the documentation and in the \"About\" dialog window in the Pi-KVM interface.</p> <p>PS: Mouse jiggler was not included in this release due to the fact that there is still some logic improvement required, and I decided that it is better to release the PS/2 functionality separately than to stall for time. This will be included in the next release.</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2020/08/13/kvmd-1-88-tailscale-support/","title":"KVMD 1.88: Tailscale support","text":"<p>We added Tailscale to the OS repository for easy access to KVM from an external network via VPN. Updated documentation is here.</p> <p>For very old computers a new mixed Arduino HID mode has been added: PS/2 keyboard + USB mouse. This is a great alternative to the PS/2 keyboard only mode that was added earlier.</p> <p>All new project supporters are added to the thank you list in the About dialog in Pi-KVM and to the github. Thanks again! </p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2020/08/17/kvmd-1-90-closing-the-stream-window-in-the-web-ui/","title":"KVMD 1.90: Closing the stream window in the web UI","text":"<p>One small, but very important feature. Now you can close the stream window in the web interface.</p> <p>Two things will happen: the browser will stop recieving the video stream, reducing traffic consumption, and the streamer on the Pi-KVM side will still work, so when you open the window again, the video stream will be restored.</p> <p>This is useful if you want to upload an image to mass storage while all the traffic goes to the video. This is especially useful for the ZeroW because of the weakness of it. Note that changing the screen resolution will raise a closed window.</p> <p>This is a feature that will be removed later along with the stream size slider.</p> <p>We also introduced various minor fixes. Don't forget to clean the browser cache after upgrading:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2020/08/19/kvmd-1-92-support-for-mouse-buttons-4-and-5/","title":"KVMD 1.92: Support for mouse buttons 4/5","text":"<p>This release brings support for mouse buttons 4 and 5 (back/forward) in the web interface for all Pi-KVM platforms.</p> <p>If you are using an Arduino HID, then you need to update the firmware to use the additional buttons. However, if you do not update the firmware, nothing terrible will happen: the Protocol is backward compatible, and Arduino will simply ignore the new buttons.</p> <ul> <li> <p>Note that these buttons will not work in VNC, since the RFB protocol does not support them by design.</p> </li> <li> <p>Fixed race condition on HID reset.</p> </li> </ul> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2020/08/21/kvmd-1-98-ustreamer-1-22/","title":"KVMD 1.93 & uStreamer 1.22","text":"<p>This is a double release of KVMD and uStreamer with improvements and fixes.</p> <p>KVMD:</p> <ul> <li> <p>Improved error message in login window.</p> </li> <li> <p>Added HTTP API for HID. For example, press and release the Shift key: </p> </li> </ul> <pre><code>curl -k -XPOST -HX-KVMD-User:admin -HX-KVMD-Passwd:admin 'https://kvm/api/hid/events/send_key?key=ShiftLeft'`\n</code></pre> <p>uStreamer:</p> <ul> <li> <p>Added timeout to vcos semaphore to prevent unexpected hanging of the OMX encoder (this should not happen about ever, but it is better to be safe).</p> </li> <li> <p>Fixed fallback to the CPU encoder when the OMX fails.</p> </li> <li> <p>Improved compatibility with some USB 3.0 video capture devices that may produce incorrect frames. The minimum frame size for encoding is set to 128 bytes.</p> </li> <li> <p>Added options to flip image and accept some color effects provided by webcams.</p> </li> </ul> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2020/08/31/kvmd-1-98-technical-preview-for-gpio/","title":"KVMD 1.98: Technical preview for GPIO","text":"<p>I've been working on a new big important feature: the ability to use custom GPIO pins for any purpose, such as connecting sensors or relays.</p> <p>This release is technical preview (but stable ofc) so that you can try out the features that will then be introduced into production.</p> <ul> <li> <p>In this release the GPIO API was added. Now you can configure any number of switches, leds and buttons connected to Pi-KVM and act with it using API: \u2060<code>#chat\u2060</code>. In one of the next releases, these switches will be available in the web interface and I will write the documentation.</p> </li> <li> <p>Added HTTP export handle for the Prometheus system to monitor the pi's and server's state: <code>/api/export/prometheus/metrics</code> with basic auth.</p> </li> <li> <p>Added support for HTTP header <code>Authorization: Basic ...</code> to support basic auth for Prometheus (and other monitoring systems).</p> </li> </ul> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2020/09/03/pikvm-now-available-on-rpi-1/","title":"Pi-KVM is now available on Raspberry Pi 1","text":"<p>In the last release, I added the ability to use this board. This is still unofficial and not reflected in the documentation, but you can already build the system using the build environment if you use the <code>BOARD=rpi</code> and <code>PLATFORM=v0-hdmi</code> or <code>v0-hdmiusb</code> parameters.</p> <p>At the moment, you can only use the A or B board. In B+, the network card does not working because of some glitches related to the new kernel (after all, this is very legacy hardware).</p> <p>To emulate the keyboard and mouse, you will need an Arduino HID, like for rpi2 or rpi3. In addition, the USB port binding for the HDMI dongle is disabled for rpi1.</p>"},{"location":"blog/2020/09/11/kvmd-1-100-gpio-and-usb-relays/","title":"KVMD 1.100: GPIO and USB relays","text":"<p>This release introduces a feature that I have been working on for a long time and that will significantly expand the functionality of Pi-KVM: the ability to use GPIO and USB relays.</p> <p>Now you can connect any number of relays and configure GPIO to control anything using the convenient customizable menu in the Pi-KVM interface. If you wanted to make a smart server power switch, or control a multiport HDMI switch via the menu - now you have all the tools to do it: https://docs.pikvm.org/gpio/.</p> <p>Some other features:</p> <ul> <li> <p>The API for integration with the Prometheus monitoring system has been finally stabilized and documented. By the way, you can get data about the status of GPIO ports in it: https://docs.pikvm.org/prometheus/.</p> </li> <li> <p>KVMD is now compatible with Python 3.7, allowing enthusiasts to create custom builds for other operating systems.</p> </li> <li> <p>Looped playback is now available for user action macros in the web interface.</p> </li> <li> <p>Fixed a minor Nginx issue that could cause the Could not build optimal types_hash message in the logs. You will probably have to look at the diff between the <code>/etc/kvmd/nginx/nginx.conf</code> and <code>/etc/kvmd/nginx/nginc.conf.pacnew</code> files and make the appropriate changes to the first one, then manually delete the second one. But if you don't do any of this, it's not a big deal, it won't affect the functionality of the system.</p> </li> <li> <p>New images are available in the archive: https://pikvm.org/download/.</p> </li> </ul> <p>Thank you to everyone who helped with the documentation and testing of new features. In addition, this release includes an updated list of thanks to those who donated to the project.</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2020/09/17/kvmd-1-101-improvement-for-the-hdmi-usb-dongle/","title":"KVMD 1.101: Improvement for the HDMI USB dongle","text":"<p>The main change in this release concerns the internals of Pi-KVM.</p> <p>About a year ago, the Linux kernel interface, which is used by most applications on the Raspberry Pi that work with GPIO, was deprecated (sysfs/gpiomem). This was replaced by the character device <code>/dev/gpiochipX</code>.</p> <p>It is stated that the old interface will be removed in 2020, that is, very soon. Existing GPIO libraries for Python and C will also stop working: RPi.GPIO, pigpio, wiringpi and other. </p> <p>It seems that the coming year will be fun for many projects that use the old library. For this reason, I got rid of RPi.GPIO and now KVMD uses libgpiod, a library for working with GPIO recommended and supported by kernel developers.</p> <p>GPIO changes will not affect those who simply use this to control the ATX or control the KVM switch. However, those who use custom GPIO in Pi-KVM should know that it is no longer possible to save the pin state for GPIO (this is the kernel limitation) using option <code>initial=null</code>. In other words, when KVMD is restarted, the state of the relay connected to the GPIO will be reset to logic 0.</p> <p>With the exception of this, the new library allowed KVMD to get rid of active GPIO state polling cycles, as well as crutches around kvmd-cleanup (does anyone even know what this is lol?). I have thoroughly tested this release and everything should be OK. However, if you notice any oddities, please let me know.</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2020/09/18/kvmd-1-102-improvement-for-the-hdmi-usb-dongle/","title":"KVMD 1.102: Improvement for the HDMI USB dongle","text":"<p>The new version features further work on libgpiod and an improvement for the HDMI USB dongle.</p> <ul> <li>Continue working with libgpiod. It turned out that I didn't use the correct symbolic names for the IO ports. This does not affect the operation, but the kernel warns that it does not like it. Fixed in the this version. If you are interested in more details, then we are talking about the fact that libgpiod allows you to view active ports using the gpioinfo command:</li> </ul> <pre><code>gpiochip0 - 54 lines:\n... \n line 20: \"GPIO20\" unused input active-high \n line 21: \"GPIO21\" unused input active-high \n line 22: \"GPIO22\" \"kvmd::atx-gpio::leds\" input active-high [used]\n line 23: \"GPIO23\" \"kvmd::atx-gpio::power_switch\" output active-high [used]\n line 24: \"GPIO24\" \"kvmd::atx-gpio::leds\" input active-high [used]\n...\n</code></pre> <p>I used names like kvmd/foo/bar, but the correct names are <code>kvmd::foo::bar</code>.</p> <ul> <li>Slight improvement for the HDMI USB dongle. Now you can always keep the stream active, regardless of whether you have a browser or VNC open. This may be necessary because the server recognizes the dongle only when it is actually streaming. If not, the video card does not see the dongle. I'm not sure if this is the case with all dongles, but the one I have behaves exactly like this.</li> </ul> <p>To include the everlasting stream use file <code>/etc/kvmd/override.yaml</code>:</p> <pre><code>kvmd:\n streamer:\n forever: true\n</code></pre> <p>To reduce power consumption and CPU usage, you can use the <code>--slowdown</code> option for ustremaer (rewrite the cmd section from <code>main.yaml</code> and add a line with the option).</p>"},{"location":"blog/2020/09/22/we-need-help-testing-ustreamer/","title":"We need help testing uStreamer","text":"<p>I need the community's help in testing the new version of ustreamer (the video server of Pi-KVM).</p> <p>I found that some drivers for capture devices and cameras contain a bug that causes video buffers that are already used by the application to be given to it twice from the queue (TL;DR kernel magic). This can potentially corrupt memory, at least the part of it where the image is contained.</p> <p>I investigated this issue and added code to ustreamer that prevents access to such a memory area. Now I want to know if our video capture devices (CSI bridge and USB dongle) are really affected by this problem. And if so, how often does this occur?</p> <p>Therefore, I need the maximum cooperation of all users. You don't need to conduct comprehensive testing, just need to check your case. If you find the time to help me, you need to install ustreamer from source. This is very easy to do.</p> <pre><code># rw\n# mv /usr/bin/ustremer /usr/local/bin/ustreamer.bak\n# git clone https://github.com/pikvm/ustreamer\n# cd ustreamer\n# make -j5 WITH_OMX=1\n# make PREFIX=/usr install\n# ro\n</code></pre> <p>After that reboot Pi-KVM (or just restart stream using web ui system menu).</p> <p>If a memory problem occurs, ustreamer will quickly restart the video. In other words, you will see the NO SIGNAL message for a couple of seconds (or a gray screen). This situation will be reflected in the log with a message V4L2 error: grabbed device buffer is already used. It is useful to check the presence of this entry in the log every few hours using the command journalctl -u kvmd | grep 'grabbed device'.</p> <p>Depending on whether this problem occurs and how often, I will look for some other solution for it, or keep the current one if it doing well.</p> <p>If the problem suddenly appears and prevents you from working, please let me know and restore the old ustreamer: mv /usr/local/bin/ustreamer.bak /usr/bin/ustreamer.</p> <p>Thank you to everyone who responds!</p>"},{"location":"blog/2020/09/24/ustreamer-2-0-memory-protection/","title":"uStreamer 2.0: Memory protection","text":"<p>Given the previous changes, I believe that there are already enough changes for version 2.0 :)</p> <ul> <li> <p>wiringPi replaced to libgpiod (reasons: \u2060news\u2060)</p> </li> <li> <p>Added protection from memory corruption on usage of buggy webcam drivers (details)</p> </li> <li> <p>Disabled cross-domain requests by default for security reasons (details)</p> </li> </ul> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2020/10/04/kvmd-2-0-redfish-support-hid-driver-improvements/","title":"KVMD 2.0: Redfish support and HID driver improvements","text":"<p>This is a major new release with important improvements.</p> <p>Let's take a look at the changes:</p> <ul> <li> <p>The first and most important change is updating the kernel to 5.4.69. Fixed the critical Linux bug with USB that could cause the Pi to reboot when using the keyboard and mouse on a rebooting host. I spent a few days debugging this problem and now it is solved in the Raspbian upstream.</p> </li> <li> <p>The kernel update is also unlocked for ZeroW boards. The new kernel fixed an old bug that caused the kernel to hang on CSI HDMI at Zero. Yea, another kernel bug that I was directly involved in solving.</p> </li> <li> <p>On the Pi-KVM side, the HID driver has been significantly improved, and now it clearly detects the USB state: the yellow color in web ui clearly shows when the cable is disconnected. Also added support for the NonUs and AltGr keys, fixed Win key in VNC.</p> </li> <li> <p>Implemented basic support for Redfish as an improved and secure IPMI replacement for enterprise use (see here for documentation. Redfish requires no additional configuration and is available directly in KVMD. It uses the same authorization mechanism as the rest of the Pi-KVM. The only handle available /redfish/v1 without authorization produces a small static document for service discovery required by standard.</p> </li> <li> <p>Added the ability to request confirmation for actions on custom GPIO buttons and switches (see View rules).</p> </li> <li> <p>Now you can create USB Ethernet for direct communication between the Pi-KVM and the server (see here for more information). This release does not include a tool for address configuration and firewall, expect soon.</p> </li> <li> <p>Improved the Web Socket API which no longer makes unnecessary broadcasts when connecting new clients. This is now convenient to use for getting the entire state of the Pi-KVM by the batch.</p> </li> <li> <p>Config sections <code>otg/msd</code>, <code>otg/acm</code> and <code>otg/drives</code> were moved to <code>otg/devices/msd</code>, <code>otg/devices/serial</code> and <code>otg/devices/drives</code>. Of course, the old config will continue to work.</p> </li> <li> <p>... And many minor changes.</p> </li> </ul> <p>Note: Before upgrading ZeroW, you will probably need to remove the <code>IgnorePkg = linux-raspberrypi and linux-raspberrypi-headers</code> parameter from <code>/etc/pacman.conf</code>, if you added it earlier.</p> <p>To update, follow:</p> <pre><code>rw\npacman -Syu\n</code></pre> <p>If you changed the file <code>/etc/kvmd/override.yaml</code>, you will see a new file: <code>/etc/kvmd/override.yaml.pacnew</code>. You can simply delete it or merge its contents with your own configuration. The new file contains commented-out usage examples and no longer contains (and requires) the <code>{}</code> row for an empty config.</p> <p>After all perform reboot. </p>"},{"location":"blog/2020/10/05/another-test-request-for-v2-users-of-rpi4-and-zerow/","title":"Another test request for v2 users of RPi4 and ZeroW","text":"<p>I found a way to improve USB HID/Mass Storage compatibility with some motherboards. I would like to ask you to check if there are any problems because of this. If successful, if you didn't have MSD working, it may work after this change.</p> <p>Please check this on your configurations: whether HID/MSD worked before, whether it works after the patch. I will be happy to hear about any changes (both positive and negative).</p> <p>Run on Pi-KVM:</p> <pre><code>rw\nsed -i -e 's|^dtoverlay=dwc2$|dtoverlay=dwc2,dr_mode=peripheral|g' /boot/config.txt\nreboot\n</code></pre> <p>This can be easily undone if problems occur.</p>"},{"location":"blog/2020/10/08/kvmd-2-1-bug-fixes/","title":"KVMD 2.1: Bug fixes","text":"<p>This is mainly a bugfix release.</p> <ul> <li> <p>Fixed incorrect keys mapping in VNC. Also implemented QEMU Extended Key Events protocol which provides messages with hardware keycodes for VNC. This input method is preferred, and clients which can use it (yea-yea, I'm advertising TigerVNC again) will not have any problems with the layouts. Configuring keymap in override.yaml also becomes unnecessary in this case.</p> </li> <li> <p>For v2 builds (RPi and ZeroW) the peripheral device mode for the USB-gadget controller is forced by default. This improves compatibility with some strange motherboards. Testing has not revealed any negative effects, but if something goes wrong, let me know.</p> </li> <li> <p>Fixed GPIO switches in Web UI menu for the case when pulsing is disabled.</p> </li> </ul> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2020/10/17/kvmd-2-2-improved-hid-modules-for-arduino-and-otg/","title":"KVMD 2.2: Improved HID modules for Arduino and OTG","text":"<p>We have made several important improvements in this release.</p> <ul> <li> <p>Improved HID modules for Arduino and OTG. Now, if the server is disabled, the event queue will not grow, and irrelevant events (such as keystrokes for a disabled server) will be deleted. </p> </li> <li> <p>Added an experimental service for configuring the USB network (issuing addresses to the server, firewall, and so on): kvmd-otgnet. Now you can up the FTP server on Pi-KVM and share files with the server using it.</p> </li> <li> <p>For all KVMD daemons the startup method has been changed: the <code>--run</code> option is required to prevent accidental startup. Updated systemd services. Migration will be transparent for users.</p> </li> <li> <p>Fixed a very rare VNC bug that could cause the server to stop transmitting an image and require a restart.</p> </li> <li> <p>Minor UI improvements (more compact menubar, etc).</p> </li> </ul> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2020/10/31/kvmd-2-3-workaround-for-dhcpd-crashes/","title":"KVMD 2.3: Workaround for dhcpcd crashes","text":"<p>A problem was found in the distro due to which the new dhcpcd (client) crashes when trying to get a Wi-Fi address (it's not me!).</p> <p>So that you don't get a broken KVM after random update, in this release I forced the use of dhclient instead of dhcpcd. You should not notice any changes or problems. If there is anything strange, please let me know.</p> <p>Now about pleasant things.</p> <ul> <li> <p>Added support for IPMI Serial-over-LAN. Now you can use ipmitool to access your server's console on the hardware COM port, see here for information.</p> </li> <li> <p>Added the ability to edit streamer options without having to copy the entire list to /etc/kvmd/override.yaml. Now you can write something like:</p> </li> </ul> <pre><code>kvmd:\n streamer:\n cmd_append: [--slowdown]\n</code></pre> <p>The other features I'm currently working on are in experimental mode. Due to the urgency of the release, I didn't have time to finish it. But I will soon :)</p>"},{"location":"blog/2020/11/11/kvmd-2-4-relative-mouse-bluetooth/","title":"KVMD 2.4: The Relative mouse & Bluetooth","text":"<p>This release added a great new feature that will please those who did not work the mouse in the BIOS/UEFI.</p> <p>Previously, Pi-KVM only emulated absolute mouse mode, and some UEFIs didn't understand this. Now you can enable relative mouse mode. In this mode, the browser will completely capture your cursor (until you press <code>Esc</code>) and transmit all events to the server.</p> <p>Testing has shown that on all UEFI in which the PI-KVM mouse did not work before, when the relative mode is enabled, the cursor works. This is a significant breakthrough in improving compatibility with various hardware. See here for details.</p> <p>A very interesting feature has appeared: now Pi-KVM can emulate Bluetooth keyboard & mouse. The usecases of this may be specific, but I'm sure there will be a use for it. For example, you can control the cursor and keyboard of an iPad or other pieces. Bluetooth mouse works in relative mode, see here.</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2020/11/27/ustreamer-2-2-better-video-performance/","title":"uStreamer 2.2: Better video performance","text":"<p>This is a bugfix release, albeit an important one.</p> <p>We fixed an issue where video performance could degrade due to NTP system clock tweaking. A small but useful fix.</p> <p>PS: If you missed the KVMD updates, I'm currently working on improvements to the Arduino HID, which will allow you to switch mouse modes in real time, as well as support for the SPI Protocol instead of UART. This is a very big change, but the work is almost done.</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2020/12/11/kvmd-2-6-completely-rewritten-arduino-hid/","title":"KVMD 2.6: Completely rewritten the Arduino HID subsystem","text":"<p>This is a very big release with a lot of changes, which took me a whole month.</p> <p>Here is what's new:</p> <ul> <li> <p>Completely rewritten the Arduino HID subsystem. Now you can switch between relative and absolute mouse modes directly from the web interface. Arduino HID can be used with both v0 and v2, in which case it provides improved compatibility with strange devices and BIOSes. Some BIOSes don't understand absolute mouse and they need relative mouse: https://github.com/pikvm/pikvm/blob/master/pages/mouse.md</p> </li> <li> <p>Now Arduino HID is compatible with Mac UEFI and is able to provide access to its menu at boot. If you need full Mac UEFI support, use Arduino HID. This is the recommended method.</p> </li> <li> <p>Implemented an alternative way to connect the Arduino HID to the Raspberry using SPI. This is not yet documented and little bit tricky, but this method will free up the UART for other needs.</p> </li> <li> <p>Migrated to Python 3.9. A big task which required patching and rebuilding of many packages.</p> </li> </ul> <pre><code>rw\npacman -Syu\npacman -S tailscale-pikvm\nreboot\n</code></pre> <p>To use the new features of the Arduino HID, you will need to perform a flash. However, if you don't do this, nothing will break, the new KVMD is fully compatible with all older firmware versions. See here for more informaiton.</p>"},{"location":"blog/2020/12/20/some-news-about-v3/","title":"Some news about v3","text":"<p>We have some news about v3. The prototypes are almost ready. Since the last release, they have included several changes and additional features.</p> <p></p> <p>In addition to the ones we announced earlier, we added:</p> <ul> <li> <p>HDMI Audio. Practice has shown that all existing CSI bridges except for the expensive Auvidea B101 model have a hardware circuit error, due to which they are not able to capture sound. Our v3 does not have this drawback. This feature is already implemented in hardware, and the software will be ready a little later. Most likely, we will offer h264 video compression + audio.</p> </li> <li> <p>Built-in fan controller. Since RPi has some cooling issues, we thought it would be great to solve this somehow.</p> </li> <li> <p>Arduino HID with USB and PS/2 keyboard and mouse. The software for PS/2 mouse will be completed later, the hardware is already ready. Also, this thing is necessary to work with Apple UEFI.</p> </li> <li> <p>The board uses only USB-C connectors (standardization!) and fully compatible with the official RPi power supply, which we will recommend for use.</p> </li> </ul> <p>A limited batch of 30 pieces will be sold to commercial customers and some interested parties in this chat. We'll probably sell to the first applicants, but we haven't decided yet. The kit will include: the v3 board, arduino HID board, adapter boards, small fan, and (probably) a 3D-printed case. RPi and power supply will NOT be included.</p> <p>Since this is a trial batch of manual assembly, the cost of one set will be $200-250 (we have not yet calculated exactly). The sale of prototypes should start before the new year. In January, we will start selling production models much cheaper (~$100).</p> <p>PS: Discussing welcome in the \u2060chat!</p>"},{"location":"blog/2021/01/12/ustreamer-3-0-h264-video-recording/","title":"uStreamer 3.0: H264 video recording","text":"<p>Currently, Pi-KVM uses MJPEG for video transmission. This is a simple and widely supported, but not very effective video format. In the near future, it is planned to support H264, and then switch to it as the main one.</p> <p>The H264 implementation is still under development, but right now you can use it to record video from your server. To do this, uStreamer supports simultaneous MJPEG and H264 encoding.</p> <p>See here for more information.</p> <p>We also have some news about Tailscale support.</p> <p>Previously, Tailscale was in its own pikvm repository and contained fixed versions of the startup scripts. Now it was accepted in upstream and the default startup scripts were broken. </p> <p>If you upgrade the system and want to keep Tailscale working, you need to install the tailscale-pikvm package:</p> <pre><code>rw\npacman -Syu\npacman -S tailscale-pikvm\nreboot\n</code></pre>"},{"location":"blog/2021/01/19/implementing-h264-support-for-vnc/","title":"Implementing H264 support for VNC","text":"<p>For those who use VNC and want to reduce the traffic using H264.</p> <p>I want to implement H264 support for VNC, but the problem is that no VNC client supports H264. I'm ready to write a server and I already have a stable H264 encoder, but I need help with the client.</p> <p>I'm going to negotiate with the developers of TigerVNC to work together on this: we will agree on a new protocol, I will implement the server, and they will implement the client. Since this is clearly a low-priority task for them, I suggest that anyone who needs this functionality should chip in for a beer for these guys.</p> <p>If you are willing to participate and want to have H264 in VNC, please report yourself in \u2060h264_vnc_funding with an indication of how much you are willing to donate. Any contribution is important! If we collect an acceptable amount (I think $500 is reasonable), I will notify everyone and you can throw this money on BountySource (a site with rewards for developers).</p> <p>Once again: I'm not asking for myself, but to pay for the work of other people. This is a very large-scale task, and if it is done by several people, everyone will benefit.</p>"},{"location":"blog/2021/02/21/kvmd-2-27-critical-bug-fix/","title":"KVMD 2.27: Critical bug fix","text":"<p>A lot of changes have accumulated since the last announced release. Mostly finally fixed wifi support on Zero and RPi4.</p> <ul> <li> <p>Added new udev rules for USB HDMI for latest RPi4 board revisions</p> </li> <li> <p>Improved handling of VNC frames. It should get a little faster.</p> </li> <li> <p>Added support for VNC X.509 encryption. Now you can use some mobile clients (such as bVNC) to access the Pi-KVM.</p> </li> <li> <p>Now the Arduino HID is rebooted when the KVMD is restarted, this prevents the Arduino from possibly hanging due to the slow build-up of the supply voltage.</p> </li> <li> <p>Changed the default JPEG compression quality on Zero. Now it is 50 (FPS has become higher, the quality remains acceptable).</p> </li> <li> <p>The web interface now allows to upload MSD images with spaces. Some more minor improvements to the web interface. Also it's now available over IPv6.</p> </li> <li> <p>For USB Ethernet (v2 only), we added the ability to configure Pi-KVM as a router for the server, see here.</p> </li> <li> <p>A lot of work has been done to use H.264 with VNC. At the moment, we have registered our new protocol in IANA and are waiting for the applying of patches in TigerVNC and the fixing of some bugs in the kernel related to HDMI and H.264.</p> </li> </ul> <p>To update: </p> <pre><code>rw\npacman -Syy\npacman -S linux-firmware=20210221.b79d239-1\npacman -Su\nreboot\n</code></pre>"},{"location":"blog/2021/03/13/kvmd-2-31-critical-bug-fix/","title":"KVMD 2.31: Critical bug fix","text":"<p>In recent weeks, I have been mainly working on H264 and have achieved significant results \u2060h264_vnc_funding. A critical bug has been fixed in the kernel that prevents the H264 encoder from being enabled by default, so now everyone can try H264 for VNC for v2 and CSI bridge (only).</p> <p>This is not yet the final official implementation, but everything should work well. The work on H264 support in the web interface is far from complete, but it will be implemented.</p> <p>Among other things:</p> <ul> <li>Improved keyboard handling in the web interface on Mac OS.</li> <li>When you close the stream window, the interface now asks for user confirmation.</li> <li>Fixed a build bug for v0 related to disabling UART console.</li> <li>Work has been carried out to standardize the H264 RFB (VNC) protocol. The standard is waiting for confirmation.</li> </ul> <p>To update: </p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2021/04/13/kvmd-2-42-fullscreen-mode-web-ui/","title":"KVMD 2.42: Fullscreen mode in the web UI","text":"<p>Introducing a big update to the web interface!</p> <p>Full-screen mode! It works in all browsers, but most of all-in Chrome/Chromium, where it allows you to capture system keys like Ctrl+W and so on.</p> <p></p><p></p> <p>Other changes:</p> <ul> <li>Changing the size of the stream window using the window corner. No more ugly \"Stream size\" slider!</li> <li>The ability to expand the window to the entire workspace with a single button.</li> <li>Added the ability to manage remote hosts via IPMI from the Web UI menu: view the power status, turn on/off, and so on. See here for details.</li> <li>Work continues on implementing H264. Many components of the system needed to be improved. Not everything is ready yet, but we are one step closer to replacing MJPEG with H264 in the browser.</li> </ul> <p>To update: </p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2021/04/17/kvmd-2-53-web-terminal-in-web-ui-window/","title":"KVMD 2.53: Web terminal in a web UI window","text":"<p>You can now have the web terminal in a window above the video stream if you like. The focus works a little strange, but it is quite functional and even supports changing the size.</p> <p></p> <p>Another recent change is that you can now select the keyboard layout of the target machine in the paste-as-keys menu, so this solves the problem of German, British, and other layouts.</p> <p></p> <p>And a few more changes:</p> <ul> <li>You can disable confirmation in the paste-as-keys menu</li> <li>Full-screen mode now works in Safari on Mac.</li> <li>Some minor UI fixes and improvements.</li> </ul> <p>To update: </p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2021/04/23/kvmd-2-55-arduino-hid-improvements/","title":"KVMD 2.55: Arduino HID imrpovements","text":"<p>This release delivers a significant improvement of the Arduino HID when you control a computer with a MacOS.</p> <p>Now you don't need to spam the Command+R or Option keys on boot to hope to get to the UEFI menu or Recovery mode\u2014just hold down the shortcut on boot, as on a real keyboard, and everything will work.</p> <p>We also improved the behavior of the stream window: now it will not try to establish a connection several times due to a race on a slow channel, but works more stably. This is part of the work on future H.264 support\u2014cleaning the ancient Augean stables.</p> <p>To update: </p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2021/05/09/kvmd-2-65-ezcoo-fix-for-usb3/","title":"KVMD 2.65: Ezcoo fix for USB 3.0","text":"<p>If you bought an Ezcoo switch for USB 3.0, then in order for it to work with Pi-KVM, you need to upgrade to the new version and add one option to the config.</p> <p>The fact is that the Ezcoo guys for some reason changed the management protocol. The update adds support for this.</p> <p>Ah, and if you're wondering where the rest of the versions disappeared between release 2.59 and 2.65, then these were some things for the upcoming H.264 support \ud83d\ude42</p> <p>To update: </p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2021/05/20/kvmd-2-71-massive-internal-changes/","title":"KVMD 2.71: Massive internal changes","text":"<p>This is a very important release. In addition to new features and fixes, a large number of internal changes have been made for the upcoming H264/WebRTC support.</p> <p>As usual, I tested everything very carefully, but anyway. If you notice anything strange (for example, with the stream), let me know.</p> <ul> <li> <p>Added module for new managed KVM switch Tesmart (as an Ezcoo alternative): https://github.com/pikvm/pikvm/blob/master/pages/tesmart.md. It can be used in a same way from Web UI.</p> </li> <li> <p>Fixed the Bluetooth HID emulation module.</p> </li> <li> <p>Improved text insertion via the Web UI: typographic quotes are now replaced with ASCII quotes. Many sites where scripts can be copied from like to break quotes, so I decided to make life a little easier for sysadmins.</p> </li> <li> <p>Due to a bug in systemd/udev, port binding for USB HDMI is disabled. This is temporary for now, but I'm considering getting rid of it altogether, because no one seems to be using multiple video devices on the Pi-KVM.</p> </li> <li> <p>Redesigned the System menu in the Web UI to make it more compact, as due to H264 and v3 there will be a lot of new settings.</p> </li> </ul> <p>To update: </p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2021/05/30/store-update/","title":"Store update","text":"<p>There is good and bad news about our store.</p> <p>A couple of days ago, we tried to make test sales and faced a huge number of refusals when making payments. In most cases, US and European banks consider the payment to Russia to be a fraudulent operation. There's nothing we can do about it. Well, it's probably well deserved, given the stories about Russian hackers.</p> <p>Obviously, we can't sell our devices under these conditions, so we decided to sell most of the batch to wholesale suppliers in the US. These are two good stores that sell Raspberry Pi and accessories for them. The advantage of this approach is that it will be easier for you to buy it, if you want to add some things (Raspberry, memory card, cables, if you don't have one) and you will get delivery faster than from Russia. Minus - it will be a little more expensive.</p> <p>The second batch will be sold through resellers for retail. To companies we will sell directly with deliveries via DHL.</p> <p>So I'm doing customs clearance this week. Most likely, this will be delayed for another three weeks, taking into account the delivery to the reseller. </p>"},{"location":"blog/2021/06/08/kvmd-2-83-uploading-large-images/","title":"KVMD 2.83: Uploading large images","text":"<p>We have improved the behavior of mass storage when uploading large images.</p> <p>Previously, the progress bar could be displayed incorrectly due to the features of different browsers (for example, chrome on some win 10), so now the download progress is calculated on the server side and transmitted to the client.</p> <p>We also recently accelerated the uploading of images to Mass Storage by two to three times.</p> <p>Work continues on the implementation of H264 and WebRTC. Presumably, the release will be within a week.</p> <p>To update: </p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2021/06/10/kvmd-3-0-big-h264-release/","title":"KVMD 3.0: The big H.264 release!","text":"<p>I'm happy to introduce you to a feature I've been working on for the last six months. Now, instead of using bold MJPEG for video, you can use fast WebRTC with H.264.</p> <p>This allows you to significantly reduce traffic consumption and improve the responsiveness of Pi-KVM on bad networks, and all in the regular Web UI! The MJPEG and H.264 modes are left to choose from and you can switch them at any time using the menu.</p> <p>It was a huge job, as I had to understand the intricacies of WebRTC functioning, integrate it with uStreamer, develop a way to automatically configure the WebRTC gateway, and so on.</p> <p>To try the new super video mode, upgrade your system (<code>rw; pacman -Syu; reboot</code>) and read the simple user guide.</p> <p>Please note that right now H.264 is only available for Raspberry Pi 4 with CSI bridge.</p>"},{"location":"blog/2021/07/04/kvmd-3-7-some-v3-news/","title":"KVMD 3.7 + Some V3 news","text":"<p>This release comes with several improvements, we also have some V3 news for you.</p> <ul> <li> <p>Now the video mode is saved in the browser. If you have chosen WebRTC by default, then it will remain the same for this browser.</p> </li> <li> <p>The Yen key in the Japanese keyboard now works.</p> </li> <li> <p>Added a link to the configuration documentation and possible problems with WebRTC (right next to the mode switch).</p> </li> <li> <p>The OS images on the site will be updated in the near future. Now the size of rootfs has been increased from 4 to 6 gigabytes to avoid problems with updates. The size of the partition in old images on already installed OS will not be increased.</p> </li> </ul> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot \n</code></pre> <p>As for the first batch of v3: it was delayed at russian customs. Let's wish health to these wonderful people. I'll deal with it. Btw the second batch is planned for September. There will be no such problems with this since it will be produced in China. </p>"},{"location":"blog/2021/07/10/kvmd-3-8-epic-apple-fix/","title":"KVMD 3.8: The Epic Apple fix!","text":"<p>For a long time, Pi-KVM had several problems related to the mouse and keyboard on Apple. Previously, you could not use the mouse in the boot menu, and recovery mode also required you to connect the mouse, despite the fact that the cursor was functioning. Because of these bugs, it was impossible to fully remotely control your Mac. Now all this is fixed!</p> <ul> <li> <p>For an Intel-based Mac, you can use the Arduino HID to enter different boot menus (Option or Cmd+R). In boot manager, a relative mouse now works, and in recovery mode, both relative and absolute work.</p> </li> <li> <p>For Mac with M1, you can use default OTG HID. You will no longer be shown a screen with an absurd requirement to connect another mouse in recovery mode.</p> </li> </ul> <p>Since this problem was hidden somewhere inside the Apple drivers, I needed to buy a hardware USB protocol analyzer to understand how to get around it (because Mac is a closed source and there is no other way to find out what is happening there). Fixing this cost me almost $1500. So if it will be useful to someone, you can support me with a donation, because developing Pi-KVM software as Open Source is my main and only job.</p> <ul> <li>https://patreon.com/pikvm</li> <li>https://www.paypal.me/mdevaev</li> </ul> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot \n</code></pre> <p>And don't forget reflash your Arduino HID! </p> <p></p>"},{"location":"blog/2021/07/14/kvmd-3-9-paste-as-keys-update/","title":"KVMD 3.9: Paste-as-Keys update","text":"<p>For the Paste-as-Keys function, the state of the confirmation switch and the selected keymap are saved. You asked for it\u2014I did it.</p> <p>Also, after solving the problems with HID on Apple, I sent patches to the upstream HID library. I know of at least one other project for which these problems were a thorn. Let's hope that we will make life easier for people \ud83d\ude42</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot \n</code></pre>"},{"location":"blog/2021/07/17/kvmd-3-11-for-workgroups/","title":"KVMD 3.11 For Workgroups","text":"<p>More new features in this new release.</p> <p>Now Wake-on-LAN can be configured not for one, but for a whole list of hosts. Now you can use this as another method of managing multiple hosts connected to an HDMI switch: https://github.com/pikvm/pikvm/blob/master/pages/wol.md</p> <p>This change required a complete rewrite of the WoL subsystem, which has now become a pseudo-GPIO driver. Your old settings in <code>override.yaml</code> will work and the button for one host is still in the System menu, since I took care of backward compatibility, but the <code>/api/wol</code> handle has been removed, you need to use the GPIO API instead it (if anyone has used it at all).</p> <p>We also made some improvements in the interface. The interval between hotkeys was increased to 100 milliseconds (since 50 was sometimes not enough for reliable operation), the shortcuts menu was separated from the paste menu in preparation for the implementation of custom keyboard shortcuts.</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot \n</code></pre>"},{"location":"blog/2021/08/02/kvmd-3-13-upload-images-by-url-dual-mouse-mode/","title":"KVMD 3.13: Upload images by URL + dual mouse mode","text":"<p>Two new great features!</p> <ul> <li> <p>Now you can tell Pi-KVM to download the image for mass storage from the HTTP(S) URL, and not just upload from your local computer. The new MSD API has also become more convenient if you are a curl guru.</p> </li> <li> <p>For v2/v3/OTG, you will no longer have to choose between relative and absolute mouse, you will be able to use both modes and switch between them without changing the config and reboot. This is very convenient if your BIOS does not understand the absolute mouse and only wants a relative one, while the absolute one is more convenient for everyday work in the OS. This dual mouse mode is disabled by default for compatibility reasons (perhaps, especially buggy bioses may not support two mice at once), to enable it, after updating, add to <code>/etc/kvmd/override.yaml</code>:</p> </li> </ul> <pre><code>kvmd:\n hid:\n mouse_alt:\n device: /dev/kvmd-hid-mouse-alt\n</code></pre> <p>Turn off the relative mode for the mouse in the config if it was enabled earlier. And make sure that you merged files <code>/etc/udev/99-kvmd.rules.pacnew</code> with <code>/etc/udev/99-kvmd.rules</code>. </p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot \n</code></pre>"},{"location":"blog/2021/08/08/big-testing-request/","title":"Big testing request","text":"<p>I have a very important request. We are preparing for a big update that will improve compatibility with BIOS and UEFI on many devices, and I need as many people as possible to check out the new build of the kernel and core packages.</p> <p>How to test:</p> <ol> <li>Switch filesystem to RW-mode using the <code>rw</code> command.</li> <li>Open the <code>/etc/pacman.conf</code> file for editing and go to its end.</li> <li>Change the repository URL like this (add testing component path): <code>Server = https://pikvm.org/repos/testing/rpi4-arm</code>. Don't change the last component (<code>rpi4-arm</code>, <code>zerow-arm</code>, etc).</li> <li>Run <code>pacman -Syu && reboot</code></li> </ol> <p>Please make sure that everything works as usual, I mean video and USB. I am particularly interested in the CSI bridge.</p>"},{"location":"blog/2021/08/17/kvmd-3-18-sensitivity-adjustment-for-relative-mouse/","title":"KVMD 3.18: Sensitivity adjustment for relative mouse","text":"<p>There are several improvements in this release.</p> <ul> <li> <p>The relative mouse now has a sensitivity adjustment. The setting is remembered in the browser.</p> </li> <li> <p>We added a PWM and Servo module for GPIO. Now you can control servos using the GPIO menu.</p> </li> <li> <p>The most important change! We added the absolute mouse compatibility mode for Windows 98 for both OTG and Arduino HID.</p> </li> </ul> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot \n</code></pre>"},{"location":"blog/2021/08/31/kvmd-3-23-keyboard-mouse-wakeup/","title":"KVMD 3.23 + kernel fix: keyboard/mouse wakeup","text":"<p>Previously, when using v2+/OTG on Pi4 and ZeroW, you could not wake up the host if it was in suspend. Now this problem is solved. </p> <p>At the moment, this feature is experimental and disabled by default, since it was implemented blindly without documentation for the USB controller (no one gave it to me lol). It would be great if as many people as possible test it and tell if everything works fine.</p> <p>Although the feature is experimental, the update must be safe.</p> <p>To update you will need our own stable kernel build (if you are using a very old image and have not installed it, in new images it is out of the box):</p> <ol> <li>Check if it is installed: <code>pacman -Q | grep pikvm-os-raspberrypi</code></li> <li>If this command didn't show you anything, install our kernel (\u2060news\u2060)</li> <li>After reboot, make this: <code>rw; pacman -Syu; reboot</code></li> <li>To enable wakeup feature edit <code>/etc/kvmd/override.yaml</code> and add this:</li> </ol> <p></p><pre><code>otg:\n remote_wakeup: true\n</code></pre> ... and reboot"},{"location":"blog/2021/09/26/kvmd-3-26-philips-hue-gpio-plugin/","title":"KVMD 3.26: Philips Hue GPIO plugin","text":"<p>This releases comes with several new features and improvements.</p> <ul> <li> <p>Started rebranding Pi-KVM -> PiKVM. Everyone is constantly confused about how to write it correctly, so we will write the name in one word. And it's easier to google, too.</p> </li> <li> <p>Added Philips Hue GPIO plugin for smartplugs and lamps. We also changed the GPIO HTTP API accordingly: pin numbers are strings now, which is a requirement for named pins.</p> </li> <li> <p>ATX and GPIO actions are now also recorded in macros.</p> </li> <li> <p>The IPMI GPIO plugin no longer calls ipmitool twice when a button is clicked in the interface.</p> </li> </ul> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2021/10/03/kvmd-3-27-mouse-polling-rate/","title":"KVMD 3.27: Mouse polling rate","text":"<p>The new version ships with a new feature: configurable mouse polling rate.</p> <p>Previously it was a fixed 100ms, now it can be reduced to 10ms, so on good communication channels it makes the mouse more responsive.</p> <p>Other changes:</p> <ul> <li>Added tests to check whether the browser supports WebRTC/H.264.</li> <li>Added a GPIO driver for a new KVM switch XK-HK4401.</li> </ul> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre> <p>We also fixed the use of new Tailscale versions. Install the <code>tailscale-pikvm</code> package.</p>"},{"location":"blog/2021/10/19/kvmd-3-33-new-wifi-configuration-method/","title":"KVMD 3.33: New Wi-Fi configuration method","text":"<p>Starting from today, the old way to configure Wi-Fi using <code>netctl</code> is deprecated. Instead, it is proposed to use a more native way with <code>systemd-networkd</code>, which is already used to configure Ethernet.</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre> <p>All new OS images will use this feature. In addition, I have prepared documentation for you on how to set up wifi in a new way: https://docs.pikvm.org/wifi</p> <p>Additionally, even if you don't use Wi-Fi, do this:</p> <pre><code>rw\nsystemctl disable pikvm-bootconfig\nrm /etc/systemd/system/pikvm-bootconfig.service /usr/local/bin/_pikvm-bootconfig.sh\nsystemctl enable kvmd-bootconfig\nreboot\n</code></pre>"},{"location":"blog/2021/10/24/kvmd-3-36-custom-command-button/","title":"KVMD 3.36: Custom command button in the menu","text":"<p>We have just implemented the long-awaited feature\u2014adding a custom command button to the menu.</p> <p>I don't know why this is necessary, but it's been asked so often, so why not do it. To use it, you will need a pseudo-GPIO CMD driver. See this help page for details.</p> <p>We also improved the behavior of stream quality sliders on Firefox.</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2021/08/12/kvmd-3-14-epic-apple-fix-vol2/","title":"KVMD 3.14: The Epic Apple fix, Vol.2","text":"<p>I continue to eliminate ancient bugs from USB. So great news for Apple and v2/v3/OTG users: you no longer need to use the Arduino HID to get into the Boot Menu or Recovery Mode.</p> <p>It took a long and thoughtful study, but now this problem has been resolved. In addition, compatibility with some strange HP and DELL motherboards has improved, so if you didn't have a keyboard there before, now it has all the chances to work! Note: wakeup from suspend using keyboard has not yet worked, but it's a matter of time.</p> <p>Before updating: If you used testing repository, cancel this and use the usual settings.</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot \n</code></pre> <p>You will also need my own stable kernel build (if you are using a very old image and have not installed it, in new images it is out of the box):</p> <ol> <li>Check if it is installed: <code>pacman -Q | grep pikvm-os-raspberrypi</code></li> <li>If this command didn't show you anything, install my kernel</li> </ol>"},{"location":"blog/2022/01/08/kvmd-3-53-oled-and-fan-updates-for-v3/","title":"KVMD 3.53: OLED and fan updates for V3","text":"<p>The new KVMD update ships with a few major OLED changes.</p> <p>First off, the OLED screen now displays the temperature, CPU and memory usage. You can control that with a new <code>kvmd-oled</code> tool. American users can now turn on the temperature display in Fahrenheit, see Step 5 in the quickstart guide for details.</p> <p>The next new feature is <code>kvmd-fan</code>. This new utility implements automatic fan speed control depending on temperature.</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2022/02/11/zero-w-1-and-rpi-1-end-of-life/","title":"Zero W 1 and RPi 1 end-of-life","text":"<p>Since Arch Linux ARM has discontinued support for the ARMv6 architecture , we are discontinuing support for PiKVM based on Zero W and RPi 1, because we don't have the ability to maintain our own fork of the whole distro for this architecture.</p> <p>It is proposed to use Zero W 2 and RPi 2 for supported replacement. I know this will upset a lot of users, but there's nothing we can do about it right now. The current plan is as follows:</p> <ol> <li> <p>We will build the last image with the current packages for Zero W 1. It will not receive updates, but will continue to work as before.</p> </li> <li> <p>In the long term, we plan to create a package repository for Raspbian. When this happens, support for Zero W 1 and RPi 1 will be returned, but not for the Arch Linux ARM, but for the Raspbian / Raspberry Pi OS.</p> </li> </ol> <p>RPi 2 and the rest of the devices continue to be supported as before.</p>"},{"location":"blog/2022/02/21/kvmd-3-55-copying-text-from-target-machine/","title":"KVMD 3.55: Copying text FROM the target machine","text":"<p>Introducing a new big feature\u2014the ability to copy text from a managed machine to the clipboard.</p> <p>As you know, the clipboard inside the machine is a system feature and has no hardware connection with PiKVM. Therefore, in order to copy the text, we made it possible to recognize the selected image on the screen using the Tesseract OCR library, which converts it into text.</p> <p></p><p></p> <p>Image recognition works locally on your Raspberry Pi and does not use any Skynet clouds. In addition, recognition works ONLY on your demand, that is, the OCR library does not see the image until you give it to it explicitly, so if you are afraid to raise an evil AI, then you can relax.</p> <p>For reasons of concern about paranoids, OCR library are not installed by default yet \ud83d\ude42</p> <pre><code>rw\npacman -Syu\npacman --assume-installed tessdata -S tesseract tesseract-data-eng\nreboot\n</code></pre> <p>Install any OCR language by searching it in <code>pacman -Ss tesseract-data</code>. </p>"},{"location":"blog/2022/03/06/new-testing-branch-available/","title":"New testing branch available","text":"<p>A few months ago, due to the release of Bullseye, the usual video encoding method used in PiKVM stopped working in the new kernel. OpenMAX and MMAL were deprecated and uStreamer has ben rewrited to use new M2M encoder. Now the work is almost completed and everything seems to be working fine.</p> <p>I am asking all interested users of v0, v2 and v3 to test this update before I make it available to everyone. Rememer: this is an experimental update, so don't install it unless you're ready to do a reflash. </p> <p>To install:</p> <pre><code>rw\nsed -i -e 's|repos/arch/|repos/arch-testing/|g' /etc/pacman.conf\npacman -Syu\nreboot\n</code></pre> <p>Please report any problems to <code>#\u2060dev</code> on Discord. Also let me know if everything is working fine. I am interested in testing on RPi3, RPi4 and Zero2W boards with HDMI-CSI bridge or v3 HAT.</p>"},{"location":"blog/2022/04/01/kvmd-3-73-experimental-dynamic-usb-configuration/","title":"KVMD 3.73: Experimental dynamic USB configuration","text":"<p>First of all, although the release is experimental, it is NOT unstable. The new utility does not affect the performance of the system in any way if you do not use.</p> <p>So, the idea is that now you can change the configuration of the USB emulator on the fly. For example, you can temporarily turn off the mouse or mass storage or USB network (if you have it configured) without restarting, and then turn it on again:</p> <pre><code>[root@pikvm ~]# kvmd-otgconf\n+ hid.usb0 # Keyboard\n+ hid.usb1 # Absolute Mouse\n+ mass_storage.usb0 # Mass Storage Drive\n[root@pikvm ~]# kvmd-otgconf --disable-function mass_storage.usb0\n+ hid.usb0 # Keyboard\n+ hid.usb1 # Absolute Mouse\n- mass_storage.usb0 # Mass Storage Drive\n[root@pikvm ~]# kvmd-otgconf --enable-function mass_storage.usb0\n+ hid.usb0 # Keyboard\n+ hid.usb1 # Absolute Mouse\n+ mass_storage.usb0 # Mass Storage Drive\n</code></pre> <p>Disabling the function means that the host will not see it in USB.</p> <p>Important: Due to the imperfections of the kernel modules, in rare cases, a dynamic configuration change can lead to a kernel panic and reboot, so use this carefully. I will fix the kernel at some point.</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2022/05/03/now-you-can-buy-a-pre-assambled-pikvm-v3-with-case/","title":"Now you can buy a pre-assambled PiKVM v3 with case","text":"<p>A \u201cPre-Assembled\u201d version of PiKVM has just been released!</p> <p>It includes the PiKVM board, a Raspberry Pi 4B 2GB, and a pre-programmed 32GB SanDisk card. Each unit has been carefully built and tested \u2764\ufe0f </p> <p></p> <p>A limited quantity is available for this launch. We are expecting a high demand and will be doing our best to keep up! It\u2019s already in stock at PiShop.us and PiShop.ca and will be soon available at other resellers.</p> <ul> <li>US: https://www.pishop.us/product/pikvm-v3-pre-assembled/</li> <li>Canada: https://www.pishop.ca/product/pikvm-v3-pre-assembled/</li> <li>Other: https://www.pikvm.io/#where-to-buy</li> </ul>"},{"location":"blog/2022/06/09/kvmd-3-101-audio-on-pikvm-v3/","title":"KVMD 3.101: PiKVM V3 + Audio = \u2764\ufe0f","text":"<p>This moment has come! We are finally ready to provide audio for testing by all V3 users. </p> <p></p> <p>Right now everything is working pretty stable, so if you really wanted to watch a movie on KVM or something like that\u2014this is your chance!</p> <p>To start using audio, follow the simple instructions here: https://docs.pikvm.org/audio.</p>"},{"location":"blog/2022/06/11/introducing-new-tool-kvmd-edidconf/","title":"Introducing a new tool \u2014 `kvmd-edidconf`","text":"<p>For the happy owners of V2 and V3, we now offer a new utility, <code>kvmd-edidconf</code>. It will help you configure EDID (the display metadata) and provide import/export for EDID modification using advanced editors such as AW EDID Editor.</p> <p>For example, with its help, you can easily change the manufacturer and model of the virtual display without external editor apps, if you want PiKVM to mimic real hardware:</p> <pre><code>$ kvmd-edidconf --set-mfc-id=LNX --set-monitor-name=PiKVM\n</code></pre> <p>See the full documentation here: https://docs.pikvm.org/edid.</p>"},{"location":"blog/2022/06/24/kvmd-3-116-lets-encrypt-certificates/","title":"KVMD 3.116: Let's Encrypt certificates","text":"<p>Usually Let's Encrypt certificates are issued and updated automatically using Certbot, however, since PiKVM uses a read-only file system, special tools around Certbot are required to work with certificates.</p> <p>Now you can use it out of box. PiKVM will ensure that they are automatically renewed without affecting the root file system. Check out the documentation: https://docs.pikvm.org/letsencrypt/.</p> <p>Here is what we recently changed to allow for this.</p> <p>As you know, the file system uses read-only mode by default. However, sometimes user scripts (updating some certificates, keys, or something else) need to save some data to the memory card.</p> <p>New versions of PiKVM after 20 June 2022 provide a small 256 Mb storage partition for this and a convenient tools of automatically managing it. The storage will always be in read-only mode, and will be writable only if requested. This is super handy if you want to make a cron job or a systemd timer. For details, please see here: https://docs.pikvm.org/pst/.</p>"},{"location":"blog/2022/07/03/small-request-for-v3-and-diy-builds-with-csi-bridge-owners/","title":"A small request for V3 and DIY builds with CSI bridge owners","text":"<p>We want to change some default values in the EDID (information about the virtual display) so that it looks not like <code>Toshiba-H2C</code>, but like <code>PiKVM</code>, and also change the vendor code.</p> <p>If you have a minute, please change the EDID settings and test the PiKVM virtual display in your BIOS and OS.</p> <p>Preparations:</p> <pre><code>rw\npacman -Syu\nkvmd-edidconf --set-mfc-id=LNX --set-monitor-name=PiKVM\nreboot\n</code></pre> <p>After this, check OS and BIOS. The current paranoid hypothesis is that perhaps some ugly BIOSes may rely on the manufacturer's code for monitor Plug-n-Playing.</p> <p>Expected behavior: PiKVM video capture work as before without any problems. If something goes wrong, you can undo all the changes.</p> <p>Please, if you have completed the testing and everything is fine, click the UP! under the message. If something doesn't work, please report to \u2060the <code>#dev</code> channel on Discord. </p>"},{"location":"blog/2022/07/24/kvmd-3-126-writable-flash-drive-storage/","title":"KVMD 3.126: Writable flash drive storage","text":"<p>Now you can upload the flash drive image to MSD, write some files to it, or even install entire OS to the PiKVM MSD drive (I don't know why, but you can), and download the image back. Use the new feature wisely.</p> <p>Okay, here is an obvious question: is it possible to download not the entire image, but one file from it? This will be implemented later. For now, only the entire image.</p> <p>Another recent change affects V3 and CSI bridges owners. I changed the display name from <code>Toshiba-H2C</code> to <code>PiKVM</code> and the manufacturer id from <code>TSB</code> to <code>LNX</code>. You may need to specify the preferred monitor resolution in your OS again. If you used a custom EDID (for example, turned on the sound), then nothing will change for you.</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2022/10/07/kvmd-3-152-android-and-ios-tablets-support/","title":"KVMD 3.152: Android and iOS tablets support","text":"<p>Several latest releases of KVMD come with improved support for web UI running on tablets.</p> <ul> <li>We now have working mouse buttons and mobile keyboard for Apple tablets running iOS.</li> <li>We also fixed Shift key in iOS JUMP and bVNC clients and fixed key confusion in Apple Magic International Keyboard.</li> <li>The mobile interface is now available for Android tablets. Maybe not perfect, but it works.</li> </ul> <p>Some of the other changes are:</p> <ul> <li>Workaround for paste-as-keys for en/em dashes.</li> <li>Improved OCR.</li> <li>Kernel updated to 5.15.68.</li> </ul> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2022/11/03/kvmd-3-159-significant-vnc-improvement/","title":"KVMD 3.159: Significant VNC improvement","text":"<p>The VNC server has learned how to transmit video asynchronously to make it fast and smooth. Now, FPS can grow about twice, it will be especially noticeable with poor internet quality.</p> <p>Some of the other recent changes:</p> <ul> <li>Fixed H.264 stream corruption (it was a kernel bug).</li> <li>Fixed the bug where the web interface considered a laptop with a touchscreen to be a mobile device.</li> <li>Made it possible to use icon leds for GPIO menu title like this:</li> </ul> <pre><code>title: [\"#KVM\", \"#PC1\", pc1led, \"#PC2\", pc2led]\n</code></pre> <p>Here is how it looks:</p> <p></p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2022/11/06/kvmd-3-163-ustreamer-5-30-no-keyframes-mode/","title":"KVMD 3.163 + uStreamer 5.30: No-Keyframes mode","text":"<p>This is the second part of an experiment to improve the video streaming.</p> <p>There is such a thing in H.264\u2014keyframes. In a normal situation, they are sent approximately once per second in order to ensure the stability of the video. If you were faced with the fact that your stream turned black, and then started working again after a couple of seconds, then you had a flow failure, but the keyframe fixed this.</p> <p>So, the keyframe is our friend. But keyframes contain an entire frame of the screen, and unlike intermediate frames, which fill the entire remaining stream, they have a huge size. Next comes blah-blah-blah about WebRTC theory and flow correction algorithms in browsers, but in general, if we disable keyframes and send them only when the flow fails, you can make the stream faster, smoother and consuming less traffic.</p> <p>You can test this mode in the new update. I've added the H.264 gop parameter that adjusts the interval between keyframes.</p> <p></p> <p>If you reduce it to zero, then keyframes will be sent only in exceptional cases. This mode is best suited for slow wired channels, but I will be interested in how well it will work in wireless communication.</p> <p>I would appreciate if someone would test this and share their experience for me in \u2060dev \ud83d\ude4f </p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2022/12/15/the-pikvm-v4-kickstarter-campaign-is-on/","title":"The PiKVM V4 Kickstarter campaign is on!","text":"<p>We've been working on this for a long time! The new PiKVM V4 is even more powerful, more convenient and more feature-rich!</p> <ul> <li>We have two new devices\u2014V4 Mini and V4 Plus. They have different hardware features.</li> <li>Both are based on Compute Module 4.</li> <li>Two new video modes support added: 1920\u00d71080@60Hz and 1920\u00d71200@60Hz. This improves the UEFI/BIOS compatibility.</li> <li>V4 Mini has a fanless design and efficient power consumption.</li> <li>V4 Plus has a super-quiet cooling system with a custom-designed heatsink and intelligent fan controller.</li> <li>Both devices are ready-made: CM4 included, as well as a case, screen, and even micro SD. Uh, and they are already assembled!</li> </ul> <p>...and a lot of other nifty stuff \u26a1 </p> <p>Visit our Kickstarter page: https://www.kickstarter.com/projects/mdevaev/pikvm-v4</p>"},{"location":"blog/2023/01/23/kvmd-3-196-2fa-support/","title":"KVMD 3.196: 2FA support","text":"<p>Many have asked for this, so now you have the opportunity to increase the security of your PiKVM.</p> <p>By the way, this is a great chance to see how the QR code is rendered in the terminal using ASCII \ud83d\ude04</p> <p>Have fun: https://docs.pikvm.org/auth/#two-factor-authentication</p> <p></p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2023/03/05/kvmd-3-203-changes-in-msd/","title":"KVMD 3.203: Changes in MSD","text":"<p>This is an infrastructure release. The internal structure of the MSD image storage has changed.</p> <p>Metadata and image directories have been merged into one:</p> <p>Old:</p> <pre><code>/var/lib/kvmd/msd/images/foobar.iso\n/var/lib/kvmd/msd/meta/foobar.iso.complete\n</code></pre> <p>New:</p> <pre><code>/var/lib/kvmd/msd/foobar.iso\n/var/lib/kvmd/msd/.__foobar.iso.complete\n</code></pre> <p>If you use a standard configuration (or even MSD on a separate flash drive), the migration will be seamless for you. All you need is just to update and reboot, the files will be moved automatically. The change was needed for future MSD-over-network support.</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2023/03/21/kvmd-3-206-nfs-storage-for-virtual-media/","title":"KVMD 3.206: NFS storage for virtual media","text":"<p>Now you can create NFS share for a common images storage for your PiKVMs fleet. The images will be available on all devices.</p> <p>Here is the documentation for the new feature: https://docs.pikvm.org/msd/#nfs-storage</p> <p>This release also comes with Mass Storage Device API (<code>/api/msd</code> and and WebSocket event <code>msd_state</code>) changes required for NFS support:</p> <ul> <li>Removed the <code>features</code> field. The flags in it don't make sense since we dropped relay msd a year ago (does anyone even know what it is?)</li> <li>Removed the <code>storage.free</code> and <code>storage.size</code> fields. Instead, use <code>storage.parts[\"\"].free</code> and <code>storage.parts[\"\"].size</code>. The new mechanism provides MSD placement on several local/NFS partitions at the same time. <code>\"\"</code> means the default partition.</li> <li>Removed the <code>storage.images[...].name</code> field. Use the object key instead. </li> </ul> <p>For those who use only Web UI or VNC, nothing changes.</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre>"},{"location":"blog/2023/06/04/kvmd-3-225-performance-update/","title":"KVMD 3.225: Performance update","text":"<p>This is a performance update that improves multiple aspects of PiKVM OS.</p> <ul> <li>Added a new very effective mouse events protocol.</li> <li>Tuned some OS settings, so you will get a faster mass-storage image uploading.</li> <li>Actually, there are many more things that I have fixed and improved, but it's too boring to describe them.</li> </ul> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre> <p>We would appreciate wider testing. There are two important parameters in Web UI that affect the latency. Try them out:</p> <ul> <li>H.264 gop in the same location.</li> <li>Mouse polling interval in the System menu;</li> </ul> <p>Try to reduce it to tis minimum values (0 and 10 ms respectively). This should reduce latency and increase responsiveness. If you don't have a very reliable network (you're using VPN, or your host is a thousand kilometers away from you)\u2014check whether the mouse will work well and whether the video will not be interrupted often.</p> <p>It is important for me to know this, because if everything is fine, I will change the default values. Let me know if you encounter any problems with the described parameters.</p>"},{"location":"blog/2023/07/30/diy-pikvm-v0-based-on-arduino-hid-becomes-legacy/","title":"DIY PiKVM V0 based on Arduino HID becomes legacy","text":"<p>I'm planning to replace V0 with a new V1 soon, which will be based on Raspberry Pico.</p> <p>Here is what it boils down to:</p> <ul> <li>No more transistors and level shifters for USB emulation, now only wires are needed.</li> <li>Full-fledged PS/2 keyboard and mouse support for connoisseurs of antiquity.</li> <li>Pico is much cheaper than Arduino.</li> </ul> <p>Old DIY devices will continue to be supported, but the instructions will be marked as legacy. If you have any suggestions for the new Pico HID, please write to the <code>#\u2060dev</code> channel on Discord.</p>"},{"location":"blog/2023/08/19/kvmd-3-249-easier-uploading-over-ssh/","title":"KVMD 3.249: easier uploading over SSH","text":"<p>In addition to many minor improvements from the previous announcement, an important change has occurred in the new release for those who use advanced Mass Storage emulation features.</p> <p>Now, when uploading an image via SSH, you no longer need to create a <code>.complete</code> file, since a manually placed image will be considered complete by default. This should simplify the operation of NFS shares for images and simplify console use.</p> <p>Before updating, delete all your broken images. In theory, you should not have them, since PiKVM deletes it on uploading error, but anyway.</p> <p>To update:</p> <pre><code>rw\npacman -Syu\nreboot\n</code></pre> <p>PS: A little bit about the state of things: PiKVM is an open source product and full-time work for several people, thanks to which we can maintain the proper level of quality and security. As you can see, even after the release of V3 and V4, we do not abandon the development of DIY devices and port all possible features there.</p>"},{"location":"blog/2023/08/23/ustreamer-5-42-reduced-stream-latency/","title":"uStreamer 5.42: Reduced stream latency!","text":"<p>While I was working on HDMI passthrough for V4 Plus (I didn't forget what we promised!), I found a way to reduce the stream latency.</p> <p>Now 1080p stream with H.264 can reach ~110ms on LAN. That is, -50ms compared to the previous result.</p> <p>BTW all PiKVMs, including V3 and DIY builds, will receive this update. </p>"},{"location":"blog/2023/10/23/kvmd-3-265-mouse-jiggler/","title":"KVMD 3.265: Mouse Jiggler!","text":"<p>This is a feature that many users have been asking for for a long time. So, mouse jiggler will allow you to prevent the monitor from falling asleep if it was turned on.</p> <p>It performs short mouse movements every minute until you use PiKVM. Works with both mouse modes: absolute and relative. In addition, being enabled, it does not interfere with normal work with PiKVM: it will only interfere when you are not interacting with a virtual keyboard or mouse. The time of inactivity is counted from your last actions.</p> <p>To update (see previous post):</p> <pre><code>curl https://files.pikvm.org/update-os.sh | bash\n</code></pre> <p>Or <code>rw; pacman -Syu; reboot</code>, if you have already updated the OS using the script earlier.</p> <p>Howto enable it: https://docs.pikvm.org/mouse_jiggler/</p>"},{"location":"blog/2023/10/24/pikvm-just-got-full-ps2-support/","title":"PiKVM just got full PS/2 support","text":"<p>Previously, to support PS/2 keyboards (only), it was necessary to assemble a complex circuit on Arduino. With the transition to Raspberry Pi Pico, we finally have full support for both keyboard and mouse. The design has been greatly simplified, and is now compatible with V4 Plus.</p> <p></p> <p>HOWTO: https://docs.pikvm.org/pico_hid_bridge/</p> <p>Let me know if you need a native support of the Sun SPARCstation Keyboard & Mouse!</p>"},{"location":"blog/2023/12/03/introducing-the-new-diy-pikvm-v1-build/","title":"Introducing the new DIY PiKVM V1 build","text":"<p>We've been working for a while to unify DIY builds and simplify instructions. The result was a new DIY platform V1, which replaced V0.</p> <ul> <li>The old Arduino HID was replaced by a new one based on the Raspberry Pi Pico.</li> <li>The Pico HID uses an SPI connection and leaves the UART on the Raspberry free so that you can connect a USB-TTL adapter and use a serial console. Hurray!</li> <li>Also, the new HID has full PS/2 mouse support, not just the keyboard, as before.</li> <li>It is much easier and faster to make than the old V0 build with Arduino.</li> <li>Among other things, now we're providing ready-made OS images for all DIYs. You will no longer have to build them yourself.</li> </ul> <p>From this day on, V0 on Arduino is declared obsolete and consigned to oblivion. Instructions for its assembly are no longer available, except for the Arduino HID page. If you need an Arduino HID for anything, use the new Pico HID. The Pico HID is also capable of working as an in-place replacement for the Arduino HID, in case you need to replace it on your old V0.</p> <p>OS images and updates for V0 will still be coming out. That is, V0 support will be continued. We only deprecate the instructions.</p> <p>The assembly instructions for the PiKVM V2 have also been updated\u2014this is greatly simplified and systematized.</p> <ul> <li>https://docs.pikvm.org/v1</li> <li>https://docs.pikvm.org/v2</li> </ul>"},{"location":"blog/2024/02/03/kvmd-3-301-generated-nginx-configs/","title":"KVMD 3.301: Generated Nginx configs","text":"<p>Starting from this version, the <code>/etc/kvmd/nginx.conf</code> config will be replaced with the <code>/etc/kvmd/nginx.conf.mako</code> template, which will be rendered to <code>/run/kvmd/nginx.conf</code> taking into account the <code>/etc/kvmd/override.yaml</code> parameters and network configurations.</p> <p>This will make it very easy to turn off IPv6, HTTPS on and off and change ports using the standard override mechanism, like this:</p> <pre><code>nginx:\n https:\n enabled: false\n</code></pre> <p>If you had any changes in nginx.conf (for example, you previously disabled HTTPS manually), your Nginx configuration will roll back to the default, and HTTPS will be enabled again. To disable it, use the snippet above.</p> <p>This will not affect the settings of certificates and Letsencrypt, nothing will break here. If you have not changed Nginx configs, you have nothing to worry about at all and the migration will be seamless.</p> <p>To update:</p> <pre><code>$ curl https://files.pikvm.org/update-os.sh | bash\n</code></pre>"},{"location":"blog/2024/02/15/kvmd-3-304-video-quality-and-compatibility-improvements/","title":"KVMD 3.304: Video quality and compatibility improvements","text":"<p>In this release, you will get many improvements regarding video quality and EDID.</p>"},{"location":"blog/2024/02/15/kvmd-3-304-video-quality-and-compatibility-improvements/#pikvm-v4","title":"PiKVM V4","text":"<ul> <li>Default resolution is 1920\u00d71080@60Hz.</li> <li>Added native support of 1920\u00d71200@60Hz!</li> <li>Fixed broken audio on Linux hosts.</li> </ul>"},{"location":"blog/2024/02/15/kvmd-3-304-video-quality-and-compatibility-improvements/#pikvm-v3","title":"PiKVM V3","text":"<ul> <li>Default resolution now is 1280\u00d7720@60Hz, it should improve BIOS compatibility.</li> <li>Supported resolutions up to 1920\u00d71080@50Hz.</li> <li>Fixed broken audio on Linux hosts.</li> </ul>"},{"location":"blog/2024/02/15/kvmd-3-304-video-quality-and-compatibility-improvements/#for-v4-v3-diy-based-on-csi-bridges","title":"For V4 + V3 + DIY based on CSI bridges","text":"<ul> <li>The color rendering quality has been significantly improved. Now the colors are bright and juicy, and not overexposed, see the attached picture.</li> <li>Presumably, this release should put an end to shamanic dancing with EDID settings for different BIOSes.</li> <li>Added several new supported resolutions like 1600\u00d7YYYY.</li> <li>kvmd-edidconf --set-audio=1 now allows you to automatically add audio blocks for PiKVM, which are required by some particularly finicky OS.</li> </ul> <p>To update:</p> <pre><code>$ curl https://files.pikvm.org/update-os.sh | bash\n</code></pre> <p>Important: if you are using a custom EDID, you will need to manually replace it with a new one after update. For example: rw; kvmd-edidconf --restore-default=v4plus; reboot (available: v0, v1, v2, v3, v4mini and v4plus)</p> <p></p>"},{"location":"blog/2024/02/16/kvmd-3-305-new-option-to-hide-the-blue-dot/","title":"KVMD 3.305: New option to hide the blue dot","text":"<p>Now you can disable the blue mouse dot.</p> <p></p> <p>But I still don't recommend doing this, because using the blue dot you can not wait for the real cursor. Click events are instantly transmitted to where the blue dot points, not the lagging real cursor.</p>"},{"location":"blog/2024/02/23/hdmi-passthrough-on%20pikvm-v4-plus/","title":"HDMI passthrough on PiKVM V4 Plus","text":"<p>We promised it at the start and finally it's almost done. The V4 Plus will get an HDMI passthrough on one of its outputs. Right now It's working on my desk, and it's pretty good: 1080p 60 fps with vertical sync, perfect 24 bit color and zero-latency.</p> <p>The first versions will pass the video if the online stream in the Web UI or VNC is not active. This is necessary to reduce all possible delays. I will finalize this in the future. I plan to release a public beta in the next week or two. In fact, it might happen sooner if I catch a wave.</p>"},{"location":"blog/2024/03/06/kvmd-ustreamer-performance-update/","title":"KVMD + uStreamer performance update","text":"<p>Today I have prepared a great update for you. After few weeks of research, I managed to increase the video performance slightly reduce the latency for all CSI devices (PiKVM V4, V3 and CSI-based V2).</p> <p>In H.264 mode (WebUI and VNC), you will get stable 30fps on 1080p and 60fps on 720p In MJPEG mode it just works a little faster.</p> <p>To update:</p> <pre><code># pikvm-update`\n</code></pre> <p>If this command is not available, please use:</p> <pre><code># curl https://files.pikvm.org/update-os.sh | bash`\n</code></pre>"},{"location":"blog/2024/03/17/kvmd-3-319-display-orientation-options/","title":"KVMD 3.319: Display orientation options for H.264 stream","text":"<p>For the H.264 stream, there are now options to rotate the virtual screen.</p> <p>Rotation is done in 90\u00b0 increments. The toggles are in the System menu in the web UI.</p> <p></p> <p>To update:</p> <pre><code># pikvm-update`\n</code></pre> <p>If this command is not available, please use:</p> <pre><code># curl https://files.pikvm.org/update-os.sh | bash`\n</code></pre>"},{"location":"blog/2024/04/16/kvmd-3-333-hdmi-passthrough-now-available-on-v4-plus/","title":"KVMD 3.333: HDMI passthrough now available on V4 Plus","text":"<p>After a long and thorny path of research, we are pleased to present the promised HDMI passthrough feature for PiKVM V4 Plus.</p> <p></p><p></p> <p>The new feature allows you to connect PiKVM between the host and local display. PiKVM will not interfere with the normal operation of the display and passes the video signal through itself until you need remote access. In this case, PiKVM will copy the video stream to the Web UI or VNC.</p> <p>But the most important thing is that the video will still be available on the local display at the same time as the stream! And of course it's zero-latency for the local display, with VSync support.</p> <p>How-to: https://docs.pikvm.org/pass</p> <p>Also, I'm glad that this release got a beautiful number, and I was finally able to make the Evangelion reference, which I forgot to do for 3.33 :)</p>"},{"location":"blog/2024/08/19/kvmd-4-4-stable-hdmi-passthrough-on-v4-plus/","title":"KVMD 4.4: HDMI passthrough on V4 Plus is stable now","text":"<p>Thanks to the work of the Raspberry kernel team, a bug related to incorrect colors in H.264 was finally fixed while working with passthrough.</p> <p>With the new release, this feature is now enabled by default, and you will get great juicy colors both in the stream and on the external physical monitor. See the documentation for details on setting this up.</p> <p></p>"},{"location":"blog/2024/12/20/announcing-pikvm-switch-multiport-extender/","title":"Announcing PiKVM Switch Multiport Extender","text":"<p>The PiKVM team is excited to present its new PiKVM Switch Multiport Extender - the most full-featured switch for PiKVM devices. After much anticipation, the PiKVM Switch is now available for order! The switch allows you to connect up to four target hosts to a single PiKVM and provides full control over them.</p> <p></p> <ul> <li>ATX control on each port.</li> <li>Per-port EDID configuration.</li> <li>HDMI dummy plug functionality.</li> <li>True Plug-n-Play with no need for override.yaml setups and complete control via Web UI.</li> <li>Multifunctional RGB LEDs with beacon mode and customizable color schemes.</li> <li>Firmware update directly from PiKVM and ready for future hardware extensions.</li> <li>Compatible with V4 Plus, V3 and DIY devices based on Pi2-Pi4 except Zero and V4 Mini.</li> </ul> <p>And now the best part: the switches can be chained! Need four ports? Get a PiKVM Switch Multiport Extender. As your server fleet expands to eight, simply add another switch and link it to the first one. Need even more? No worries \u2014 connect up to five switches and enjoy 20 fully functional ports on your PiKVM. Say goodbye to replacing your entire KVM system!</p> <p>You can order PiKVM Switch Multiport Extender from our international store.</p> <p>Canadian customers can place an order at PiShop.ca.</p> <p>See also the detailed technical descriptions and documentation on docs.pikvm.org.</p> <p>The first batch will start shipping at the end of December 2024, and the second batch will be at the end of January 2025. </p>"},{"location":"blog/2024/12/25/kvmd-4-29-h264-over-http/","title":"KVMD 4.29: H.264 over HTTP","text":"<p>I know that some people have a problem using H.264 and WebRTC with firewalls, NAT, Tailscale and other things. Until recently, the only alternative was MJPEG, which consumes a lot of traffic. So I was constantly researching whether something could be done about it, and finally found a way.</p> <p>Starting with KVMD 4.29, in addition to WebRTC, a new method of direct transmission of H.264 over HTTP will be available to you. Is the Web UI working? Then direct video transmission will also work. This completely solves the problem of WebRTC unavailability.</p> <p>This new feature is available for free not only to PiKVM V4 and V3 users, but also to all DIY users with HDMI-CSI devices. Merry Christmas to everyone! \ud83e\udd73 </p> <p>A little tip: use H.264 gop 0 in settings.</p> <p>To update just run <code>pikvm-update</code>. As usual, I advise you not to upgrade without physical access to the device. Also, you should not update PiKVM if the amount of alcohol in the blood on the occasion of the holiday is not zero or at least does not correspond to the level of the peak Ballmer.</p> <p>PS: Our work on the open development of PiKVM is possible only through sales of hardware and donations. So if you want to support us, please consider [buying(https://pikvm.org/buy/) our official PiKVM or a Switch.</p> <p></p>"},{"location":"blog/2025/01/12/switch-update-%20better-hdmi-compatibility/","title":"Switch update: better HDMI compatibility","text":"<p>An announcement for happy PiKVM Switch owners. We have released a firmware update that improves compatibility with some HDMI sources + audio. </p> <p>You need to update the PiKVM OS using <code>pikvm-update</code>, and the firmware will be delivered with it. Next, follow the instructions in the Switch menu.</p> <p>This is another cool feature of the PiKVM Switch: you don't need to take any complicated steps to update the firmware. A switch connected to PiKVM receives an update from PiKVM, and then updates all other switches in the chain automatically.</p> <p></p>"},{"location":"blog/2025/01/20/kvmd-4-44-two-way-audio-with-microphone/","title":"KVMD 4.44: Two-way audio with microphone","text":"<p>PiKVM V3 and V4 Mini/Plus just got two-way audio with microphone! Now you can use voice applications remotely, or you can just emotionally tell the server what you think about it.</p> <p></p><p></p> <p>How to: https://docs.pikvm.org/audio</p>"},{"location":"blog/2025/01/24/kvmd-4-49-dvd-images-support/","title":"KVMD 4.49: DVD images support","text":"<p>Starting with KVMD 4.49, the old 2.2 GB CD limit is now removed.</p> <p>PiKVM just learned how to support large DVD images natively, which means that you no longer need Ventoy to prepare Flash images for PiKVM. You can even use the official Windows ISO to install the OS! Small ISO images will be handled as CD as before, but for big images PiKVM will switch emulation to DVD mode automatically.</p> <p></p> <p>How to update: <code>pikvm-update</code>, as usual.</p> <p>If you've been dreaming of getting DVD emulation, then your wish has been fulfilled \ud83d\ude42</p>"},{"location":"blog/2025/02/16/pikvm-switch-firmware-update/","title":"PiKVM Switch firmware update","text":"<p>At the request of Switch owners, we have improved the compatibility with DIY devices based on CSI bridge.</p> <ul> <li>Fixed the problem of the HDMI backpowering.</li> <li>Added compatibility mode if DIY PiKVM does not see the image through the switch.</li> </ul> <p>As we promised, this is a new generation of multiport switches. It's so smart that we can fix any problems with it with a simple firmware update. No more \"Oh crap, my \" doesn't show any videos because of EDID \ud83d\ude2d \" Okay, okay, we just really proud of the design, sorry \ud83d\ude42</p> <ul> <li>How to update: https://docs.pikvm.org/switch/#firmware-updating</li> <li>How to enable the fix: next to the update chapter.</li> </ul> <p>Where to buy:</p> <ul> <li>Worldwide: https://shop.hipi.io/product/pikvm-switch-multiport-extender</li> <li>Canada: https://www.pishop.ca/product/pikvm-switch-multiport-extender/</li> </ul>"},{"location":"blog/2025/03/11/kvmd-4-65-adopt-display-identifiers-on-v4-plus/","title":"KVMD 4.65: Adopt display identifiers on V4 Plus","text":"<p>PiKVM V4 Plus just got a new tool to read and adopt display identifiers like model and serial number from the physical monitor.</p> <p>Install the updated OS using pikvm-update, connect the desired display to OUT2 port and use follows:</p> <pre><code>[root@pikvm ~]# rw\n[root@pikvm ~]# kvmd-edidconf --import-display-ids --apply\n[root@pikvm ~]# ro\n</code></pre> <p>V4 will read display identifiers and apply them to own EDID. The target host connected to PiKVM will recognize it as your display.</p>"},{"location":"blog/2025/05/18/kvmd-4-72-big-bunch-of-big-improvements/","title":"KVMD 4.72: A big bunch of big improvements","text":"<p>This release has gathered a whole bunch of features that some users have been asking. And this is a big step forward in terms of usability.</p>"},{"location":"blog/2025/05/18/kvmd-4-72-big-bunch-of-big-improvements/#web-ui","title":"Web UI","text":"<ul> <li>\u2b50 The maximized window continues to be maximized when the browser is resized or the resolution of the remote host is changed. It's meaning the stream will always occupy the maximum workspace without having to constantly press the dot button to remove the black bars from above or below the stream.</li> <li>\u2b50 The text in the paste menu can now be sent using the hotkey Ctrl+Enter.</li> <li>\u2b50 Added two-finger scrolling on touch devices.</li> <li>\u2b50 The virtual keyboard supports the key lock mode by clicking the middle button. Hotkeys like REISUB are now much more convenient to enter. Long left or short right click for hold like right now, middle for lock.</li> <li>Fixed the mouse positioning at the right and bottom edges of the screen.</li> <li>Fixed incorrect scrolling inertia when changing the direction. The scrolling algorithm has been significantly improved.</li> <li>Fixed the keys overlapping on the virtual keyboard on HiDPI screens.</li> </ul>"},{"location":"blog/2025/05/18/kvmd-4-72-big-bunch-of-big-improvements/#vnc","title":"VNC","text":"<ul> <li>\u2b50 Eliminated the mess with the clipboard. Now, to paste the text, you just need to copy it to the client PC, and then use the magic <code>LeftAlt,LeftAlt,P</code> hotkey (quickly in a row, without holding). No more accidental insertion when switching windows.</li> <li>\u2b50 Hotkeys for switching channels on the PiKVM Switch on any VNC client. If you have one or two switches, you can use <code>LeftAlt,LeftAlt,1 (1-8)</code> to switch between 8 channels. For three or more Switches, you need to use double numbers, like <code>LeftAlt,LeftAlt,3,2</code> (unit 3, channel 2).</li> <li>\u2b50 VNC clients showing host information will now display the current active port of PiKVM Switch and KVM name.</li> <li>VNCAuth no longer requires you to write the KVMD password in /etc/kvmd/vncpasswd and does not prevent you from using one-time passwords with KVMD. Now you can turn it on if you haven't done it before.</li> </ul>"},{"location":"blog/2025/05/18/kvmd-4-72-big-bunch-of-big-improvements/#ipmi","title":"IPMI","text":"<ul> <li>kvmd-ipmi no longer requires writing the KVMD password in <code>/etc/kvmd/ipmipasswd</code> and does not prevent you from using 2FA with KVMD. Now you can turn it on if you haven't done it before.</li> </ul>"},{"location":"blog/2025/05/18/kvmd-4-72-big-bunch-of-big-improvements/#pikvm-switch","title":"PiKVM Switch","text":"<ul> <li>\u2b50 Improved VNC integration (see the previous header).</li> <li>Option to disable the dummy plug function.</li> </ul> <p>To update:</p> <p><code>pikvm-update</code></p>"},{"location":"blog/2025/05/23/kvmd-4-74-local-usb-mouse-passthrough/","title":"KVMD 4.74: Local USB keyboard & mouse passthrough","text":"<p>With this new mode, all USB keyboards and mice connected to PiKVM directly will be forwarded the host. If you're using PiKVM Switch, they will be forwarded via the Switch to the active selected host.</p> <p>There are several hotkeys available that are always active:</p> <ul> <li><code>LeftAlt, LeftAlt, K</code> - (mnemonic KVM, quick hit) disable keyboard/mouse grabbing and allow them to use with PiKVM locally, for example, for the console operating.</li> <li><code>LeftAlt, LeftAlt, H</code> - (Host) - switch back to the passthrough mode and pass keyboard-mouse events to the host.</li> <li>Switching the PiKVM Switch channels. If you have one or two switches, you can use <code>LeftAlt, LeftAlt, 1 (1-8)</code> to switch between 8 channels. For three or more Switches, you need to use double numbers, like <code>LeftAlt, LeftAlt, 3, 2</code> (unit 3, channel 2).</li> </ul> <p>Now you can set up your workplace so that all your input devices are connected via PiKVM, this is especially convenient with the V4 Plus, which can also passthrough a monitor. And if you use a switch, then you will no longer need to have a separate keyboard and mouse for local work. Your workplace behaves exactly the same locally as it does remotely.</p> <p>To enable this feature, update OS with <code>pikvm-update</code> and run <code>rw; systemctl enable --now kvmd-localhid; ro</code>. </p>"},{"location":"blog/2025/05/27/kvmd-4-76-advanced-diagnostics-for-the-video-streams/","title":"KVMD 4.76: Advanced diagnostics for the video stream","text":"<p>Now you will see the reason why there is no signal. We reliably distinguish the condition of the cable from the absence of a signal or unsupported video mode.</p> <p></p>"},{"location":"blog/2025/09/30/kvmd-4-99-oled-display-improvements-on-v3-and-v4/","title":"KVMD 4.99: OLED display improvements on V3 and V4","text":"<ul> <li>Now the display shows the number of users who use PiKVM via the Web UI and VNC. This number is located next to the cute spinning stick that we all love so much.</li> <li>If there is at least one user, the display brightness will be reduced to a minimum to prolong its life.</li> </ul>"},{"location":"blog/2025/10/23/kvmd-4-107-configuration-changes/","title":"KVMD 4.107: Configuration changes","text":"<p>We have revamped the configuration system. If PiKVM customization concerns you, read on.</p> <p>Here are the main changes:</p> <ul> <li> <p>We have moved <code>/etc/kvmd/main.yaml</code> to <code>/usr/lib/kvmd/</code>, because it's a platform config that should never be changed.</p> </li> <li> <p>We have deprecated and removed <code>/etc/kvmd/logging.yaml</code>. It contained some Python-specific logging settings that no one had ever changed. Getting rid of this artifact will simplify the configuration structure for some future improvements.</p> </li> <li> <p>We have deprecated <code>/etc/kvmd/auth.yaml</code>. This is a legacy auth configuration that existed before <code>/etc/kvmd/override.yaml</code> was introduced, and has never been suggested for use even in the documentation. If you have ever customized your PiKVM with <code>auth.yaml</code> (likely not), your changes will be carefully moved to <code>/etc/kvmd/override.d/...</code>, and the source file is <code>auth.yaml</code> should be deleted manually. Please see here for details.</p> </li> <li> <p>The <code>!include</code> directive in <code>/etc/kvmd/override*</code> and <code>/etc/kvmd/meta.yaml</code> configs is now deprecated and removed. Instead, you can place your partial config files into the <code>/etc/kvmd/override.d</code> directory, which is described in the documentation. Automatic migration is not possible here, and if you used <code>!include</code> for some reason, <code>pikvm-update</code> will tell you to remove this from the configuration before updating.</p> </li> </ul> <p>Please note that if you stored all the configs only in <code>override.d</code> and <code>override.yaml</code> and did not use <code>!include</code>, the migration will be transparent for you.</p>"},{"location":"stl/atx/","title":"PiKVM v3 ATX mounting brackets for 3D printing","text":""},{"location":"stl/atx/#pikvm-v3-atx-mounting-brackets-for-3d-printing","title":"PiKVM v3 ATX mounting brackets for 3D printing","text":"<p>A good way to mount an ATX adapter in a computer case is to place it in a PCI slot. Here you can get drawings of PCI brackets for 3D printing.</p> Variant Description This is a standard bracket of common length, which will fit most personal computers The short bracket (low profile), for compact PCs or rack servers"},{"location":"stl/v3.2/","title":"3D printable case for PiKVM v3.2 HAT","text":""},{"location":"stl/v3.2/#3d-printable-case-for-pikvm-v32-hat","title":"3D printable case for PiKVM v3.2 HAT","text":"<p>When printing the case, you can choose the following options:</p> <ul> <li>The presence or absence of an OLED screen (used to display the IP address and other information).</li> <li>The presence or absence of holes for the AUM v3.3 (Advanced USB Module, most likely you don't have it).</li> </ul> <p>Also take a look at the PCI bracket for ATX adapter board.</p>"},{"location":"stl/v3.2/#buy-options","title":"Buy options","text":"<ul> <li>Small 5v fan strongly recommended to avoid overheating in the case.</li> <li>I2C OLED screen.</li> </ul>"},{"location":"stl/v3.2/#building","title":"Building","text":""},{"location":"stl/v3.2/#parts","title":"Parts","text":""},{"location":"stl/v3.2/#the-front-part","title":"The front part","text":"<p>Choose ONE of them.</p> Variant Description The front part of the case WITHOUT a hole for the OLED The front part of the case with a hole for installing the OLED"},{"location":"stl/v3.2/#the-back-part","title":"The back part","text":"<p>Choose ONE of them.</p> Variant Description The back part of the case WITHOUT AUM holes The back part of the case for installing the AUM"},{"location":"stl/v3.2/#spacers","title":"Spacers","text":"Type Description 6.2mm spacer, required TWO pieces 2mm spacer required TWO without AUM or ONE for AUM 1mm spacer required ONE for AUM only Low spacer required ONE"},{"location":"stl/v3.3/","title":"PiKVM v3.3 Plastic Case for 3D printing","text":""},{"location":"stl/v3.3/#pikvm-v33-plastic-case-for-3d-printing","title":"PiKVM v3.3 Plastic Case for 3D printing","text":"<p>When printing the case, you can choose the following options:</p> <ul> <li>The presence or absence of an OLED screen (used to display the IP address and other information).</li> </ul> <p>Also take a look at the PCI bracket for ATX adapter board and great unofficial case mod for Noctua fans</p>"},{"location":"stl/v3.3/#buy-options","title":"Buy options","text":"<ul> <li>Small 5v fan strongly recommended to avoid overheating in the case.</li> <li>I2C OLED screen.</li> </ul>"},{"location":"stl/v3.3/#parts","title":"Parts","text":""},{"location":"stl/v3.3/#the-front-part","title":"The front part","text":"<p>Choose ONE of them.</p> Variant Description The front part of the case WITHOUT a hole for the OLED The front part of the case with a hole for installing the OLED"},{"location":"stl/v3.3/#the-back-part","title":"The back part","text":"Variant Description The back part of the case"},{"location":"stl/v3.3/#spacers","title":"Spacers","text":"Type Description 6.2mm spacer, required TWO pieces 1mm spacer required TWO pieces Low spacer required ONE piece"},{"location":"stl/v3.3/#fasteners-screws","title":"Fasteners (screws)","text":"<p>The official PiKVM v3.3 hat came with eight M2.5 x 12mm screws for countersunk holes. You can use these with the case.</p>"},{"location":"stl/v3.3/#assembly","title":"Assembly","text":"<p>Note: the spacers slide over the (short) hexagonal standoffs included in the official v3.3 hat:</p> <p></p> <p>To assemble:</p> <ol> <li>Ensure the hexagonal standoffs are all attached to the top side of the v3.3 hat. Tip: if you need to remove the case in the future, you don't want these hexagonal standoffs spinning while you loosen the screws - be sure to tighten the standoffs more than you tighten the screws in step 17. You could even use some thread-locking fluid on the standoffs now.</li> <li>Ensure the bottom side of the Pi has no screws present</li> <li>Ensure you have eight M2.5 x 12mm screws free for later use.</li> <li>Slide the two short spacers over the two standoffs on the side of the hat which contains the ATX, keyboard/mouse emulation, and HDMI connector. See Figure 1.</li> </ol> Figure 1: 1mm spacer placement <ol> <li>Slide the two long spacers over the two standoffs on the opposite side of the HAT - near the LEDs, power input, and console-over-ethernet connector. See Figure 2.</li> </ol> Figure 2: Placement of 6.2mm spacers. <ol> <li>Attach the fan to the two headers labeled \"fan\" located next to the CSI ribbon cable and large capacitor.</li> <li>Slide the fan into the slot on the front part of the case. The fan should move fan from outside to inside the case. For the fan in Figure 3, this means mounting with the label facing the inside of the case and the black lead connected to the negative (-) terminal on the PCB. Ensure the fan leads don't bind as you slide the fan in. See Figure 3.</li> </ol> Figure 3: Fan placement <ol> <li>If you still have foam covering the GPI pins on the top side of the hat, now is a good time to remove them. Leaving this in place will restrict airflow. </li> <li>Flip the PiKVM over and set the low spacer bracket you printed on the bottomside of the Pi with the straight edge facing away from the SD card. See Figure 4.</li> </ol> Figure 4: Low spacer placement <ol> <li>While allowing the low spacer to continue resting on the Pi, gently slide the PiKVM into the front part of the case. Ensure the spacers clear the top of the case (likely facing away from you) and that the fan leads don't bind on anything. The low spacer should remain mostly in place thanks to the solder joints on the Pi.</li> <li>If successful, the low spacer should be fairly close to aligning with the holes in the case. Use a small screwdriver or tweezers to fix the alignment. You may need to insert the screwdriver into the case along the inner face to push the low spacer towards the holes. See video for reference.</li> <li>Insert 4 screws into the holes of the case and tighten enough so things don't fall out, but leave plenty of slack - you might need to push the electronics around slightly to align the holes in the next steps.</li> <li>Now is a good time to power on the PiKVM and ensure the fan spins. It should come on automatically unless you explicitly disabled it yourself.</li> <li>Slide the back part over the PiKVM and align with the front part you assembled in previous steps.</li> <li>Ensure the case seats properly around the connectors.</li> <li>Insert the remaining four screws into the case and tighten. If the holes don't line up, you can hold the case while pushing on some of the PiKVM connectors to shift the electronics inside the case.</li> <li>Tighten all screws.</li> <li>Tip your bartender.</li> </ol>"},{"location":"blog/archive/2025/","title":"2025","text":""},{"location":"blog/archive/2025/#2025","title":"2025","text":""},{"location":"blog/archive/2024/","title":"2024","text":""},{"location":"blog/archive/2024/#2024","title":"2024","text":""},{"location":"blog/archive/2023/","title":"2023","text":""},{"location":"blog/archive/2023/#2023","title":"2023","text":""},{"location":"blog/archive/2022/","title":"2022","text":""},{"location":"blog/archive/2022/#2022","title":"2022","text":""},{"location":"blog/archive/2021/","title":"2021","text":""},{"location":"blog/archive/2021/#2021","title":"2021","text":""},{"location":"blog/archive/2020/","title":"2020","text":""},{"location":"blog/archive/2020/#2020","title":"2020","text":""},{"location":"blog/category/releases/","title":"Releases","text":""},{"location":"blog/category/releases/#releases","title":"Releases","text":""},{"location":"blog/category/products/","title":"Products","text":""},{"location":"blog/category/products/#products","title":"Products","text":""},{"location":"blog/category/development/","title":"Development","text":""},{"location":"blog/category/development/#development","title":"Development","text":""},{"location":"blog/page/2/","title":"Blog","text":""},{"location":"blog/page/2/#blog","title":"Blog","text":""},{"location":"blog/page/3/","title":"Blog","text":""},{"location":"blog/page/3/#blog","title":"Blog","text":""},{"location":"blog/page/4/","title":"Blog","text":""},{"location":"blog/page/4/#blog","title":"Blog","text":""},{"location":"blog/page/5/","title":"Blog","text":""},{"location":"blog/page/5/#blog","title":"Blog","text":""},{"location":"blog/page/6/","title":"Blog","text":""},{"location":"blog/page/6/#blog","title":"Blog","text":""},{"location":"blog/page/7/","title":"Blog","text":""},{"location":"blog/page/7/#blog","title":"Blog","text":""},{"location":"blog/page/8/","title":"Blog","text":""},{"location":"blog/page/8/#blog","title":"Blog","text":""},{"location":"blog/page/9/","title":"Blog","text":""},{"location":"blog/page/9/#blog","title":"Blog","text":""},{"location":"blog/page/10/","title":"Blog","text":""},{"location":"blog/page/10/#blog","title":"Blog","text":""},{"location":"blog/archive/2022/page/2/","title":"2022","text":""},{"location":"blog/archive/2022/page/2/#2022","title":"2022","text":""},{"location":"blog/archive/2021/page/2/","title":"2021","text":""},{"location":"blog/archive/2021/page/2/#2021","title":"2021","text":""},{"location":"blog/archive/2021/page/3/","title":"2021","text":""},{"location":"blog/archive/2021/page/3/#2021","title":"2021","text":""},{"location":"blog/archive/2020/page/2/","title":"2020","text":""},{"location":"blog/archive/2020/page/2/#2020","title":"2020","text":""},{"location":"blog/archive/2020/page/3/","title":"2020","text":""},{"location":"blog/archive/2020/page/3/#2020","title":"2020","text":""},{"location":"blog/category/products/page/2/","title":"Products","text":""},{"location":"blog/category/products/page/2/#products","title":"Products","text":""},{"location":"blog/category/releases/page/2/","title":"Releases","text":""},{"location":"blog/category/releases/page/2/#releases","title":"Releases","text":""},{"location":"blog/category/releases/page/3/","title":"Releases","text":""},{"location":"blog/category/releases/page/3/#releases","title":"Releases","text":""},{"location":"blog/category/releases/page/4/","title":"Releases","text":""},{"location":"blog/category/releases/page/4/#releases","title":"Releases","text":""},{"location":"blog/category/releases/page/5/","title":"Releases","text":""},{"location":"blog/category/releases/page/5/#releases","title":"Releases","text":""},{"location":"blog/category/releases/page/6/","title":"Releases","text":""},{"location":"blog/category/releases/page/6/#releases","title":"Releases","text":""},{"location":"blog/category/releases/page/7/","title":"Releases","text":""},{"location":"blog/category/releases/page/7/#releases","title":"Releases","text":""},{"location":"blog/category/releases/page/8/","title":"Releases","text":""},{"location":"blog/category/releases/page/8/#releases","title":"Releases","text":""}]} |