Skip to content

Commit 9dbc7d7

Browse files
llogenllogen
committed
feat: add PiKVM module
The PiKVM module provides comprehensive control of a DUT via a PiKVM device. It offers power management through ATX control, keyboard input simulation, and virtual media mounting capabilities. Power management commands: on, off, force-off, reset, force-reset, and status. Keyboard control commands: type, key, combo, and paste. Virtual media commands: mount, mount-url, unmount, and media-status. The module connects to a PiKVM device using HTTP/HTTPS with configurable host, user, password, and timeout. It supports both short and long ATX button presses for power and reset control, allows sending keyboard input and key combinations, and enables mounting ISO images from local files or URLs. Signed-off-by: llogen <christoph.lange@blindspot.software>
1 parent 1da20f9 commit 9dbc7d7

5 files changed

Lines changed: 1011 additions & 0 deletions

File tree

‎cmds/dutagent/modules.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import (
1818
_ "github.com/BlindspotSoftware/dutctl/pkg/module/gpio"
1919
_ "github.com/BlindspotSoftware/dutctl/pkg/module/ipmi"
2020
_ "github.com/BlindspotSoftware/dutctl/pkg/module/pdu"
21+
_ "github.com/BlindspotSoftware/dutctl/pkg/module/pikvm"
2122
_ "github.com/BlindspotSoftware/dutctl/pkg/module/serial"
2223
_ "github.com/BlindspotSoftware/dutctl/pkg/module/shell"
2324
_ "github.com/BlindspotSoftware/dutctl/pkg/module/ssh"

‎pkg/module/pikvm/README.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# PiKVM
2+
3+
This module provides comprehensive control of a DUT via a PiKVM device. It offers power management through ATX control, keyboard input simulation, and virtual media mounting capabilities.
4+
5+
## Features
6+
7+
### Power Management
8+
Control the DUT's power state via ATX power and reset buttons:
9+
10+
```
11+
COMMANDS:
12+
on Power on via short ATX power button press
13+
off Graceful shutdown via short ATX power button press
14+
force-off Force power off via long ATX power button press (4-5 seconds)
15+
reset Reset via short ATX reset button press
16+
force-reset Force reset via long ATX reset button press
17+
status Query current power state
18+
```
19+
20+
### Keyboard Control
21+
Send keyboard input to the DUT:
22+
23+
```
24+
COMMANDS:
25+
type <text> Type a text string
26+
key <keyname> Send a single key (e.g., Enter, Escape, F12)
27+
combo <keys> Send key combination (e.g., Ctrl+Alt+Delete)
28+
paste Paste text from stdin
29+
```
30+
31+
### Virtual Media
32+
Mount ISO images or disk images as virtual USB devices:
33+
34+
```
35+
COMMANDS:
36+
mount <path> Mount an image file from the agent's filesystem
37+
mount-url <url> Mount an image from a URL
38+
unmount Unmount current virtual media
39+
media-status Show mounted media information
40+
```
41+
42+
## Configuration Options
43+
44+
| Option | Type | Default | Description |
45+
| -------- | ------ | ------- | -------------------------------------------------------- |
46+
| host | string | - | Address of the PiKVM device (e.g., "192.168.1.100") |
47+
| user | string | admin | Username for authentication |
48+
| password | string | - | Password for authentication |
49+
| timeout | string | 10s | Timeout for HTTP requests (e.g., "10s", "30s") |
50+
51+
⚠️ **Security Warning**: Passwords are stored in plaintext in the configuration file. This should only be used in trusted environments.
52+
53+
## API Endpoints Used
54+
55+
This module interacts with the following PiKVM API endpoints:
56+
57+
- `/api/atx/power` - Power management status
58+
- `/api/atx/click` - ATX button control (power/reset)
59+
- `/api/hid/events/send_key` - Keyboard input simulation
60+
- `/api/msd` - Mass Storage Device (virtual media) control
61+
- `/api/msd/write` - Upload images to PiKVM
62+
- `/api/msd/set_connected` - Mount/unmount media
63+
64+
## Usage Examples
65+
66+
See [pikvm-example-cfg.yml](./pikvm-example-cfg.yml) for comprehensive configuration examples.
67+
68+
### Basic Power Control
69+
70+
```yaml
71+
version: 0
72+
devices:
73+
my-server:
74+
desc: "Server controlled via PiKVM"
75+
cmds:
76+
power-on:
77+
desc: "Power on the server"
78+
modules:
79+
- module: pikvm
80+
main: true
81+
args:
82+
- on
83+
options:
84+
host: https://pikvm.local
85+
user: admin
86+
password: admin
87+
```
88+
89+
### Boot Menu Access
90+
91+
```yaml
92+
enter-bios:
93+
desc: "Press F12 to enter boot menu"
94+
modules:
95+
- module: pikvm
96+
main: true
97+
args:
98+
- key
99+
- F12
100+
options:
101+
host: https://pikvm.local
102+
user: admin
103+
password: admin
104+
```
105+
106+
### ISO Mounting
107+
108+
```yaml
109+
mount-installer:
110+
desc: "Mount Ubuntu installer ISO"
111+
modules:
112+
- module: pikvm
113+
main: true
114+
args:
115+
- mount-url
116+
- https://releases.ubuntu.com/22.04/ubuntu-22.04-live-server-amd64.iso
117+
options:
118+
host: https://pikvm.local
119+
user: admin
120+
password: admin
121+
```
122+
123+
## Requirements
124+
125+
- PiKVM device with API access enabled
126+
- Network connectivity between dutagent and PiKVM
127+
- Valid authentication credentials
128+
129+
## Notes
130+
131+
- The module defaults to HTTPS if no scheme is specified in the host
132+
- HTTP can be used by explicitly specifying `http://` in the host
133+
- Long button presses (force-off, force-reset) hold the button for 4-5 seconds
134+
- Virtual media images are uploaded to PiKVM's storage when using the `mount` command
135+
- The `mount-url` command instructs PiKVM to download the image directly from the URL

‎pkg/module/pikvm/pikvm-example-cfg.yml‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
version: 0
2+
devices:
3+
my-server:
4+
desc: "A server controlled via PiKVM"
5+
cmds:
6+
# Power Management Commands
7+
power-on:
8+
desc: "Power on the server via PiKVM ATX power button (short press)"
9+
modules:
10+
- module: pikvm
11+
main: true
12+
args:
13+
- on
14+
options:
15+
host: https://pikvm.local
16+
user: admin
17+
password: admin
18+
timeout: 10s
19+
20+
power-off:
21+
desc: "Graceful shutdown via PiKVM ATX power button (short press)"
22+
modules:
23+
- module: pikvm
24+
main: true
25+
args:
26+
- off
27+
options:
28+
host: https://192.168.1.100
29+
user: admin
30+
password: admin
31+
32+
force-off:
33+
desc: "Force power off via PiKVM ATX power button (long press)"
34+
modules:
35+
- module: pikvm
36+
main: true
37+
args:
38+
- force-off
39+
options:
40+
host: https://pikvm.local
41+
user: admin
42+
password: admin
43+
44+
reset:
45+
desc: "Reset via PiKVM ATX reset button (short press)"
46+
modules:
47+
- module: pikvm
48+
main: true
49+
args:
50+
- reset
51+
options:
52+
host: https://pikvm.local
53+
user: admin
54+
password: admin
55+
56+
force-reset:
57+
desc: "Force reset via PiKVM ATX reset button (long press)"
58+
modules:
59+
- module: pikvm
60+
main: true
61+
args:
62+
- force-reset
63+
options:
64+
host: https://pikvm.local
65+
user: admin
66+
password: admin
67+
68+
status:
69+
desc: "Query current power status via PiKVM"
70+
modules:
71+
- module: pikvm
72+
main: true
73+
args:
74+
- status
75+
options:
76+
host: https://pikvm.local
77+
user: admin
78+
password: admin
79+
80+
# Keyboard Control Commands
81+
enter-bios:
82+
desc: "Send F12 key to enter BIOS boot menu"
83+
modules:
84+
- module: pikvm
85+
main: true
86+
args:
87+
- key
88+
- F12
89+
options:
90+
host: https://pikvm.local
91+
user: admin
92+
password: admin
93+
94+
ctrl-alt-del:
95+
desc: "Send Ctrl+Alt+Delete key combination"
96+
modules:
97+
- module: pikvm
98+
main: true
99+
args:
100+
- combo
101+
- Ctrl+Alt+Delete
102+
options:
103+
host: https://pikvm.local
104+
user: admin
105+
password: admin
106+
107+
# Virtual Media Commands
108+
mount-iso:
109+
desc: "Mount an ISO image from local filesystem"
110+
modules:
111+
- module: pikvm
112+
main: true
113+
args:
114+
- mount
115+
- /path/to/image.iso
116+
options:
117+
host: https://pikvm.local
118+
user: admin
119+
password: admin
120+
121+
mount-iso-url:
122+
desc: "Mount an ISO image from URL"
123+
modules:
124+
- module: pikvm
125+
main: true
126+
args:
127+
- mount-url
128+
- https://example.com/os.iso
129+
options:
130+
host: https://pikvm.local
131+
user: admin
132+
password: admin
133+
134+
unmount-media:
135+
desc: "Unmount virtual media"
136+
modules:
137+
- module: pikvm
138+
main: true
139+
args:
140+
- unmount
141+
options:
142+
host: https://pikvm.local
143+
user: admin
144+
password: admin
145+
146+
media-info:
147+
desc: "Show mounted media information"
148+
modules:
149+
- module: pikvm
150+
main: true
151+
args:
152+
- media-status
153+
options:
154+
host: https://pikvm.local
155+
user: admin
156+
password: admin

0 commit comments

Comments
 (0)