ge-aerospace/pxe-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b20e6be629b0776ea93069d8dce77f1e3a8e7b8e
pxe-server/docs/SITE-CUSTOMIZATION.md
cproudlock ead3314f58 Two-NIC standard: pin imaging and GE NICs by MAC everywhere 
Every server has an imaging NIC (static, the only one that serves
DHCP/TFTP/HTTP boot/SMB) and a GE corporate NIC (DHCP client, SSH and the
webapp on 9009). The playbook guessed the PXE NIC and the installer put
172.16.9.1/24 on every en* NIC, so a two-NIC box could answer on the GE
network.

- New per-site vars pxe_nic_mac / corp_nic_mac (required, from
  playbook/site-vars.yml or -e; template site-vars.example.yml), stable
  names pxe_nic_name / corp_nic_name (default pxe0 / corp0, overridable),
  pxe_server_ip, pxe_subnet, DHCP range. pxe_imaging_mac / pxe_ge_mac are
  derived from them. The play stops before touching anything if a MAC is
  unset, malformed, duplicated or not on the box (lists the box's NICs).
- Heuristic NIC detection and the single-NIC netplan task replaced by a
  two-NIC netplan template (match macaddress + set-name), installed by
  pxe-netplan-apply.sh: validate in a scratch root, back up, generate,
  rename, apply, restore the previous config on any failure. cloud-init
  network config disabled so it cannot rewrite it.
- dnsmasq: /etc/dnsmasq.d/pxe-nic-only.conf from the vars (interface=,
  except-interface=, no-dhcp-interface=); dnsmasq.conf IP/range from vars.
- UFW per interface: imaging NIC 22, 67/udp, 69/udp, 80, 4433, 445, 139,
  137/udp, 138/udp, 9009; GE NIC 22 and 9009 only. Old any-interface rules
  and the stale 9011 rule removed after the new ones are in.
- sysctl drop-in: IPv4/IPv6 forwarding off; ip_nonlocal_bind so Apache
  can bind the imaging IP before the address is up.
- Samba [global]: interfaces = 127.0.0.0/8 <imaging NIC>, bind interfaces
  only. Apache 80 and 4433 on the imaging IP only; 9009 stays on all (TODO:
  the webapp has no auth).
- autoinstall: DHCP only on en*, no static 172.16.9.1; apt geoip off and
  offline-install fallback now that the corp NIC may have a lease.
- Blancco UEFI/Secure Boot: blancco_kver (7.0.0-34-generic) drives the
  kernel, initramfs and modules builds instead of the running kernel;
  outputs vmlinuz-ubuntu-70, kexec-initrd-70.img, kmod-<kver>.tar.gz as the
  menu and blancco-init.sh expect; creates: guards keyed on the full kver.
  Ubuntu's shimx64.efi.signed published as blancco/shimx64.efi.
  download-packages.sh adds shim-signed, linux-generic-hwe-24.04 and the
  pinned linux-image/modules/modules-extra for BLANCCO_KVER.

Rendered with the live MACs and names, netplan generate output is
identical to the live config; pxe-nic-only.conf and the Samba binding
match live directive for directive.
2026-10-15 08:53:41 -04:00

210 lines
8.9 KiB
Markdown
Raw Blame History

# Site Customization
The PXE server in this repo was built for the GE Aerospace West Jefferson site.
To stand it up at another site, several values need to change. This document
lists every site-specific value, where it lives today, and the recommended
forward state.
## Status
The repo has not yet been parameterized. As of 2026-04-14 the site-specific
values below are hardcoded in multiple files. The `config/` directory at the
repo root is a placeholder for the future state where one YAML file drives
substitution at build time. Until that exists, customizing for a new site
means editing the source files directly.
If you are bringing up the first non-WJ site, expect to do this manually and
contribute a `config/sites/<sitename>.yaml` template back to the repo.
## Values to change
### Network
Every server has two NICs: the imaging NIC (isolated imaging LAN, static
172.16.9.1, the only NIC that serves DHCP/TFTP/HTTP boot/SMB) and the GE
corporate NIC (DHCP client; SSH and the webapp on 9009 only). Put both MACs
in `playbook/site-vars.yml` (copy `playbook/site-vars.example.yml`) before
building the USB: `pxe_nic_mac`, `corp_nic_mac`. The installer brings the
network up with DHCP only; the first-boot playbook stops before changing
anything if either MAC is unset or missing, then pins both NICs by MAC in
netplan (names `pxe0` / `corp0`, overridable), dnsmasq, UFW and Samba.
| Value | Default | Where it lives |
|-------------------|----------------------|--------------------------------------------------------------------------------|
| PXE server IP | 172.16.9.1 | `playbook/pxe_server_setup.yml` (dnsmasq config, iPXE script, samba conf, webapp env), `playbook/startnet.cmd` (mount paths), `boot-tools/blancco/grub-blancco.cfg` (TFTP/HTTP URLs) |
| PXE subnet | 172.16.9.0/24 | Same as above, plus `playbook/pxe_server_setup.yml` (UFW rules) |
| DHCP range | 172.16.9.10-100 | `playbook/site-vars.yml` (`pxe_dhcp_start`, `pxe_dhcp_end`) |
| NIC MACs / names | (required) / pxe0, corp0 | `playbook/site-vars.yml` (`pxe_nic_mac`, `corp_nic_mac`, `pxe_nic_name`, `corp_nic_name`) |
| Hostname | pxeserver | `autoinstall/user-data` (identity.hostname) |
### Identity and credentials
| Value | Default | Where it lives |
|-----------------------------|---------------------------------------|---------------------------------------------------------|
| Linux user | pxe / pxe | `autoinstall/user-data` (identity.username, password hash) |
| Samba upload user | pxe-upload / pxe | `playbook/pxe_server_setup.yml` (Samba user creation) |
| Samba blancco user | blancco / blancco | `playbook/pxe_server_setup.yml` |
| Sudo password | pxe | autoinstall password hash; also referenced in scripts that ssh + sudo |
### WiFi and BMC (Blancco licensing)
The Blancco custom `config.img` carries WiFi credentials and BMC cloud
credentials in plaintext. These are GE-Aerospace specific.
| Value | Default | Where it lives |
|---------------|----------------------|-------------------------------------------------------------------------|
| WiFi SSID | INTERNETACCESS | `boot-tools/blancco/config.img` (inside the cpio archive: preferences.xml) |
| WiFi password | Acc3ssGr@nted22 | Same |
| BMC endpoint | classic.eu-west-1.blancco.cloud:443 | Same; encrypted credentials inside config.img |
To rebuild `config.img` for a different site, see BLANCCO.md ("Rebuilding
config.img").
### Image types
The repo defines seven image types (see `playbook/pxe_server_setup.yml`,
`image_types`). Most sites likely only need a subset. The current set:
- gea-standard
- gea-engineer
- gea-shopfloor
- ge-standard
- ge-engineer
- ge-shopfloor-lockdown
- ge-shopfloor-mce
Trim or extend this list and the matching `shopfloor_types` filter as needed.
### PC types (shopfloor sub-types)
`playbook/shopfloor-setup/` contains per-PC-type install logic. The current
types reflect WJ shopfloor needs:
- CMM (PC-DMIS)
- WaxAndTrace
- Keyence
- Genspect
- Display (Lobby and Dashboard variants)
- Standard (Timeclock and Machine variants)
- Lab
A site without CMMs can drop the CMM type and its installers entirely.
### GCCH bulk-enrollment PPKGs
PPKG filenames are baked into `playbook/startnet.cmd` and
`startnet-template.cmd`. They are tied to the GE Aerospace tenant. Other
sites/tenants will have their own PPKGs with different filenames.
| PPKG enrollment menu choice | Default filename |
|-----------------------------|---------------------------------------------------------------|
| 1 NoOffice | GCCH_Prod_SFLD_NoOffice_US_Exp_20260430_v4.10.ppkg |
| 2 StdOffice x86 | GCCH_Prod_SFLD_StdOffice-x86_US_Exp_20260430_v4.10.ppkg |
| 3 StdOffice x64 | GCCH_Prod_SFLD_StdOffice-x64_US_Exp_20260430_v4.10.ppkg |
| 4 ProPlusOffice x86 | GCCH_Prod_SFLD_ProPlusOffice-x86_US_Exp_20260430_v4.10.ppkg |
| 5 ProPlusOffice x64 | GCCH_Prod_SFLD_ProPlusOffice-x64_US_Exp_20260430_v4.10.ppkg |
When you bump PPKG versions, update the filenames in startnet.cmd, drop the
new PPKGs in `enrollment/` on the workstation, and rebuild the USB.
### Site-specific shopfloor config
`playbook/shopfloor-setup/site-config.json` has site-specific values like
default machine number ranges, share paths for software, and more. Inspect
that file for site name strings, share UNC paths, and machine number ranges.
### Branding
The Flask webapp uses GE Aerospace branding:
- Logo: `webapp/static/ge-aerospace-logo.svg`
- Favicon: `webapp/static/favicon.ico`
- Page titles and templates reference "GE Aerospace" in `webapp/templates/*.html`
- iPXE menu title: "GE Aerospace PXE Boot Menu" in `playbook/pxe_server_setup.yml`
### Drivers (Dell)
Driver content is hardware-specific, not strictly site-specific, but the set
of driver families to bundle changes by what hardware the site deploys:
- `Dell_11/Pro` and `Dell_11/ProMax`: Dell Pro Micro PCs (most common shopfloor)
- `Dell_11/Optiplex`: traditional desktops
- `Dell_11/Precision`: workstations
- `Dell_11/Latitude`: laptops (large, often excluded if site has none)
The `scripts/download-drivers.py` and `scripts/Download-Drivers.ps1` scripts
populate `drivers-staging/` from upstream sources. Edit these to target the
relevant hardware lists.
### BIOS update manifest
`playbook/shopfloor-setup/BIOS/models.txt` maps Dell model strings to the
BIOS .exe to flash. Update this whenever new hardware arrives or Dell
publishes a new firmware release for a model already in the fleet.
### Intune DSC categories
The post-enrollment Intune DSC delivery (per `intune-dsc.md` memory) pulls
per-category YAML from Azure Blob:
- main
- cmm
- displaypcs
- waxtrace
Different sites/tenants will need their own categories and their own Azure
Blob storage account.
### Image-upload paths on Windows
`scripts/Upload-Image.ps1` defaults to:
- `\\172.16.9.1\image-upload` as the destination
- `C:\ProgramData\GEAerospace\MediaCreator\Cache\` as the source
Update both for a different site.
## Recommended forward state
A site config file should drive substitution at build time. Proposed schema:
```yaml
# config/sites/<sitename>.yaml
site:
name: westjeff
pxe_server_ip: 172.16.9.1
pxe_subnet: 172.16.9.0/24
dhcp_range_start: 172.16.9.10
dhcp_range_end: 172.16.9.100
hostname: pxeserver
credentials:
pxe_user: pxe
pxe_password: pxe
pxe_upload_password: pxe
blancco_password: blancco
blancco:
wifi_ssid: INTERNETACCESS
wifi_password: Acc3ssGr@nted22
bmc_endpoint: classic.eu-west-1.blancco.cloud:443
ppkg_versions:
current: v4.10
expiry: 20260430
intune_dsc_categories: [main, cmm, displaypcs, waxtrace]
image_types: [gea-standard, gea-engineer, gea-shopfloor]
shopfloor_types: [gea-shopfloor]
```
`scripts/build-usb.sh` and the playbook would consume this and substitute
into the templated config files. Implementing this is a separate piece of
work; until then, edit source files directly.
## Secrets handling
Some values above are sensitive (WiFi passwords, BMC credentials, Samba
passwords). Today these sit in plain text in the repo. For a multi-site
deployment, treat them as per-site secrets:
- Keep `config/sites/<sitename>.secrets.yaml` out of git (gitignore).
- Distribute via secure channel (1Password, Vault, etc.) when standing up
a new site.
- The `eMxInfo.txt` precedent (see `feedback_emxinfo_secret.md`) is a good
template: never commit, document where the canonical copy lives.
Reference in New Issue View Git Blame Copy Permalink