CASCADE/README.md

# `cascade`

The next iteration of the cascade network.

Should it have been thunder?

Probably.

It's cascade anyway.

## Usage

From a [Proxmox VE][PVE] machine with [Nix][NIX] installed:

```bash
nix-shell
```

Guidance will be printed which should be followed.

## Prerequisites

In order to discover your network and configure hosts, this configuration management system requires the following:
* Samba DC with functioning DNS and DHCP server.
* You must be able to auth with Kerberos to Samba.
* Proxmox running on the local host
* Proxmox should have a local filesystem called hdd-fs

## The Future (or how to not Proxmox)

### Or how it works without the script

Proxmox is not _at all_ a requirement for using this.

Neither is Samba.  They are requirements for the mkvirt function in shell.nix.

This may be replaced or not used at all.  The image created in result/nixos.img will boot on most hypervisors.

After the image is created and booted, it must be morphed.

The first step in morphing is making the machine resolveable.  This is done with Samba but may be done with
another DNS system.  The key is that it must be resolveable _immediately_ after the record is created because
morph then uses that record to find the machine.  Reworking this to use IPs would require changing morph's
defaults or explicitly setting the deployment target address to be something other than the hostname.

After the host is resolveable, morph.

### Interesting Places

* `custom-image.nix`
  * nixos.img disk size, format, partition table, etc
* `common/ssh.nix`
  * configure ssh package (such as `openssh_gssapi` vs `openssh`)
* `common/users.nix`
  * the deploy user, ssh keys, shell, etc.
* `functions/*.nix`
  * a function per file
  * load default.nix to load all functions by name in a set
* `hosts/*`
  * hosts deployed via morph are pulled from here automatically
  * files in this folder should be informational only.  they _do not_ return a function.
  * functionality which requires access to config or pkgs should be implemented in `profiles/` and loaded by name in imports.
* `profiles/*`
  * profiles for describing machines of a certain class.
  * profiles may represent hardware such as `api` and `qemu-vm` or a configuration pattern such as `dhcp-server` or `base`.
  * the `base` profile is special in that it _should_ always be loaded.  it is generally included by the hardware profile.
* `shell.nix`
  * shell functions and configuration to build and deploy machines
    * `env_cascade`
      * discover domain, and realm config such as domain controller (samba) to send DNS updates to
      * sanitize config
      * returns env vars
	* `$DOMAIN` 
	  * domain name (from hostname -d), lowercase
	* `$REALM` 
	  * domain name (from hostname -d), uppercase
        * `$workgroup`
	  * workgroup (first domain segment), lowercase
	* `$WORKGROUP`
	  * workgroup (first domain segment), uppercase
	* `$DC`
	  * lookup PTR of (lookup A of $DOMAIN)
	  * this will find a domain controller in a "normal" domain such as is created by default in Samba
    * `env_name`
      * sanitize hostname
      * returns env vars
        * `$name` hostname, lowercase
	* `$NAME` hostname, uppercase
    * `samba-create-ipv4-records`
      * create DNS records
    * `wait-for-vm-ipv4`
      * wait for a VM to have an ipv4 address in a private subnet
    * `mkvirt`
      * `morph build`
      * get an unused VMID from Proxmox
      * create a new virt with discovered VMID
      * wait for IP
      * create DNS record with IP
      * morph deploy to single machine
    * `destroy-host`
      * removes hosts/$name.nix
      * removes DNS entry for $name.$DOMAIN


NIX: https://www.nixos.org
PVE: https://www.proxmox.com/en/proxmox-ve