From e8ef744f59c50f36a46cac59d5722b63e9303d3f Mon Sep 17 00:00:00 2001 From: Raphael Dannecker Date: Thu, 20 Mar 2025 21:17:22 +0100 Subject: [PATCH] Provide documenation --- doc/exam_mode.md | 27 +++++++ doc/vm_support.md | 45 +++++++++++ doc/wlan.md | 186 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 258 insertions(+) create mode 100644 doc/exam_mode.md create mode 100644 doc/vm_support.md create mode 100644 doc/wlan.md diff --git a/doc/exam_mode.md b/doc/exam_mode.md new file mode 100644 index 0000000..cfb64e6 --- /dev/null +++ b/doc/exam_mode.md @@ -0,0 +1,27 @@ +# exam_mode + +## Description / use cases + +Activating exam_mode provides following functionalities: +* when -exam user logs in, firewalld.service will start and prevent communication between devices in the same local network +* home- and media-directory of -exam users will be renamed (on the next day) and removed (after some days).\ + This is important due the fact, that -exam user will be new created (with new user-id) on exam-mode initialisation.\ + Without renaming/deleting the home- and media-directory, the -exam user couldn't log in twice on the same pc.\ + Particularly important on machines with localhome + +## Requirements + +none + +## Example + +Per default, all hosts will get exam_mode. But we don't want exam_mode on teacher devices + +inventory.yml +``` +teacherdevices: + hosts: + 10.0.14.[1..75] + vars: + exam_mode: false +``` diff --git a/doc/vm_support.md b/doc/vm_support.md new file mode 100644 index 0000000..5eff05d --- /dev/null +++ b/doc/vm_support.md @@ -0,0 +1,45 @@ +# VM support + +lmn_client provides scripts to +* create +* modify +* distribute +* run + +VMs based on Qemu/KVM in school network. + +## Requirements + +* For distribution of VMs, you have to run a `seedbox` with aria2 server (torrent server).\ + Repository with ansible-playbook for seedbox install: https://codeberg.org/digitalsouveraeneschule/... +* `seedbox`-hostname must be resolvable via DNS + +## Activation / Default + +### To enable VM support: + +``` +vm_support: true +``` + +Default: `vm_support: false + +### Torrent Server +``` +torrent_srv: "myseedbox.linuxmuster.net" +``` + +Default: `torrent_srv: "seedbox.{{ domain }}"` + + +## Example + +Enable VM support on all clients. + +inventory.yml +``` +all: + vars: + vm_support: true + torrent_srv: "myseedbox.linuxmuster.net" # default: seedbox.{{ domain }} +``` diff --git a/doc/wlan.md b/doc/wlan.md new file mode 100644 index 0000000..f848512 --- /dev/null +++ b/doc/wlan.md @@ -0,0 +1,186 @@ +# WLAN support + +Supported modes authenticating via WLAN: + +* **WPA-Personal** (WPA-PSK)\ + authentication via preshared key (psk) +* **WPA-Enterprise** (WPA-802.1x) with **EAP-TLS**\ + authentication via client certificates (eap-tls) + +Which method is used is determined by the variable `wlan` + +Choices: +* `"none"` <- (default) +* `"psk"` +* `"eap-tls"` + +## WPA-Personal + +### Requirements + +WLAN with configured WPA-Personal (WPA-PSK) + +### Configuration / Variables + + * **wlan** + Authentication mode + Type: *String* + Values: + * "none" <-- (default) + * "psk" <-- set to use WPA-Personal + * "eap-tls" + * **wlan_ssid** + SSID of used WLAN + Type: *String* + * **wlan_password** + Password of WLAN. Only for `wlan: "psk"` + Type: *String* + +### Examples + +#### One class of devices with wlan access + +inventory.yml +```yaml +laptop: + hosts: + 10.0.13.[1-28]: + vars: + wlan: "psk" + wlan_ssid: "devicesPSK" + wlan_password: "topsecretpasswd" +``` + +#### Two device classes with different wlan access + +inventory.yml +```yaml +laptop_students: + hosts: + 10.0.13.[1-28]: + vars: + wlan: "psk" + wlan_ssid: "Students" + wlan_password: "topsecretpasswd1" +laptop_teachers: + hosts: + 10.0.23.[1-82]: + vars: + wlan: "psk" + wlan_ssid: "Teachers" + wlan_password: "topsecretpasswd2" +``` + +## WPA-Enterprise with EAP-TLS + +Authentication is based on individual certificates, which will be automaticaly created on the radius server. +Every devices gets his own certificate. When creating new certificates, the old one will be revoked. + +### Requirements + + * You need to run a freeradius server. For installation see https://codeberg.... + * The user, running this playbook, must have access to the radius-Server via ssh. + +### Configuration / Variables + + * **wlan** + Authentication mode + Type: *String* + Values: + * "none" <-- (default) + * "psk" + * "eap-tls" <-- set to use WPA Enterprise with EAP-TLS + * **wlan_ssid** + SSID of used WLAN + Type: *String* + * **wlan_eap_ca** + CA data for certs and crl + Type: *Dictionary of Strings* + Keys: + * C <-- default: "DE" + * ST <-- default: "Baden-Wuerttemberg" + * L <-- default: "Reutlingen" + * O <-- default: "Linuxschule" + * emailAddress <-- default: "admin@example.com" + * CN <-- default: "Radius Certificate Authority" + * password <-- default: "OtherVerySecurePassw0rd" + * **wlan_force_issue** + Force to issue a new certificate + Only for `wlan: "eap-tls"` + Type: *Bolean* + Values: + * true + * false <-- (default) + +### Examples + +inventory.yml: +```yaml +infrastructure: + hosts: + radius_server: + ansible_host: 10.0.0.15 + ansible_user: ansible +laptop: + vars: + wlan: "eap-tls" + wlan_ssid: "devices8021x" + wlan_eap_ca: + C: "DE" + ST: "Baden-Wuerttemberg" + L: "Reutlingen" + O: "Linuxschule" + emailAddress: "admin@example.com" + CN: "Radius Certificate Authority" + password: "secret4radiusCA" +``` + +## complex example with both modes + +We have three groups of devices (one with psk, two with eap-tls): + +inventory.yml +```yaml +all: + vars: + wlan_ssid: "WLAName" # teacher and staff are using the same ssid + radiusca_password: "secret4radiusCA" + country_name: "DE" + state_or_province_name: "Baden-Württemberg" + locality_name: "Stuttgart" + organization_name: "Baumschule" + admin_email: "admin@example.com" + +infrastructure: + hosts: + radius_server: + ansible_host: 10.0.0.15 + ansible_user: ansible + +laptop_students: + hosts: + 10.0.13.[1-28]: + vars: + wlan: "psk" + wlan_ssid: "Students" # ssid "WLAN" from group "all" will be overwritten + wlan_password: "topsecretpasswd" +laptop_teachers: + hosts: + 10.0.23.[1-82]: + vars: + wlan: "eap-tls" +laptop_staff: + hosts: + 10.0.61.[1-20]: + vars: + wlan: "eap-tls" +``` + +## example: Force issue of new certs + +The issue of certificates can be forced. + +Force issue of new certs for hosts in group laptop_teacher. +If there is a valid certificate, the old one will be revoked and a new certificate will be issued. + + ansible-playbook -i myinventory.yml -l laptop_teachers lmn-client.yml -e "wlan_force_issue=true"