Improve documentation
This commit is contained in:
Raphael Dannecker
parent
471ff52df0
commit
9a6a05e2d0
11 changed files with 195 additions and 84 deletions
12
README.md
12
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
|
||||
|
|
|
|||
|
|
@ -5,9 +5,9 @@
|
|||
|
||||
## Configuration / Variables
|
||||
|
||||
* **custom_roles**
|
||||
List of roles which will be applied
|
||||
Type: *List of Strings*
|
||||
* **custom_roles**
|
||||
List of roles which will be applied
|
||||
Type: *List of Strings*
|
||||
Default: []
|
||||
|
||||
|
||||
|
|
@ -48,4 +48,3 @@ laptops:
|
|||
- role_a
|
||||
- role_b
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -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).\
|
||||
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.\
|
||||
* 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
|
||||
|
|
|
|||
53
doc/install_ontop.md
Normal file
53
doc/install_ontop.md
Normal file
|
|
@ -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`
|
||||
50
doc/install_pxe.md
Normal file
50
doc/install_pxe.md
Normal file
|
|
@ -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
|
||||
|
|
@ -16,26 +16,23 @@ To enable the local home directory, set the variable `localhome` to `true` (defa
|
|||
|
||||
## Configuration / Variables
|
||||
|
||||
* **localhome**
|
||||
This flag indicates whether to use home on local disk.
|
||||
If set to `true` local user's home will be on local disk.
|
||||
Type: *Boolean*
|
||||
* **localhome**
|
||||
This flag indicates whether to use home on local disk.
|
||||
If set to `true` local user's home will be on local disk.
|
||||
Type: *Boolean*
|
||||
Values:
|
||||
* `false` <-- (default)
|
||||
* `true`
|
||||
* **localhome_logout_missing_serverhome**
|
||||
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.
|
||||
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.
|
||||
Type:: *Boolean*
|
||||
* **localhome_logout_missing_serverhome**
|
||||
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.
|
||||
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.
|
||||
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).
|
||||
|
|
|
|||
|
|
@ -15,16 +15,16 @@ Default: `firewall.{{ domain }}`
|
|||
|
||||
## Configuration / Variables
|
||||
|
||||
* **localproxy**
|
||||
This flag indicates whether to install the local proxy.
|
||||
If set to `true` local Squid proxy will be installed.
|
||||
Type: *Boolean*
|
||||
* **localproxy**
|
||||
This flag indicates whether to install the local proxy.
|
||||
If set to `true` local Squid proxy will be installed.
|
||||
Type: *Boolean*
|
||||
Values:
|
||||
* `false` <-- (default)
|
||||
* "username"
|
||||
* **localproxy_parent**
|
||||
This variable specifies the name of the parent HTTP proxy that accepts the user's Kerberos ticket.
|
||||
Default: "firewall.{{ domain }}"
|
||||
* **localproxy_parent**
|
||||
This variable specifies the name of the parent HTTP proxy that accepts the user's Kerberos ticket.
|
||||
Default: "firewall.{{ domain }}"
|
||||
Type: *String*
|
||||
|
||||
## Example
|
||||
|
|
|
|||
|
|
@ -15,20 +15,20 @@ Default: `Muster!`
|
|||
|
||||
## Configuration / Variables
|
||||
|
||||
* **localuser**
|
||||
Username of local guest account
|
||||
If set to `false` no user will be created
|
||||
Type: *String*/*Boolean*
|
||||
* **localuser**
|
||||
Username of local guest account
|
||||
If set to `false` no user will be created
|
||||
Type: *String*/*Boolean*
|
||||
Values:
|
||||
* `false` <-- (default)
|
||||
* "username"
|
||||
* **localuser_password**
|
||||
Password of local guest user
|
||||
Default: "Muster!"
|
||||
* **localuser_password**
|
||||
Password of local guest user
|
||||
Default: "Muster!"
|
||||
Type: *String*
|
||||
* **localuser_secretsalt**
|
||||
Salt for creation of password hash
|
||||
Default: "4ANAxPycC3q"
|
||||
* **localuser_secretsalt**
|
||||
Salt for creation of password hash
|
||||
Default: "4ANAxPycC3q"
|
||||
Type: *String*
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
If the login screen appears on the wrong device, this can be corrected using the `dual_screen` 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.
|
||||
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**
|
||||
This flag indicates whether to prepare clonescreen mode.
|
||||
If set to `true` clonescreen will be default.
|
||||
Type: *Boolean*
|
||||
* **misc_clonescreen**
|
||||
This flag indicates whether to prepare clonescreen mode.
|
||||
If set to `true` clonescreen will be default.
|
||||
Type: *Boolean*
|
||||
Values:
|
||||
* `false` <-- (default)
|
||||
* "username"
|
||||
* **misc_clonescreen_mode**
|
||||
This variable specifies the resolution and frequency of display.
|
||||
Default: "1920x1080@60"
|
||||
Type: *String*
|
||||
* ** dual_screen **
|
||||
Array with X11 and Wayland naming of desired primary display.
|
||||
* **misc_clonescreen_mode**
|
||||
This variable specifies the resolution and frequency of display.
|
||||
Default: "1920x1080@60"
|
||||
Type: *String*
|
||||
* ** dual_screen **
|
||||
Array with X11 and Wayland naming of desired primary display.
|
||||
Type: *String*
|
||||
Example: [DisplayPort-3, DP-4]
|
||||
* ** audio_output **
|
||||
Array of audio-output device to be selected.
|
||||
* ** audio_output **
|
||||
Array of audio-output device to be selected.
|
||||
Example: [pci-0000_00_1f.3, analog-stereo]
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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**
|
||||
This flag indicates whether to activate VM support.
|
||||
Type: *Boolean*
|
||||
* **vm_support**
|
||||
This flag indicates whether to activate VM support.
|
||||
Type: *Boolean*
|
||||
Values:
|
||||
* `false` <-- (default)
|
||||
* `true`
|
||||
* **vm_torrent_serv**
|
||||
Name of the torrent server.
|
||||
Type: *String*
|
||||
* **vm_torrent_serv**
|
||||
Name of the torrent server.
|
||||
Type: *String*
|
||||
Default: `vm_torrent_serv: "seedbox.{{ domain }}"`
|
||||
* **vm_uploadseed_pwd**
|
||||
Password for upload-seed. Used for image upload to torrent-server.
|
||||
Type: *String*
|
||||
* **vm_uploadseed_pwd**
|
||||
Password for upload-seed. Used for image upload to torrent-server.
|
||||
Type: *String*
|
||||
Default: `secret = "token:topsecret"`
|
||||
|
||||
## Example
|
||||
|
|
|
|||
46
doc/wlan.md
46
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**
|
||||
Authentication mode
|
||||
Type: *String*
|
||||
* **wlan**
|
||||
Authentication mode
|
||||
Type: *String*
|
||||
Values:
|
||||
* "none" <-- (default)
|
||||
* "psk" <-- set to use WPA-Personal
|
||||
* "eap-tls" <-- set to use WPA-Enterprise with EAP-TLS
|
||||
* **wlan_ssid**
|
||||
SSID of used WLAN
|
||||
* **wlan_ssid**
|
||||
SSID of used WLAN
|
||||
Type: *String*
|
||||
* **wlan_enable_on_boot**
|
||||
If set to `true` wlan will be enabled on boot
|
||||
Type: *Boolean*
|
||||
* **wlan_enable_on_boot**
|
||||
If set to `true` wlan will be enabled on boot
|
||||
Type: *Boolean*
|
||||
Default: `true`
|
||||
|
||||
## WPA-Personal
|
||||
|
|
@ -39,8 +39,8 @@ WLAN with configured WPA-Personal (WPA-PSK)
|
|||
|
||||
### Additional Configuration / Variables
|
||||
|
||||
* **wlan_password**
|
||||
Password of WLAN. Only for `wlan: "psk"`
|
||||
* **wlan_password**
|
||||
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**
|
||||
CA data for certs and crl
|
||||
Type: *Dictionary of Strings*Keys:
|
||||
* **wlan_eap_ca**
|
||||
CA data for certs and crl
|
||||
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**
|
||||
Force to issue a new certificateOnly for `wlan: "eap-tls"`
|
||||
Type: *Bolean*
|
||||
* **wlan_force_issue**
|
||||
Force to issue a new certificateOnly for `wlan: "eap-tls"`
|
||||
Type: *Bolean*
|
||||
Values:
|
||||
* true
|
||||
* false <-- (default)
|
||||
* **wlan_eap_ca_crl**
|
||||
URL of the certificate revocation list
|
||||
Type: *String*
|
||||
* **wlan_eap_ca_crl**
|
||||
URL of the certificate revocation list
|
||||
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"
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue