Internals

Galaxy

Azimuth is a hierarchy with 256 galaxies at the top. Each galaxy spawns and sponsors stars; each star spawns and sponsors planets.

Planets periodically publish where they live to their sponsoring galaxy’s address map.

Azimov walks the sponsor chain to its galaxy, then uses it for peer lookups, and for encrypted relay in challenging network conditions (e.g., when behind CGNAT).

Operators

Requirements

• Public TCP 443. Clients dial https://{patp}.relay.azimov.network (zod.relay.azimov.network for ~zod). That is DERP and the address map. The port is 443.
• Public UDP 3478. STUN. An HTTP proxy does not carry it.
• A certificate clients already trust on that name. The proxy can obtain one from Let’s Encrypt, or you can provide one. Login writes a separate relay certificate, ~/.azimuthd/derper/ca.crt, for the hop from the proxy to the relay.

0. DNS Update

Contact the Azimov team to create a {patp}.relay.azimov.network record for your galaxy’s IP. For now, this is a manual process; an automated self-service workflow is on the roadmap.

1. Give the relay its own :443

Install the daemon from install. Opening the kernel interface needs an administrator (root, or CAP_NET_ADMIN on Linux). The relay ships inside that daemon.

The reverse proxy owns the host’s 443. Run the galaxy in its own network namespace so the relay can bind :443 there. It does not listen on port 80. Publish the relay as 127.0.0.1:8443, the map as 127.0.0.1:8090, and UDP 3478 on the public address. Mount ~/.azimuthd/derper/ where the proxy can read it.

2. Log in as the galaxy

Logging in as the galaxy starts the relay and the address map, and publishes this galaxy’s address to nut.relay.azimov.network to bootstrap the network. A galaxy uses az login --ticket with its Bridge master ticket. Login.

On first launch, the daemon writes ~/.azimuthd/derper/ca.crt, a certificate for the encrypted relay at {patp}.relay.azimov.network.

3. Reverse proxy

Put the proxy on public 443 for {patp}.relay.azimov.network, with the certificate from the requirements. Send /addr and /mesh to http://127.0.0.1:8090 and leave those paths in place. The map is HTTP on 8090. Send every other path to https://127.0.0.1:8443. That hop uses the relay certificate from step 2: the proxy sends the public name and trusts ca.crt by its absolute path. DERP keeps the connection open, so turn buffering off and allow a long read. UDP 3478 stays a direct publish.

Caddy. With no tls line, Caddy obtains a Let’s Encrypt certificate. To provide one, set tls to that certificate and key.

{patp}.relay.azimov.network {
	handle /addr/* {
		reverse_proxy 127.0.0.1:8090
	}
	handle /mesh/* {
		reverse_proxy 127.0.0.1:8090
	}
	handle {
		reverse_proxy https://127.0.0.1:8443 {
			transport http {
				tls_server_name {patp}.relay.azimov.network
				tls_trusted_ca_certs /home/az/.azimuthd/derper/ca.crt
			}
		}
	}
}

nginx. Point ssl_certificate at a certificate clients already trust. The map belongs in the http block. proxy_pass has no trailing path, so /addr and /mesh stay intact.

map $http_upgrade $connection_upgrade {
	default upgrade;
	""      close;
}

server {
	listen 443 ssl;
	server_name {patp}.relay.azimov.network;

	ssl_certificate     /path/to/fullchain.pem;
	ssl_certificate_key /path/to/privkey.pem;

	location /addr/ {
		proxy_pass http://127.0.0.1:8090;
	}
	location /mesh/ {
		proxy_pass http://127.0.0.1:8090;
	}
	location / {
		proxy_pass https://127.0.0.1:8443;
		proxy_http_version 1.1;
		proxy_set_header Host $host;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection $connection_upgrade;
		proxy_ssl_server_name on;
		proxy_ssl_name {patp}.relay.azimov.network;
		proxy_ssl_trusted_certificate /home/az/.azimuthd/derper/ca.crt;
		proxy_ssl_verify on;
		proxy_buffering off;
		proxy_read_timeout 3600s;
		proxy_send_timeout 3600s;
	}
}

That ca.crt path is the daemon user’s ~/.azimuthd/derper/ca.crt.

4. Let this machine dial its own name

The galaxy dials {patp}.relay.azimov.network. Hairpin that name to the public certificate, or map it to loopback and trust the relay CA. On Nut, we at TND map nut.relay.azimov.network to 127.0.0.1 inside the galaxy container and point the process at that CA.

5. Probe

A 200 means this galaxy is live. Until then, sponsees stay on nut.relay.azimov.network (~nut, galaxy 67). NXDOMAIN, a TLS error, or a 404 leaves them there.