# aux / Fast Boot

Timestamp: 2026-10-08 · Version: 2.2.0
Author & Credits: https://www.alawise.es/1-s

`fast-boot.sh` is a standalone Bash entrypoint with an embedded Python engine, URL catalog and portal assets. The supplied dynamic-engine URL list is preserved. Versions are pinned by those URLs; a dated filename is not a claim that the upstream file exists or is the newest release.

The engine is verbose by default. Each parallel transfer is labelled with its filename and reports its source, percentage, bytes, speed, ETA, resume state, validation and SHA-256 result. The labels remain readable when four downloads run together. Use `--quiet` when only errors and the final summary are wanted; `--verbose` or `-v` explicitly selects the default live output.

```bash
sudo bash fast-boot.sh --verbose --jobs 4
sudo bash fast-boot.sh --quiet --generate-only
```

## Start safely

Review the script, then inspect the plan without writes or network requests:

```bash
bash fast-boot.sh --dry-run
```

Requirements: Bash, Python 3.12 or newer, curl, and bsdtar (`libarchive-tools` on Debian, `bsdtar` on Fedora). Mount and RAM modes also need root, util-linux mount/umount, and stat. Dependencies are checked; the script does not install packages or alter firewall, DNS, PHP-FPM, nginx or systemd configuration.

## Excalibur: disk-backed mounts

```bash
sudo bash fast-boot.sh \
  --mode mount \
  --output /var/www/aux.1-s.es/html \
  --cache /var/www/aux.1-s.es/isos \
  --base-url https://aux.1-s.es \
  --pxe-url http://pxeboot.1-s.es
```

ISOs stay in the cache. The webroot exposes symlinks to their files and read-only loop mounts to their contents. These are disk-backed mounts: symlinks do not load ISOs into RAM. Linux uses available memory as its page cache.

Mounts are not automatically restored after a reboot. Rerun the same command after networking is available. This version does not create a systemd unit. nginx must serve the same webroot for aux and pxeboot hostnames, permit intentional symlink access to the cache, prioritize `index.php`, and pass PHP to a configured PHP-FPM service. Fedora SELinux labels and policy must also permit those paths; this script does not change or disable SELinux.

## Excalibur: actual RAM copies

```bash
sudo bash fast-boot.sh \
  --mode ram \
  --ram-dir /dev/shm/aux-fast-boot \
  --output /var/www/aux.1-s.es/html \
  --base-url https://aux.1-s.es \
  --pxe-url http://pxeboot.1-s.es
```

The RAM directory must already reside on tmpfs. Each payload is copied there and consumes its full size. The engine checks free space before copying, keeps the durable disk download cache, and reports failures rather than claiming a disk-backed file is a RAM copy. Contents and mounts disappear after reboot. RAM mode is unsuitable for a catalog larger than available tmpfs capacity.

## OVH France: physical preparation

Run on a Linux machine where bsdtar is available; then upload the complete generated webroot to shared hosting:

```bash
bash fast-boot.sh \
  --mode extract \
  --output ./france/html \
  --cache ./france/isos \
  --base-url https://b.1-s.eu \
  --pxe-url http://b.1-s.eu
```

This mode duplicates the cached download into the webroot and physically extracts the ISO into its own directory. The generated webroot is self-contained for upload and needs both compressed image and extracted tree disk capacity. Serve `assets/`, `catalog.json`, payload files and extracted trees. No root or loop mount is required on the shared hosting server.

## Catalog and updates

```bash
bash fast-boot.sh --url-file urls.txt --dry-run
sudo bash fast-boot.sh --url-file urls.txt --refresh
sudo bash fast-boot.sh --only debian
bash fast-boot.sh --generate-only --output ./prepared/html --cache ./prepared/isos
```

The external URL list replaces the embedded list. Exact duplicate URLs are removed; distinct URLs with the same basename cause an explicit collision error. SourceForge `/download` suffixes are removed when deriving filenames. Queries are not used as filenames. HTTP(S) sources are supported, with HTTPS preferred.

Valid cached files are reused. `--refresh` fetches them again; interrupted downloads retain `.part` data for a later resume. The verbose output announces whether the partial file resumes with `If-Range` or restarts because no server validator is available. Completed HTML responses, empty files, invalid ISO signatures and invalid archives are rejected. Failed updates preserve the previous valid cache and report a nonzero exit status. Upstream servers can reject resume requests; remove the specific `.part` file to retry a full transfer in that case.

`--generate-only` performs no download, extraction or mount. It reads valid existing cache files and already prepared trees, then writes the portal and menu. It can expose an existing cache through a webroot symlink. Ensure any manually prepared tree matches its ISO before using this option.

There is no automatic deletion of old payloads or unrelated webroot files. A cache lock prevents concurrent runs. Replacing generated pages preserves prior versions under the cache's `backups/` directory. Existing unmanaged payload trees are left for inspection; only trees recorded by this engine may be remounted or replaced. Old ISOs can continue to consume space until deliberately removed.

## Download from an SSH terminal

After deploying the generated webroot on the mirror:

```bash
links https://aux.1-s.es/cli.html
# Or:
lynx https://aux.1-s.es/cli.html
```

`cli.html` is a compact HTML page with no JavaScript, stylesheets, images, cookies or app dependencies. ISO downloads come first, grouped by architecture. Every filename is a real HTTP(S) link. Open the adjacent **commands** link for the exact `wget -c -O filename -- URL` or `curl -fL -C - -o filename -- URL` command. Both specify the output filename, so SourceForge URLs ending in `/download` retain the ISO's real name. Copy a command into the SSH shell in the desired destination directory; rerun it to resume when the server supports HTTP Range requests.

The visual catalog also contains all rows and links in the initial HTML response, in both `index.html` and `index.php`. JavaScript adds filters and dialogs. Resource names lead to ordinary HTML detail pages when JavaScript is unavailable. The original colors and layout remain in the visual catalog.

The default link uses the local mirror only after the engine marks that file as published. Otherwise it uses the configured upstream. The optional mirror selector remains available in the visual catalog. `downloads/isos.tsv` provides one ISO per line with filename, architecture, selected URL and the local SHA-256 when available; it excludes compressed archives and non-ISO boot binaries. `downloads/urls.txt` remains the original complete source list. Do not feed source URLs blindly to `wget -i`: multiple SourceForge URLs can otherwise use the same `download` filename.

Resume only the same image/version, and verify its checksum before use. If a rolling image was replaced on the server, download a fresh copy. These pages work on an ordinary static server or PHP host. The private Sites preview still requires its platform sign-in; the SSH workflow uses the mirror's own HTTP(S) address without that sign-in layer.

## Generated files

- `index.php`: the complete pre-rendered catalog and a fixed-path catalog reader for enhanced interactions. No visitor request parameters control URLs or shell commands.
- `index.html`: static version of the same portal for Sites or a static web server.
- `cli.html`: compact text-browser catalog with direct download links and architecture groups.
- `files/`: lightweight resource pages with explicit filenames, resume commands and recorded hashes.
- `assets/`: local styles, JavaScript, supplied logo and favicon.
- `catalog.json`: source URLs, metadata, local state, real sizes and hashes.
- `menu.ipxe`: architecture and firmware-aware menu generated from prepared local files.
- `sitemaps.xml`: the canonical root and locally published download files, serialized as valid XML.
- `SHA256SUMS`: hashes of locally published downloads.
- `downloads/`: engine, documentation, source list, ISO TSV list, source PHP text, initial menu and a portable portal bundle.

The ZIP contains the portal and engine, not multi-gigabyte ISO payloads. Upload the prepared webroot directly for a physical mirror.

## Integrity

`SHA256SUMS` records the downloaded bytes; it does not authenticate them against a distribution's signing key. For an independently trusted checksum list, use:

```bash
sudo bash fast-boot.sh --checksums trusted-SHA256SUMS
```

Payloads listed in that file must match before publication. Obtain and authenticate checksum/signature records through the distribution's verification procedure. Unlisted payloads are only checked for a valid container and given a local SHA-256 hash.

## Boot scope

Supported recipes cover recognized Debian and Kali installers, Debian-style live trees, Ubuntu casper images, Fedora live and netinst media, Arch media, and matching native network boot clients. Actual kernel/initrd pairs and required filesystem files must exist before a recipe enters the menu. The initial menu contains only the shell, reboot and local-disk options until preparation succeeds.

Debian-style live-boot HTTP fetch can need a numeric IPv4 URL. The engine resolves the boot hostname to IPv4 during generation, or accepts `--live-url http://SERVER_IP`. A failed resolution leaves these live recipes out of the menu. Regenerate after the mirror address changes. HTTPS boot support depends on the iPXE build and certificates; the default client boot URL uses HTTP independently of the portal's HTTPS URL.

Fedora netinst uses the local `.treeinfo` tree for `inst.stage2` and the corresponding upstream `/os/` package repository for `inst.repo`. A netinst ISO is not a full package repository. Kernel/initrd file checks are necessary but do not prove boot compatibility: test on intended BIOS/UEFI/ARM clients. Secure Boot requires a separately trusted, signed boot chain.

Gentoo, Proxmox and Super GRUB images remain downloadable without speculative automatic recipes. Memtest ZIP files are unpacked, including nested ISO contents; only discovered native `memtest.efi` or `memtest.bin` files become menu entries. DBAN stays download-only and never receives an automatic erasure command.

From an iPXE shell:

```text
dhcp
chain http://pxeboot.1-s.es/menu.ipxe
```

The Sites portal initially uses the configured upstream URL catalog. It does not execute Bash, host ISO payloads, deploy to Excalibur, configure DHCP/TFTP, or assert that external mirrors are online. Mirror downloads are generated paths and visibly unverified. Run the engine on the intended preparation/server machine to create the operational mirror.

## Primary technical references

- iPXE platform, build architecture and CPU detection: https://ipxe.org/cfg/platform, https://ipxe.org/cfg/buildarch, https://ipxe.org/cmd/cpuid
- iPXE chainloading: https://ipxe.org/cmd/chain
- Debian live-boot options: https://manpages.debian.org/unstable/live-boot-doc/live-boot.7.en.html
- Anaconda stage2 and install repositories: https://anaconda-installer.readthedocs.io/en/latest/user-guide/boot-options.html
- Project source: https://github.com/1wise/aux.1-s.eu