trixie/doc/wlan.md

# 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"`

## Common Configuration / Variables

* **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  
  Type: *String*
* **wlan_enable_on_boot**  
  If set to `true` wlan will be enabled on boot  
  Type: *Boolean*  
  Default: `true`

## WPA-Personal

### Requirements

WLAN with configured WPA-Personal (WPA-PSK)

### Additional Configuration / Variables

* **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.

### Additional Configuration / Variables

* **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 certificateOnly for `wlan: "eap-tls"`  
  Type: *Bolean*  
  Values:
  * true
  * false <-- (default)
* **wlan_eap_ca_crl**  
  URL of the certificate revocation list  
  Type: *String*  
  Default: "http://radius.{{ domain }}/radius-ca.crl"

### 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"
    wlan_eap_ca_crl: "http://radius.example.com/radius-ca.crl"
```

## 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
    wlan_eap_ca:
      C: "DE"
      ST: "Baden-Wuerttemberg"
      L: "Reutlingen"
      O: "Linuxschule"
      emailAddress: "admin@example.com"
      CN: "Radius Certificate Authority"
      password: "secret4radiusCA"
    wlan_eap_ca_crl: "http://radius.example.com/radius-ca.crl"

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"
    wlan_enable_on_boot: false
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"