Improve documentation

README.md

@@ -20,11 +20,23 @@ Ansible playbooks and roles to deploy Debian clients for LinuxMuster.
   Starts local firewall and removes local directories of exam users the day after.
 * [localhome](doc/localhome.md)
   Sometimes a local home directory makes more sense than the home on a network share.
+* [localproxy](doc/localproxy.md)
+  Creates a http-proxy running in user context and authentication on parent with users krb5-ticket.
 * [localuser](doc/localuser.md)
   Creates a local guest user with home on tmpfs.
+* [misc_clonescreen](doc/misc_clonescreen.md)
+  CloneScreen on presenter PCs
 * [vm_support](doc/vm_support.md)
   VMs based on Qemu/KVM in school network.
 * [vpn](doc/vpn.md)
   Provides VPN access to school network.
 * [wlan](doc/wlan.md)
   Provides WLAN access via WPA Personal/Enterprise.
+
+## Installation
+
+Following possibilities:
+
+* [Install client via PXE-Boot](doc/install_pxe.md)
+* [Run playbook on existing client](doc/install_ontop.md)
+* Install client via USB-Stick including ansible-playbook

doc/custom_roles.md

@@ -5,9 +5,9 @@
 
 ## Configuration / Variables
 
-  * **custom_roles**
+  * **custom_roles**  
-    List of roles which will be applied
+    List of roles which will be applied  
-    Type: *List of Strings*
+    Type: *List of Strings*  
     Default: []
 
 
@@ -48,4 +48,3 @@ laptops:
       - role_a
       - role_b
 ```
-

doc/exam_mode.md

@@ -4,9 +4,9 @@
 
 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).\
+* 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.\
+  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.\
+  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

doc/install_ontop.md

@@ -0,0 +1,53 @@
+# Installation on existing client
+
+An easy method to test the lmn-client is to run the playbook manual on a fresh installed client.
+
+## Direct call via ansible-pull
+
+With two simple commands you can install the lmn-client with default configuration.
+
+Steps:
+
+* Install debian on client (via USB or PXE)
+* Install additional packages: ansible
+  `sudo apt install ansible`
+* Run Playbook
+  `ansible-pull -i inventory.yml -l localhost, --url=https://codeberg.org/DigitalSouveraeneSchule/lmn-client.git -C main lmn-client.yml`
+
+## Checkout git and run ansible locally
+
+When checking out the repository you can customize the installation by editing the inventory before run the playbook.  
+You can repeat the process as often as you like and gradually adapt your inventory settings to your needs.
+
+Steps:
+
+* Install debian on client (via USB or PXE)
+* Install additional packages: ansible, git  
+  `sudo apt install ansible git`
+* Checkout Repository
+  `git clone https://codeberg.org/DigitalSouveraeneSchule/lmn-client.git`
+* Create inventory  
+  `cp inventory.yml inventory-myschool.yml`
+* Edit inventory-myschool.yml  
+  e.g.: `nano inventory-myschool.yml`
+* Run Playbook  
+  `ansible-playbook -i inventory-myschool.yml -l localhost lmn-client.yml`
+
+## Run with other target device
+
+If you want to run the play on an other target pc:
+
+* You have to add the target IP or hostname in the inventory.
+* SSH access on target must be configured (deploy ssh public-key on target host)
+
+`ansible-playbook -i inventory-myschool.yml -l target lmn-client.yml`
+
+## Upload changes to your own remote repository
+
+If you are satisfied with your changes, you can upload the changes to your own remote repository.
+
+* Create new git repository on your git service (e.g. https://codeberg.org)
+* Add new remote origin  
+  `git remote add myorigin git@codeberg.org:myname/mylmn-client.git`
+* Push the repository to the new remote  
+  `push -u myorigin main`

doc/install_pxe.md

@@ -0,0 +1,50 @@
+# Installation via PXE/Grub
+
+* **Using DigitalSouveraeneSchule repository and LinuxMuster.Net tftp**  
+  Simplest solution. Playbook and default inventory from DigitalSouveraeneSchule codeberg repository.  
+  Linux kernel and initial Ramdisk from debian repository.
+* **Using your own repository and LinuxMuster.Net tftp**  
+  Here you can use your own inventory and make many custom settings.  
+  Linux kernel and initial Ramdisk from debian repository.
+* **Using your own repository and livebox tftp**  
+  Additional kernel and Ramdisk from your own infrastrukture.
+
+## Using codeberg repository and LinuxMuster.Net tftp
+
+### Modification LinuxMuster.Net server
+
+Create grub config for device group `lmnclient` on your schools server:
+
+/srv/linbo/boot/grub/lmnclient.cfg
+```
+# ### NOT managed by linuxmuster.net ###
+
+# edit to your needs
+set default=1
+
+menuentry 'Installer Debian bookworm (amd64) + preseed + ansible inventory' {
+   echo -n "Enter domain join password: "
+   read adpw
+   linux   (http,ftp.debian.org)/debian/dists/stable/main/installer-amd64/current/images/netboot/debian-installer/amd64/linux auto=true priority=high \
+           url=https://codeberg.org/DigitalSouveraeneSchule/lmn-client/raw/branch/fvs/misc/preseed.cfg interface=auto \
+           playbook=lmn-client.yml adpw="${adpw}" ---
+   initrd  (http,ftp.debian.org)/debian/dists/stable/main/installer-amd64/current/images/netboot/debian-installer/amd64/initrd.gz
+}
+```
+
+Insert host in devices.csv and set device group to `lmnclient`:
+
+devices.csv
+```
+classroom;mypc01;lmnclient;F2:81:6B:C9:E3:EF;10.0.5.51;;;;classroom-studentcomputer;;1;;;;;
+```
+
+### On client PC
+
+* In BIOS-Setting: Set boot to UEFI
+* Start via PXE
+* When asked for domain-join-password: Enter password of `global-admin`
+* confirm `hostname` and `domain` (you will be asked in network setup)
+* ... Get a cup of coffee ... wait until reboot ... login (Logging in may take a few minutes after installation)
+
+## Using your own livebox server

doc/localhome.md

@@ -16,26 +16,23 @@ To enable the local home directory, set the variable `localhome` to `true` (defa
 
 ## Configuration / Variables
 
-  * **localhome**
+  * **localhome**  
-    This flag indicates whether to use home on local disk.
+    This flag indicates whether to use home on local disk.  
-    If set to `true` local user's home will be on local disk.
+    If set to `true` local user's home will be on local disk.  
-    Type: *Boolean*
+    Type: *Boolean*  
     Values:
     * `false` <-- (default)
     * `true`
-  * **localhome_logout_missing_serverhome**
+  * **localhome_logout_missing_serverhome**  
-    If this flag is set to `true`, the user will be logged out if mounting the serverhome failed.
+    If this flag is set to `true`, the user will be logged out if mounting the serverhome failed.  
-    Sometimes mounting the server homes fails, but the user still logs in.
+    Sometimes mounting the server homes fails, but the user still logs in.  
-    For laptops used in schools, it's better to force the server home.
+    For laptops used in schools, it's better to force the server home.  
-    For teacher devices that can also be used outside of school, this flag must not be set.
+    For teacher devices that can also be used outside of school, this flag must not be set.  
-    Type:: *Boolean*
+    Type:: *Boolean*  
     Values:
     * `false`
     * `true` <-- (default)
 
-
-localhome_logout_missing_serverhome
-
 ## Example
 
 * Hosts in group `laptops` will get the localhome. Teacherlaptops will be part of the `laptop` group (children-entry).

doc/localproxy.md

@@ -15,16 +15,16 @@ Default: `firewall.{{ domain }}`
 
 ## Configuration / Variables
 
-  * **localproxy**
+  * **localproxy**  
-    This flag indicates whether to install the local proxy.
+    This flag indicates whether to install the local proxy.  
-    If set to `true` local Squid proxy will be installed.
+    If set to `true` local Squid proxy will be installed.  
-    Type: *Boolean*
+    Type: *Boolean*  
     Values:
     * `false` <-- (default)
     * "username"
-  * **localproxy_parent**
+  * **localproxy_parent**  
-    This variable specifies the name of the parent HTTP proxy that accepts the user's Kerberos ticket.
+    This variable specifies the name of the parent HTTP proxy that accepts the user's Kerberos ticket.  
-    Default: "firewall.{{ domain }}"
+    Default: "firewall.{{ domain }}"  
     Type: *String*
 
 ## Example

doc/localuser.md

@@ -15,20 +15,20 @@ Default: `Muster!`
 
 ## Configuration / Variables
 
-  * **localuser**
+  * **localuser**  
-    Username of local guest account
+    Username of local guest account  
-    If set to `false` no user will be created
+    If set to `false` no user will be created  
-    Type: *String*/*Boolean*
+    Type: *String*/*Boolean*  
     Values:
     * `false` <-- (default)
     * "username"
-  * **localuser_password**
+  * **localuser_password**  
-    Password of local guest user
+    Password of local guest user  
-    Default: "Muster!"
+    Default: "Muster!"  
     Type: *String*
-  * **localuser_secretsalt**
+  * **localuser_secretsalt**  
-    Salt for creation of password hash
+    Salt for creation of password hash  
-    Default: "4ANAxPycC3q"
+    Default: "4ANAxPycC3q"  
     Type: *String*
 
 

doc/misc_clonescreen.md

@@ -2,31 +2,31 @@
 
 Presentation PCs have a habit of displaying the primary screen on the wrong device. Furthermore, the workspace is extended by default instead of mirrored.
 
-These issues can be resolved using the 'misc_clonescreen' variable.
+These issues can be resolved using the 'misc_clonescreen' variable.  
-If the login screen appears on the wrong device, this can be corrected using the `dual_screen` variable.
+If the login screen appears on the wrong device, this can be corrected using the `dual_screen` variable.  
 Furthermore, the display devices are mirrored by default instead of extended.
 
 If the cabling does not properly support large screen resolutions, the desired resolution and refresh rate can be set.
 
 ## Configuration / Variables
 
-  * **misc_clonescreen**
+  * **misc_clonescreen**  
-    This flag indicates whether to prepare clonescreen mode.
+    This flag indicates whether to prepare clonescreen mode.  
-    If set to `true` clonescreen will be default.
+    If set to `true` clonescreen will be default.  
-    Type: *Boolean*
+    Type: *Boolean*  
     Values:
     * `false` <-- (default)
     * "username"
-  * **misc_clonescreen_mode**
+  * **misc_clonescreen_mode**  
-    This variable specifies the resolution and frequency of display.
+    This variable specifies the resolution and frequency of display.  
-    Default: "1920x1080@60"
+    Default: "1920x1080@60"  
-    Type: *String*
-  * ** dual_screen **
-    Array with X11 and Wayland naming of desired primary display.
     Type: *String*
+  * ** dual_screen **  
+    Array with X11 and Wayland naming of desired primary display.  
+    Type: *String*  
     Example: [DisplayPort-3, DP-4]
-  * ** audio_output **
+  * ** audio_output **  
-    Array of audio-output device to be selected.
+    Array of audio-output device to be selected.  
     Example: [pci-0000_00_1f.3, analog-stereo]
 
 

doc/vm_support.md

@@ -10,25 +10,25 @@ VMs based on Qemu/KVM in school network.
 
 ## Requirements
 
-* For distribution of VMs, you have to run a `seedbox` with aria2 server (torrent server).\
+* 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
 
 ## Configuration / Variables
 
-  * **vm_support**
+  * **vm_support**  
-    This flag indicates whether to activate VM support.
+    This flag indicates whether to activate VM support.  
-    Type: *Boolean*
+    Type: *Boolean*  
     Values:
     * `false` <-- (default)
     * `true`
-  * **vm_torrent_serv**
+  * **vm_torrent_serv**  
-    Name of the torrent server.
+    Name of the torrent server.  
-    Type: *String*
+    Type: *String*  
     Default: `vm_torrent_serv: "seedbox.{{ domain }}"`
-  * **vm_uploadseed_pwd**
+  * **vm_uploadseed_pwd**  
-    Password for upload-seed. Used for image upload to torrent-server.
+    Password for upload-seed. Used for image upload to torrent-server.  
-    Type: *String*
+    Type: *String*  
     Default: `secret = "token:topsecret"`
 
 ## Example

doc/wlan.md

@@ -2,9 +2,9 @@
 
 Supported modes authenticating via WLAN:
 
-* **WPA-Personal** (WPA-PSK)
+* **WPA-Personal** (WPA-PSK)  
   authentication via preshared key (psk)
-* **WPA-Enterprise** (WPA-802.1x) with **EAP-TLS**
+* **WPA-Enterprise** (WPA-802.1x) with **EAP-TLS**  
   authentication via client certificates (eap-tls)
 
 Which method is used is determined by the variable `wlan`
@@ -16,19 +16,19 @@ Choices:
 
 ## Common Configuration / Variables
 
-* **wlan**
+* **wlan**  
-  Authentication mode
+  Authentication mode  
-  Type: *String*
+  Type: *String*  
   Values:
   * "none" <-- (default)
   * "psk" <-- set to use WPA-Personal
   * "eap-tls" <-- set to use WPA-Enterprise with EAP-TLS
-* **wlan_ssid**
+* **wlan_ssid**  
-  SSID of used WLAN
+  SSID of used WLAN  
   Type: *String*
-* **wlan_enable_on_boot**
+* **wlan_enable_on_boot**  
-  If set to `true` wlan will be enabled on boot
+  If set to `true` wlan will be enabled on boot  
-  Type: *Boolean*
+  Type: *Boolean*  
   Default: `true`
 
 ## WPA-Personal
@@ -39,8 +39,8 @@ WLAN with configured WPA-Personal (WPA-PSK)
 
 ### Additional Configuration / Variables
 
-* **wlan_password**
+* **wlan_password**  
-  Password of WLAN. Only for `wlan: "psk"`
+  Password of WLAN. Only for `wlan: "psk"`  
   Type: *String*
 
 ### Examples
@@ -80,7 +80,7 @@ laptop_teachers:
 
 ## WPA-Enterprise with EAP-TLS
 
-Authentication is based on individual certificates, which will be automaticaly created on the radius server.
+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
@@ -90,9 +90,9 @@ Every devices gets his own certificate. When creating new certificates, the old
 
 ### Additional Configuration / Variables
 
-* **wlan_eap_ca**
+* **wlan_eap_ca**  
-  CA data for certs and crl
+  CA data for certs and crl  
-  Type: *Dictionary of Strings*Keys:
+  Type: *Dictionary of Strings*Keys:  
   * C <-- default: "DE"
   * ST <-- default: "Baden-Wuerttemberg"
   * L <-- default: "Reutlingen"
@@ -100,15 +100,15 @@ Every devices gets his own certificate. When creating new certificates, the old
   * emailAddress <-- default: "admin@example.com"
   * CN <-- default: "Radius Certificate Authority"
   * password <-- default: "OtherVerySecurePassw0rd"
-* **wlan_force_issue**
+* **wlan_force_issue**  
-  Force to issue a new certificateOnly for `wlan: "eap-tls"`
+  Force to issue a new certificateOnly for `wlan: "eap-tls"`  
-  Type: *Bolean*
+  Type: *Bolean*  
   Values:
   * true
   * false <-- (default)
-* **wlan_eap_ca_crl**
+* **wlan_eap_ca_crl**  
-  URL of the certificate revocation list
+  URL of the certificate revocation list  
-  Type: *String*
+  Type: *String*  
   Default: "http://radius.{{ domain }}/radius-ca.crl"
 
 ### Examples
@@ -184,7 +184,7 @@ laptop_staff:
 
 The issue of certificates can be forced.
 
-Force issue of new certs for hosts in group laptop_teacher.
+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"