entanglement_installer

README

entanglement installer

This is tooling to install Entanglement on bare metal systems. It consts of a live OS which starts the first of several phases of the cluster install process:

After the install is complete, if DNS is configured correctly, the console should be accessible at console.<domain> and the api at api.<domain>. The VM can be accessed via SSH.

Not yet even considered, but this should also make it possible to join new nodes to an existing cluster, skipping parts of stage2 and all of stage3.

development

required tools:

Build:

• podman

Run:

• libvirt (i've been using the virt-manager GUI)

development setup (assuming libvirt default network uses 192.168.122.0/24 subnet):

• ensure the libvirt default network is running
• create a file called build-config.go in the root of the repo that looks something like the following. Replace the SSH key for your own:

package entanglement_installer

func init() {
	Config.SSHKeys = []string{"ssh-ed25519 AAAAAAAAAAAAAAAAAAAAAA you"}
	Config.Defaults.PublicIP = "192.168.122.5"
	Config.Defaults.PublicSubnet = "192.168.122.0/24"
	Config.Defaults.PublicGateway = "192.168.122.1"
	Config.Defaults.Domain = "eg.localtest.me"
	Config.Headless = true // skip all (most - sometimes the first one requires manually pressing enter) interactive options and accept the defaults
}

• add this line to /etc/hosts:

192.168.122.5   api.eg.localtest.me console.eg.localtest.me auth.eg.localtest.me kratos.eg.localtest.me

Now you are ready to run the dev loop:

1. build an iso and start a VM: ./test-in-vm.sh
2. use the virtual console via virt-manager to accept all the default options in the installer.
3. when the install is complete (it takes about 15 minutes for me), go to console.eg.localtest.me in your browser, click through several certificate warnings, and login with admin/changeme

helpful commands during development

• To SSH to the inner VM when everything is up: ssh debian@192.168.122.5
• To SSH to the outer VM (the VM acting as a hypervisor): ssh debian@$(grep ci-info: local-test-vm.log | grep 192.168.122 | awk '{ print $10 }' | head -n1)
• To access internal resources before networking is setup: sshuttle -r debian@$(grep ci-info: local-test-vm.log | grep 192.168.122 | awk '{ print $10 }' | head -n1) 192.168.100.0/24 10.0.0.0/24
• To SSH to inner VM before networking is setup, run sshuttle (as shown on the line above), then nested_vm_ip=$(ssh debian@$(grep ci-info: local-test-vm.log | grep 192.168.122 | awk '{ print $10 }' | head -n1) 'journalctl --boot | grep "DHCPACK(virbr1) 192.168.100."' | awk '{ print $7 }' | head -n1) && ssh-keygen -R ${nested_vm_ip} && ssh debian@${nested_vm_ip}
• ./local-build.sh builds the program into an ISO
• ./test-in-vm.sh runs local-build.sh then boots the newly created ISO in a virtual machine with virt-install
• To use a custom extensions rhyzome-agent, put a link to it in build-config.go: Config.HostFiles["/usr/local/bin/rhyzome-agent"] = "http://192.168.122.1:8000/rhyzome-agent"
  • I usually make a directory in /tmp and run python3 -m http.server in it, and put my locally built rhyzome-agent in it
  • To use a custom cluster-bootstrap, build a custom rhyzome agent with URL to custom cluster-bootstrap: go build -ldflags "-X entanglement.garden/rhyzome/client/bootstrap.ClusterBootstrapBin=http://192.168.122.1:8000/cluster-bootstrap" ./cmd/rhyzome-agent

Documentation

Index

• Variables
• type BuildConfig
• type InstallOptions

Variables

var (
	Config = BuildConfig{
		BaseImage:         "https://cloud.debian.org/images/cloud/bookworm/daily/latest/debian-12-generic-amd64-daily.raw",
		VMBaseImageQcow:   "https://cloud.debian.org/images/cloud/bookworm/daily/latest/debian-12-generic-amd64-daily.qcow2",
		VMBaseImageRaw:    "https://cloud.debian.org/images/cloud/bookworm/daily/latest/debian-12-generic-amd64-daily.raw",
		ContainerRegistry: "docker.io",
		HostFiles: map[string]string{
			"/usr/local/bin/rhyzome-agent": "https://codeberg.org/api/packages/EntanglementGarden/generic/rhyzome/cb82ff4/rhyzome-agent",
			"/opt/step.deb":                "https://dl.step.sm/gh-release/cli/gh-release-header/v0.23.2/step-cli_0.23.2_amd64.deb",
		},
		Defaults: InstallOptions{
			SuperuserName:              "admin",
			SuperuserPasswordPlaintext: "changeme",
			ExtraPackages:              []string{"jq", "tmux", "tmate", "htop", "mosh"},
		},
		Logs:      []string{"/dev/ttyS0", "/dev/tty2"},
		DebugLogs: []string{},
	}
)

Types

type BuildConfig

type BuildConfig struct {
	BaseImage         string // URL to image to use for the hypervisor.
	VMBaseImageQcow   string // override base image for services VM
	VMBaseImageRaw    string
	SSHKeys           []string              // SSH keys to add to the hypervisor and services VM (user: debian)
	ContainerRegistry string                // docker hub proxy to use
	HostFiles         map[string]string     // files to download to the hypervisor's root disk. key is the path on disk to the destination, value is the URL. mode will always be 755 (executable)
	AptMirrors        []cloudinit.AptMirror // select an apt mirror for the hypervisor and services VM. the default will be used if unspecified
	Defaults          InstallOptions        // bake defaults into the installer image. These will be prefilled in the TUI
	Headless          bool                  // skip all interactive configuration, just use the configured defaults and install
	Logs              []string
	DebugLogs         []string
}

type InstallOptions

type InstallOptions struct {
	RootDisk      string
	WAN           string
	SSHKeys       []string
	Domain        string
	PublicIP      string
	PublicSubnet  string
	PublicGateway string
	ExtraPackages []string // Extra packages to install on the hypervisor

	SuperuserName              string // username for the root user
	SuperuserEmail             string // email address for root user. currently stored for future use but never verified or used. Will NEVER be sent to any server outside of this installation without separate explicit approval
	SuperuserPasswordPlaintext string // plaintext password for the superuser. Ignored if SuperuserPasswordHashed is set
	SuperuserPasswordHashed    string // hash of the superuser password in a format that Ory Kratos will accept (https://www.ory.sh/docs/kratos/manage-identities/import-user-accounts-identities#hashed-passwords). If set, SuperuserPasswordPlaintext is ignored.
}