# Claremont MakerSpace Windows 10 Deployment

A mess of various stuff to install Windows 10 via the network, with automatic hostname assignment from [Snipe-IT](https://snipeitapp.com/) and installation of [Salt](saltproject.io) minion.
Domain join and rest of setup (installing applications, applying configuration, etc.) is done afterwords by Salt and group policy.

## Usage

In theory, just enable UEFI PXE Booting, plug into the `CMS Classroom` network, and select `PXE Boot (IPV4)` (or similar) as a boot option.

- For computers with UEFI, but without UEFI PXE (for some reason...), you can make a USB drive to jumpstart the process by with `ipxe.usb` ([see below](<#build-ipxe>)).
- For computers without Ethernet, a USB 3 Ethernet adapter can be used (I'm not sure if all adapters work, but I believe it does have to be USB 3).
  - In theory, some WiFi adapters support PXE booting (and are supported by iPXE), but not the ones in the latops CMS has.

## Setup

Somewhat based on [this helpful guide][pxe_win].
Written for Debian 11.
Various hostnames and exact paths may need to be adjusted in provided files.
Also assumes UEFI booting, because Legacy booting is pretty deprecated at this point.

### Enable PXE booting in DHCP server

Depends pretty heavily on DHCP server, but in UniFi it's in `Settings -> Networks -> <specific network> -> Advanced`.
See [previously mentioned guide][pxe_win] or [iPXE docs](https://ipxe.org/howto/dhcpd) for more details (but ignore the bit about chainloading, as we instead are using an embedded script).

### <a name="build-ipxe"></a>Build custom [iPXE](https://ipxe.org/)

1. Clone `git://git.ipxe.org/ipxe.git`
2. Copy [`embed.ipxe`](./embed.ipxe) to `src/`
   - This allows for chainloading, without needing support from the DHCP server
3. Build PXE executable or usb image

```sh
make bin-x86_64-efi/ipxe.usb EMBED=embed.ipxe SHELL="sh" # For USB drive
make bin-x86_64-efi/ipxe.efi EMBED=embed.ipxe SHELL="sh" # For PXE TFTP boot
```

4. `dd` `ipxe.usb` to a USB drive, if needed (for computers with UEFI, but not UEFI PXE)

### TFTP (via `tftpd-hpa`)

1. Install `tftpd-hpa` package
2. Copy [`tftp/main.ipxe`](./tftp/main.ipxe) (and `ipxe.efi`, if PXE booting) to `/srv/tftp`
   - This doesn't actually need to be a menu; it could basically just be `chain http://<hostname here>:8081/poll/1/${mac} ||`
3. Copy [`tftp/tftpd.map`](./tftp/tftpd.map) to `/etc/`, and add `--map-file /etc/tftpd.map` to `TFTP_OPTIONS` in `/etc/default/tftpd-hpa`
   - This is to work around some older UEFI PXE implementations, which add a 0xFF character (which they render as ÿ) after the file name for unclear reasons

### Hostname script

1. Install `python3` and `python3-requests`
2. Copy [`ipxe-set-hostname-from-serial.py`](./ipxe-set-hostname-from-serial.py) to `/usr/lib/cgi-bin`
3. [Generate a token from Snipe-IT](https://snipe-it.readme.io/reference/generating-api-tokens) and edit it into the script

### [Shoelaces](https://github.com/thousandeyes/shoelaces)

1. Set base URL, bind address, and data dir in `/etc/default/shoelaces`
2. Copy [`shoelaces`][./shoelaces] folder to `/srv/shoelaces`
3. Download [wimboot](https://ipxe.org/wimboot) and put it in `/srv/shoelaces/static/windows`
4. Adjust `mappings.yaml` for the targeted subnet

### Windows Installer

1. [Download The latest Windows 10 ISO](https://www.microsoft.com/en-us/software-download/windows10ISO)
2. Extract the ISO to `software` SMB share, at `pxe/Windows10`
3. Retrieve the following files for pxe booting, and place them in `/srv/shoelaces/static/windows/windows10/` (keeping the folder structure):

```
boot/bcd
boot/boot.sdi
sources/boot.wim
```

### [Salt](https://saltproject.io/) minion

1. [Download latest salt windows minion installer](https://docs.saltproject.io/salt/install-guide/en/latest/topics/install-by-operating-system/windows.html)
2. Place in `<software share>/pxe/Windows10/sources/$OEM$$/$$/setup/scripts/` as `Salt-Minion-Setup.exe`
   - This slightly magic path will place the files at `C:\Windows\Setup\Scripts` in the installed OS
3. Copy [`SetupComplete.cmd`](./SetupComplete.cmd) to same directory
   - This will be run after setup is complete as `SYSTEM`, and installs salt with the configured hostname as the minion name

## Sources/References

* [iPXE boot Windows and Linux, using uefi.][pxe_win]
* [iPXE - open source boot firmware [docs]][ipxe_docs]
* [Snipe-IT API Reference][snipeit_api]

[pxe_win]: https://rpi4cluster.com/pxe/win/ "iPXE boot Windows and Linux, using uefi."
[ipxe_docs]: https://ipxe.org/docs "iPXE - open source boot firmware [docs]"
[snipeit_api]: https://snipe-it.readme.io/reference/ "Snipe-IT API Reference"