Skip to content

Commit e67bfbc

Browse files
author
Adam Delo
authored
Merge pull request #13 from ol3d/release/v1.2.0
Release/v1.2.0
2 parents 8fec799 + 73e347b commit e67bfbc

14 files changed

+220
-185
lines changed

‎.github/linters/.markdownlint.yaml

-2
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,6 @@ MD013:
1515
tables: true
1616
# Include headings
1717
headings: true
18-
# Include headings
19-
headers: true
2018
# Strict length checking
2119
strict: false
2220
# Stern length checking

‎.github/workflows/link-checker.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ jobs:
3434
- name: Update Issue
3535
uses: peter-evans/create-issue-from-file@v5
3636
with:
37-
title: Broken links detected in docs
37+
title: Link Checker
3838
issue-number: "${{ steps.link-checker-issue.outputs.issue-number }}"
3939
content-filepath: ./lychee/out.md
4040
token: "${{ steps.generate-token.outputs.token }}"

‎README.md

+39-57
Original file line numberDiff line numberDiff line change
@@ -27,79 +27,61 @@ The following PiKVM version(s) are currently unsupported and may not work with t
2727

2828
## Role Variables
2929

30-
`oled.enabled` By setting this value to **true**, it enables the physical OLED screen on the PiKVM device. By default this is set to **false** since not all PiKVM devices utilize an OLED screen.
30+
`oled_enabled` By setting this value to **true**, it enables the physical OLED screen on the PiKVM device. By default this is set to **false** since not all PiKVM devices utilize an OLED screen.
3131

32-
`oled.rotate` By setting this value to **true**, the PiKVM OLED screen will be rotated. This is useful if the screen is the incorrect orientation from which you want displayed. For this setting to be applied, `oled.enabled` must be set to **true**. By default this value is set to **false**.
32+
`oled_rotate` By setting this value to **true**, the PiKVM OLED screen will be rotated. This is useful if the screen is the incorrect orientation from which you want displayed. For this setting to be applied, `oled_enabled` must be set to **true**. By default this value is set to **false**.
3333

34-
`oled.fahrenheit` By setting this value to **true**, the PiKVM OLED screen will display temperature in Fahrenheit units instead of Celcius. For this setting to be applied, `oled.enabled` must be set to **true**. By default this value is set to **false**.
34+
`oled_fahrenheit` By setting this value to **true**, the PiKVM OLED screen will display temperature in Fahrenheit units instead of Celcius. For this setting to be applied, `oled_enabled` must be set to **true**. By default this value is set to **false**.
3535

36-
`fan.enabled` By setting this value to **true**, the PiKVM will activate the FAN header pins allowing power to a physical fan. By default this is set to **true** since the PiKVM is recommended to have active cooling.
36+
`fan_enabled` By setting this value to **true**, the PiKVM will activate the FAN header pins allowing power to a physical fan. By default this is set to **true** since the PiKVM is recommended to have active cooling.
3737

38-
`web_terminal.enabled` By setting this value to **true**, the PiKVM WebUI will enable terminal access. If set to false, no terminal actions can be performed from within the WebUI and must be performed by the root user using SSH. By default this is set to **true** to allow WebUI admin terminal access. ***Warning - All WebUI users have the same access rights. This means that any additional users besides the default admin account created for the WebUI will also have full access to the terminal.***
38+
`web_terminal_enabled` By setting this value to **true**, the PiKVM WebUI will enable terminal access. If set to false, no terminal actions can be performed from within the WebUI and must be performed by the root user using SSH. By default this is set to **true** to allow WebUI admin terminal access. ***Warning - All WebUI users have the same access rights. This means that any additional users besides the default admin account created for the WebUI will also have full access to the terminal.***
3939

4040
`pikvm_os_update_output_logs` By setting this value to **true**, during execution of this role, the system update output will be displayed within the ansible logs. This can be useful to see what packages are updated during role execution. By default this is set to **true**.
4141

42-
`hdmi.edid.custom` If set, a custom HDMI EDID value will override the PiKVM default. By default, the EDID value will be set based on the PiKVM OS version.
42+
`hdmi_edid` If set, a custom HDMI EDID value will override the PiKVM default. By default, the EDID value will be set based on the PiKVM OS version.
4343

44-
`hdmi.passthrough.enabled` This option is only available for PiKVM V4 Plus. By setting this value to **false**, the OUT2 port on the back side of the PiKVM V4 Plus will be disabled. By default this option is set to **true**. To enable this setting, `kvmd_override.enabled` must also be set to **true**.
44+
`hdmi_passthrough_enabled` This option is only available for PiKVM V4 Plus. By setting this value to **false**, the OUT2 port on the back side of the PiKVM V4 Plus will be disabled. By default this option is set to **true**. To enable this setting, `kvmd_override_enabled` must also be set to **true**.
4545

46-
`validate.validators.system` By setting this value to **true**, this role will validate the PiKVM required files and system packages before configuring anything. When using an official PiKVM OS provided by PiKVM, this should pass without issue, however, by setting this value to **true**, it ensures that any custom OS is able to be properly configured. By default this is set to **true**.
46+
`mouse_jiggler_enabled` By setting this value to **true**, the virtual mouse jiggler will be available for use within the WebUI. By default this value is set to **false**. This setting does not turn ON the mouse jiggler, instead, it allows the user to activate it manually. To enable this setting, `kvmd_override_enabled` must also be set to **true**.
4747

48-
`validate.validators.prometheus` By default PiKVM allows Prometheus scraping by exposing metrics on the `/api/export/prometheus/metrics` endpoint. By setting this value to **true**, this role will validate that the metrics endpoint is available and correctly configured. By default this is set to **true**.
48+
`mouse_jiggler_on_after_reboot` By setting this value to **true**, the virtual mouse jiggler will become active after reboot. By default this value is set to **false**. This setting turns ON the mouse jiggler by default after reboot. If you wish to have manual control over the activation of this setting after reboot, do not set this value to true. `mouse_jiggler_enabled` must be set to **true** for this setting to be applied. To enable this setting, `kvmd_override_enabled` must also be set to **true**.
4949

50-
`validate.fail_on_validate` By setting this value to **true**, any validators that fail will stop the role from continuing execution. This is helpful to prevent unknown issues from occuring during role execution if a validator fails. By default this is set to **true**.
50+
`kvmd_override_enabled` By setting this value to **true**, the current override file within /etc/kvmd/override.yaml will be overwritten to match this roles config. By default this value is set to **false**.
5151

52-
`hid.mouse.jiggler.enabled` By setting this value to **true**, the virtual mouse jiggler will be available for use within the WebUI. By default this value is set to **false**. This setting does not turn ON the mouse jiggler, instead, it allows the user to activate it manually. To enable this setting, `kvmd_override.enabled` must also be set to **true**.
53-
54-
`hid.mouse.jiggler.on_after_reboot` By setting this value to **true**, the virtual mouse jiggler will become active after reboot. By default this value is set to **false**. This setting turns ON the mouse jiggler by default after reboot. If you wish to have manual control over the activation of this setting after reboot, do not set this value to true. `hid.mouse.jiggler.enabled` must be set to **true** for this setting to be applied. To enable this setting, `kvmd_override.enabled` must also be set to **true**.
55-
56-
`kvmd_override.enabled` By setting this value to **true**, the current override file within /etc/kvmd/override.yaml will be overwritten to match this roles config. By default this value is set to **false**.
52+
`serial_over_usb_enabled` By setting this value to **true**, the PiKVM will be configured to allow serial connections over USB. This can be used for terminal access from the managed server to the PiKVM, or for any other purpose that requires a serial connection. This is only available for PiKVM V2+.
5753

5854
### Example Variable Usage
5955

6056
```yaml
61-
oled:
62-
enabled: true
63-
rotate: false
64-
fahrenheit: false
65-
fan:
66-
enabled: true
67-
web_terminal:
68-
enabled: false
57+
oled_enabled: true
58+
oled_rotate: false
59+
oled_fahrenheit: false
60+
fan_enabled: true
61+
web_terminal_enabled: false
6962
pikvm_os_update_output_logs: true
70-
hdmi:
71-
edid:
72-
custom: |
73-
00FFFFFFFFFFFF005262888800888888
74-
1C150103800000780AEE91A3544C9926
75-
0F505425400001000100010001000100
76-
010001010101D32C80A070381A403020
77-
350040442100001E7E1D00A050001940
78-
3020370080001000001E000000FC0050
79-
492D4B564D20566964656F0A000000FD
80-
00323D0F2E0F000000000000000001C4
81-
02030400DE0D20A03058122030203400
82-
F0B400000018E01500A0400016303020
83-
3400000000000018B41400A050D01120
84-
3020350080D810000018AB22A0A05084
85-
1A3030203600B00E1100001800000000
86-
00000000000000000000000000000000
87-
00000000000000000000000000000000
88-
00000000000000000000000000000045
89-
passthrough:
90-
enabled: false
91-
validate:
92-
validators:
93-
system: true
94-
prometheus: true
95-
fail_on_validate: false
96-
hid:
97-
mouse:
98-
jiggler:
99-
enabled: true
100-
on_after_reboot: true
101-
kvmd_override:
102-
enabled: true
63+
hdmi_edid: |
64+
00FFFFFFFFFFFF005262888800888888
65+
1C150103800000780AEE91A3544C9926
66+
0F505425400001000100010001000100
67+
010001010101D32C80A070381A403020
68+
350040442100001E7E1D00A050001940
69+
3020370080001000001E000000FC0050
70+
492D4B564D20566964656F0A000000FD
71+
00323D0F2E0F000000000000000001C4
72+
02030400DE0D20A03058122030203400
73+
F0B400000018E01500A0400016303020
74+
3400000000000018B41400A050D01120
75+
3020350080D810000018AB22A0A05084
76+
1A3030203600B00E1100001800000000
77+
00000000000000000000000000000000
78+
00000000000000000000000000000000
79+
00000000000000000000000000000045
80+
hdmi_passthrough_enabled: false
81+
mouse_jiggler_enabled: true
82+
mouse_jiggler_on_after_reboot: false
83+
kvmd_override_enabled: true
84+
serial_over_usb_enabled: false
10385
```
10486
10587
## Example Playbook
@@ -139,7 +121,7 @@ This role will update system packages if available to the most recent version. T
139121
140122
This role will cause the PiKVM to reboot if required. This action cannot currently be disabled.
141123
142-
If `kvmd_override.enabled` is set to **true**, the current /etc/kvmd/override.yaml file will be overwritten and cannot be recovered. Please ensure that you have a backup of the current override.yaml file.
124+
If `kvmd_override_enabled` is set to **true**, the current /etc/kvmd/override.yaml file will be overwritten and cannot be recovered. Please ensure that you have a backup of the current override.yaml file.
143125

144126
**Warning**: By using this role, you acknowledge that it may impact any existing installations or configurations on your PiKVM device. This role and its contributors are not responsible for any data loss, configuration changes, or other issues that may arise. Use at your own risk and ensure you have appropriate backups and safeguards in place before running this role on a production device.
145127

‎defaults/main.yml

+11-25
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,13 @@
11
---
2-
oled:
3-
enabled: false
4-
rotate: false
5-
fahrenheit: false
6-
fan:
7-
enabled: true
8-
web_terminal:
9-
enabled: true
2+
oled_enabled: false
3+
oled_rotate: false
4+
oled_fahrenheit: false
5+
fan_enabled: true
6+
web_terminal_enabled: true
107
pikvm_os_update_output_logs: true
11-
hdmi:
12-
edid:
13-
custom: null
14-
passthrough:
15-
enabled: false
16-
validate:
17-
validators:
18-
system: true
19-
prometheus: true
20-
fail_on_validate: false
21-
hid:
22-
mouse:
23-
jiggler:
24-
enabled: false
25-
on_after_reboot: false
26-
kvmd_override:
27-
enabled: false
8+
hdmi_edid: null
9+
hdmi_passthrough_enabled: false
10+
mouse_jiggler_enabled: false
11+
mouse_jiggler_on_after_reboot: false
12+
kvmd_override_enabled: false
13+
serial_over_usb_enabled: false

‎tasks/edid-config.yml

+6-6
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,11 @@
99
decoded_current_edid: "{{ current_edid.content | b64decode }}"
1010

1111
- name: EDID Config - Set EDID to default value
12-
when: (hdmi.edid.custom | default("") | length == 0)
12+
when: (hdmi_edid is none)
1313
block:
1414
- name: EDID Config - Read the default EDID file
1515
ansible.builtin.slurp:
16-
src: "/usr/share/kvmd/configs.default/kvmd/edid/{{ pikvm_version_mapped }}.hex"
16+
src: "/usr/share/kvmd/configs.default/kvmd/edid/{{ pikvm_version }}.hex"
1717
register: default_edid
1818

1919
- name: EDID Config - Set current EDID value to default
@@ -34,17 +34,17 @@
3434

3535
- name: EDID Config - Set EDID to custom value
3636
when: >
37-
(hdmi.edid.custom | default("") | length > 0)
38-
and (hdmi.edid.custom != decoded_current_edid)
37+
(hdmi_edid is not none)
38+
and (hdmi_edid != decoded_current_edid)
3939
block:
4040
- name: EDID Config - Mount filesystem Read Write (rw)
4141
ansible.builtin.import_tasks: shared/filesystem-mode.yml
4242
vars:
4343
fs_mode: rw
4444

45-
- name: EDID Config - Override tc358743-edid hex file with custom EDID value if not the same
45+
- name: EDID Config - Override tc358743-edid hex file with EDID value if not the same
4646
ansible.builtin.copy:
47-
content: "{{ hdmi.edid.custom }}"
47+
content: "{{ hdmi_edid }}"
4848
dest: /etc/kvmd/tc358743-edid.hex
4949
mode: "0640"
5050
force: true

‎tasks/fan-config.yml

+3-3
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@
66

77
- name: Fan Config - PiKVM fan configuration block
88
when: >
9-
(kvmd_fan_status.status.UnitFileState == 'disabled' and fan.enabled | bool) or
10-
(kvmd_fan_status.status.UnitFileState == 'enabled' and not fan.enabled | bool)
9+
(kvmd_fan_status.status.UnitFileState == 'disabled' and fan_enabled | bool) or
10+
(kvmd_fan_status.status.UnitFileState == 'enabled' and not fan_enabled | bool)
1111
block:
1212
- name: Fan Config - Mount filesystem Read Write (rw)
1313
ansible.builtin.import_tasks: shared/filesystem-mode.yml
@@ -17,5 +17,5 @@
1717
- name: Fan Config - Manage kvmd-fan service
1818
ansible.builtin.systemd:
1919
name: kvmd-fan
20-
enabled: "{{ fan.enabled }}"
20+
enabled: "{{ fan_enabled }}"
2121
notify: Reboot PiKVM

‎tasks/main.yml

+10-32
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,33 @@
11
---
22
- name: Validate System
33
ansible.builtin.import_tasks: validate/system-validate.yml
4-
when: (validate.validators.system | bool)
5-
6-
- name: Validate Prometheus
7-
ansible.builtin.import_tasks: validate/prometheus-validate.yml
8-
when: (validate.validators.prometheus | bool)
9-
10-
- name: Check and extract PiKVM OS version
11-
ansible.builtin.shell:
12-
cmd: set -o pipefail && pacman -Q | grep -oP 'kvmd-platform-(v[0-9]+|v4mini|v4plus)'
13-
register: kvmd_platform_version_raw
14-
changed_when: false
15-
failed_when: kvmd_platform_version_raw.rc != 0
16-
17-
- name: Define PiKVM OS version mapping
18-
ansible.builtin.set_fact:
19-
pikvm_version_map:
20-
v0: "v0"
21-
v1: "v1"
22-
v2: "v2"
23-
v3: "v3"
24-
v4mini: "v4mini"
25-
v4plus: "v4plus"
26-
27-
- name: Set the mapped PiKVM OS version
28-
ansible.builtin.set_fact:
29-
pikvm_version_mapped: "{{ pikvm_version_map.get(kvmd_platform_version_raw.stdout | regex_replace('^kvmd-platform-', ''), 'unknown') }}"
304

315
- name: Update all system packages
326
ansible.builtin.import_tasks: system-updates.yml
337

34-
- name: Configure PiKVM Physical Fan
35-
ansible.builtin.import_tasks: fan-config.yml
36-
378
- name: Configure PiKVM Physical OLED Screen
389
ansible.builtin.import_tasks: oled-config.yml
3910

11+
- name: Configure PiKVM Physical Fan
12+
ansible.builtin.import_tasks: fan-config.yml
13+
4014
- name: Manage web terminal
4115
ansible.builtin.import_tasks: web-terminal-config.yml
4216

17+
- name: Configure serial-over-usb
18+
ansible.builtin.import_tasks: serial-over-usb-config.yml
19+
when: (pikvm_version_mapped in v2_incremental_list)
20+
4321
- name: Configure EDID file
4422
ansible.builtin.import_tasks: edid-config.yml
4523
vars:
46-
pikvm_version_mapped: "{{ pikvm_version_mapped | default('unknown') }}"
24+
pikvm_version: "{{ pikvm_version_mapped }}"
4725

4826
- name: Configure KVMD Override
4927
ansible.builtin.import_tasks: kvmd-override-config.yml
5028
vars:
51-
pikvm_version_mapped: "{{ pikvm_version_mapped | default('unknown') }}"
52-
when: (kvmd_override.enabled | bool)
29+
pikvm_version: "{{ pikvm_version_mapped }}"
30+
when: (kvmd_override_enabled | bool)
5331

5432
- name: Force mount filesystem Read Write (ro)
5533
ansible.builtin.import_tasks: shared/filesystem-mode.yml

‎tasks/oled-config.yml

+16-16
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,12 @@
1717
- name: OLED Config - Check filesystem change required for OLED services
1818
ansible.builtin.set_fact:
1919
oled_kvmd_change_required: "{{
20-
(kvmd_oled_status.status.UnitFileState == 'disabled' and oled.enabled | bool) or
21-
(kvmd_oled_status.status.UnitFileState == 'enabled' and not oled.enabled | bool) or
22-
(kvmd_oled_reboot_status.status.UnitFileState == 'disabled' and oled.enabled | bool) or
23-
(kvmd_oled_reboot_status.status.UnitFileState == 'enabled' and not oled.enabled | bool) or
24-
(kvmd_oled_shutdown_status.status.UnitFileState == 'disabled' and oled.enabled | bool) or
25-
(kvmd_oled_shutdown_status.status.UnitFileState == 'enabled' and not oled.enabled | bool)
20+
(kvmd_oled_status.status.UnitFileState == 'disabled' and oled_enabled | bool) or
21+
(kvmd_oled_status.status.UnitFileState == 'enabled' and not oled_enabled | bool) or
22+
(kvmd_oled_reboot_status.status.UnitFileState == 'disabled' and oled_enabled | bool) or
23+
(kvmd_oled_reboot_status.status.UnitFileState == 'enabled' and not oled_enabled | bool) or
24+
(kvmd_oled_shutdown_status.status.UnitFileState == 'disabled' and oled_enabled | bool) or
25+
(kvmd_oled_shutdown_status.status.UnitFileState == 'enabled' and not oled_enabled | bool)
2626
}}"
2727

2828
- name: OLED Config - Check if kvmd-oled override file exists
@@ -45,8 +45,8 @@
4545
ExecStart=
4646
ExecStart=/usr/bin/kvmd-oled --clear-on-exit{{ rotate_option }}{{ fahrenheit_option }}
4747
vars:
48-
rotate_option: "{{ ' --height=32 --rotate=2' if oled.rotate | bool else '' }}"
49-
fahrenheit_option: "{{ ' --fahrenheit' if oled.fahrenheit | bool else '' }}"
48+
rotate_option: "{{ ' --height=32 --rotate=2' if oled_rotate | bool else '' }}"
49+
fahrenheit_option: "{{ ' --fahrenheit' if oled_fahrenheit | bool else '' }}"
5050

5151
- name: OLED Config - Set all relevant OLED configuration facts
5252
ansible.builtin.set_fact:
@@ -57,17 +57,17 @@
5757
ansible.builtin.set_fact:
5858
oled_override_change_required: >-
5959
{{
60-
oled.enabled and
61-
((oled.rotate | bool or oled.fahrenheit | bool) and
60+
oled_enabled and
61+
((oled_rotate | bool or oled_fahrenheit | bool) and
6262
(current_oled_override_normalized != desired_oled_override_normalized))
6363
}}
6464
6565
- name: OLED Config - OLED override removal required
6666
ansible.builtin.set_fact:
6767
oled_override_removal_required: >-
6868
{{
69-
((not oled.rotate | bool and not oled.fahrenheit | bool) or
70-
(not oled.enabled | bool)) and
69+
((not oled_rotate | bool and not oled_fahrenheit | bool) or
70+
(not oled_enabled | bool)) and
7171
(oled_override_file.stat.exists | default(false))
7272
}}
7373
@@ -85,7 +85,7 @@
8585
- name: OLED Config - Manage OLED services
8686
ansible.builtin.systemd:
8787
name: "{{ item }}"
88-
enabled: "{{ oled.enabled }}"
88+
enabled: "{{ oled_enabled }}"
8989
loop:
9090
- kvmd-oled
9191
- kvmd-oled-reboot
@@ -112,9 +112,9 @@
112112
ExecStart=/usr/bin/kvmd-oled --clear-on-exit{{ rotate_option }}{{ fahrenheit_option }}
113113
mode: "0640"
114114
vars:
115-
rotate_option: "{{ ' --height=32 --rotate=2' if oled.rotate | bool else '' }}"
116-
fahrenheit_option: "{{ ' --fahrenheit' if oled.fahrenheit | bool else '' }}"
117-
when: (oled.rotate | bool) or (oled.fahrenheit | bool)
115+
rotate_option: "{{ ' --height=32 --rotate=2' if oled_rotate | bool else '' }}"
116+
fahrenheit_option: "{{ ' --fahrenheit' if oled_fahrenheit | bool else '' }}"
117+
when: (oled_rotate | bool) or (oled_fahrenheit | bool)
118118

119119
- name: OLED Config - Remove kvmd-oled override file
120120
when: (oled_override_removal_required | bool)

0 commit comments

Comments
 (0)