ansible-install-server/README.md

# HW4F Netboot Installer

Server die automatische Installation über das Netzwerks von Ubuntu 20.04
im Rahmen des Projekts [https://hardwareforfuture.de](**Hardware for Future**)
des [https://dezentrale.space/](dezentrale e.V).

Für den Betrieb wird einmalig eine Internetverbindung benötigt.
Der Server wird über Ansible aufgesetzt.
Hierfür werden verschiedene Komponenten installiert,
u.a. FAI (Fully Automatic Installation).
Mit dem Server wird ein Netz aufgespannt,
welches für den Anschluß des zu installierenden Rechner verwendet wird.
Wenn die Rechner mit dem Netzwerk verbunden sind,
können sie über einen Netzwerkboot (F-Testen beim Start des Rechners) über PXE gebootet werden.
PXE lädt die erforderliche Dateien vom Server
und der FAI-Installer installiert dann Ubuntu auf den Rechner.

Es wird ein Nutzer `demo` angelegt.
Das Passwort ist `fai`.
Dieser Nutzer kann Administrationsrechte erlangen.
Das Passwort muss im Anschluss geändert werden.

## Voraussetzungen

Server:

* Debian Buster
* Zwei Netzwerkports oder zwei Netzwerkkarten (1x für WAN, 1x für LAN und FAI)

Zu installierende Clients:

* CPU mit x86-64 Unterstützung
* 512 MB RAM empfohlen
* mehr als 20 GB Festsplatte oder SSD
* PXE-fähig oder USB-Stick mit bootfähigen iPXE oder iPXE-CD zum Booten der Rechner

## Verwendung

Zunächst Ansible für die automatische Installation
und Konfiguration aller Komponeten herunterladen:

```console
apt install python3-pip
pip3 install ansible
```

Danach ein Playbook (z.B. `fai.yml`) anlegen
und die grundlegende Parameter festlegen:

```yml
- hosts: localhost
  become: true
  vars:
    dhcp_interface: eth1 # NIC für die Installer Netz
    wan_interface: eth0  # NIC zum Internet
  roles:
    - fai
```

Einen Eintrag hinzufügen in
`~/.ssh/config`

```
host hw4f-fai hw4f-fai.intern.dezentrale.space
	user		username
	#hostname	192.168.1.11
```

Danach das Playbook ausführen:

```
ansible-playbook fai.yml

ansible-playbook -i inventory/dezentrale.yml -K --check --diff -v fai.yml
```

### Virtuale Testinstanz

Für eine testweise Installation kann
[https://www.vagrantup.com/](Vagrant) verwendet werden.
Es richtet anhand der *Vagrantfile* eine virtuelle Maschine ein
und provisioniert sie mittels Ansible.
Vagrant unterstützt verschiedene Provider für Virtualisierungslösungen
bspw. VirtualBox oder libvirt/KVM.

Zur Verwendung muss Vagrant zunächst installiert werden.
Hier beispielsweise zusammen mit VirtualBox:

```
apt install vagrant virtualbox
```

Danach kann die virtuelle Umgebung erstellt
und automatisch eingerichtet werden:

```
vagrant up
```

Die Vagrantfile definiert eine Maschinen mit zwei Ethernet-Ports.
Der erste Port ist für Verwaltung von Vagrant
und der zweite Port (IP: `192.168.33.1`)
um die notwendige FAI Services über ein virtuelles Netzwerk anzubieten.
Mit diesen Netzwerk können dann weitere virtuelle Maschine verbunden werden,
um sie mit FAI automatisch zu installieren.


*Hinweis:* Die Verwendung von VirtualBox wird empfohlen.
Bei libvirt/KVM gab es Probleme
mit dem Starten von Clients für Testinstallationen im virtuellen Netzwerk.
Hier kann es helfen das Netzwerk über *Virt-Manager* neuzustarten oder
ein weiteres isoliertes Netzwerk zu erstellen
und es mit dem zweiten Netzwerkport des FAI-Servers zu verbinden.

### Konfiguration

Über Ansible-Variablen kann die Installation noch weiter angepasst werden.


|**Variable**              |**Bedeutung**                                                   |**Standard**                             |
|---                       |---                                                             |---------------------------------------- |
|dhcp_interface            |NIC des Installtionnetzes (muss gesetzt sein)                   |                                         |
|wan_interface             |NIC zum Internet                                                |`eth0`                                   |
|server_name               |Server-Name                                                     |hw4f-fai                                 |
|domain_name               |Domain-Name des Netzes                                          |local                                    |
|server_ip                 |IP des Servers                                                  |`192.168.33.1`                           |
|server_netbits            |Bits der Netzmaske                                              |`24 `                                    |
|server_netmask            |Netzmaske                                                       |`255.255.255.0`                          |
|apt_cacher_offline_mode   |true, um nur den vorhanden Packet-Cache als Repository zu nutzen|false                                    |
|debian_release            |Debian Release, was für FAI genutzt werden soll.                |buster                                   |
|pxe_preselected_entry     |Vorausgewählte iPXE-Eintag                                      |`__exit` (von lokale Datenträger starten)|
|pxe_menu_timeout          |Timeout für iPXE-Menu in Milisekunden                           |5000                                     |
|ipxe_additional_entries   |Zusätzliche Einträge für iPXE-Menu                              |keine                                    |
|use_apt_cache_for_server  |Apt Cache für den Server selbst verwenden                       |`false`                                  |
|fai_hw4f_profile_username |Desktop Benutzername                                            |`user`                                   |
|fai_hw4f_profile_password |Passwort der Benutzers                                          |`dezentrale`                             |

Beispielsweise kann der Server mit obigen Playbook aufgesetzt werden,
eine Rechner mit Ubuntu installiert werden und
danach der Server wie folgt in den Offline-Installationsmodus versetzt werden:

```yml
- hosts: localhost
  become: true
  vars:
    dhcp_interface: eth1 # NIC für die Installer Netz
    wan_interface: eth0  # NIC zum Internet
    apt_cacher_offline_mode: true
  roles:
    - fai
```

Danach das Playbook noch einmal ausführen,
um die Konfigration zu aktualisieren:

```
ansible-playbook fai.yml
```

#### Zusätzliche Menü-Einträge im iPXE-Menü

Das vordefinierte Playbook für `playbook-vagrant.yml` (Vagrant)
enthält bereits einen zusätzlichen Eintrag für Memtest.

```
ipxe_additional_entries:
  memtest:
    name: Memtest86+
    files: tools/memtest
    kernel: memtest86+-5.31b.bin
# other:
#  name: Anzeigetext des Eintrags
#  files: path/to/files/to/copy
#  kernel: Kernel
#  args: Argumente für den Kernel
#  initrd:
#    - initrd0.img
#    - initrd1.img
#    - ...
#  multiboot:
#    - module0.img
#    - module1.img
#    - ...

pxe_preselected_entry: memtest
```

Dabei werden alle Dateien unter,
die im `files` ausgewiesen sind,
in das PXE-Verzeichnis kopiert.
Es wird ein zusätzlichen Menüeintrag
mit dem Label `memtest` (Name des Eintrags) und
dem Anzeigetext aus `name` angelegt.
Es sind folgende Felder für jeden Boot-Eintrag möglich:

|**Feld**  |**Beschreibung**            |**iPXE-Argument**   |
|---       |---                         |---                 |
|files     |Dateien für den Eintrag     |                    |
|kernel    |Zu ladenden Kernel          |`kernel`            |
|args      |Argumente des Kernel        |an Kernel angehängt |
|initrd    |InitRD-Images               |`initrd`            |
|multiboot |Images für Multiboot-Kernel |`multiboot`         |

Der vorausgewählt Eintrag kann über `pxe_preselected_entry` mit dem Label ausgewählt werden.
Um FAI auszuwählen muss `__fai` gesetzt werden.

## Details

*TBD*

### Komponenten

* DHCP: isc-dhcp-server
* TFTP: tftpd-hpa
* DNS: unbound
* ntp: ntp
* time: inetd
* HTTP: nginx
* rtime: inetd
* Apt Cache: apt-cacher-ng

## Verweise

* [https://fai-project.org](FAI Project)
* [https://ipxe.org](iPXE)
* [https://www.ansible.com](Ansible)