Kellnr

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Kellnr Crate Registry by SecureAnyCloud and select Create.

On the Basics tab, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22).

Select Review + create, then Create. Open port 443 afterwards, as shown in the next step.

Accept the image terms once per subscription, then deploy:

az vm image terms accept --urn sac:kellnr-ubuntu-24-04:default:latest
az group create --name kellnr-rg --location eastus
az vm create \
  --resource-group kellnr-rg \
  --name kellnr-vm \
  --image sac1647283583153:kellnr-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard
az vm open-port --resource-group kellnr-rg --name kellnr-vm --port 443 --priority 1010

Connect over SSH:

ssh azureuser@<vm-public-ip>

The login user is azureuser unless you chose a different administrator name when you created the VM.

Check that both services are active:

systemctl is-active kellnr nginx

Both must report active. The kellnr unit does not start until first boot has finished generating this VM's credentials. nginx does not start until first boot has created its certificate. If you have only just created the VM, wait a minute and run the command again.

Check the version and the liveness endpoint:

/usr/local/bin/kellnr --version curl -s http://127.0.0.1:8000/api/v1/health; echo

That prints kellnr 6.8.0 and then OK. The health endpoint is deliberately the one route outside the authentication layer, so a load balancer can probe it without a credential. It reveals nothing except that the process is alive.

Run the port check:

sudo /usr/local/sbin/kellnr-port-check.sh

The script prints the exact set of TCP ports reachable from outside the VM and fails if the set is anything other than 22 and 443. Kellnr itself listens on 127.0.0.1:8000 and is proven unreachable on the VM's external address. Nothing listens on port 80.

To see the raw listening sockets:

sudo ss -Hltn | awk '{print $4}' | sort -u

Every credential this registry uses was generated on this VM's first boot and exists on no other instance. The credentials are written to a file that only root can read.

This command shows the file with the two secrets masked, so you can see its shape before you read the real values:

sudo sed -E 's/^(KELLNR_ADMIN_PASSWORD=|KELLNR_API_TOKEN=).*/\1<redacted>/' \
  /root/kellnr-credentials.txt

The file contains these fields:

• KELLNR_URL: the web interface for this VM
• KELLNR_HOST: this VM's customer-facing address, resolved at first boot
• KELLNR_ADMIN_USER: always admin
• KELLNR_ADMIN_PASSWORD: the web interface password for this VM
• KELLNR_API_TOKEN: the cargo API token for this VM
• KELLNR_REGISTRY_INDEX: the index URL to put in ~/.cargo/config.toml
• KELLNR_TLS_CERT: this VM's certificate, for clients that verify it

Read the real values when you need them:

sudo grep -E '^KELLNR_(URL|HOST|ADMIN_USER|REGISTRY_INDEX)=' /root/kellnr-credentials.txt

The upstream default password for Kellnr's admin account is the string admin, and the credential is decided once, at the instant the registry database is created. This image ships no database, so that default never reaches a running instance. The next step proves it rather than asserting it.

Run the authentication check:

sudo /usr/local/sbin/kellnr-verify-auth.sh /root/kellnr-credentials.txt

The script runs the whole credential gate against the real TLS front door. It prints KELLNR_AUTH_OK only if every one of these holds:

• the documented default admin / admin is refused with 401
• a blank password is refused with 400, which is Kellnr's own validation answering before any credential check
• five well-known weak passwords are refused with 401
• this VM's password is accepted, reports is_admin, and hands out a session the web API then honours
• the registry index and the publish endpoint both refuse a missing token and a wrong token with 401
• the index advertises https:// at this VM's own address with auth-required set
• kellnr's own port does not answer on the VM's external address, and nothing answers on port 80
• TLS verification refuses an address the certificate does not name

Each of those checks is itself tested against a known-bad input, so a check that could never fail is caught. Run the self test:

sudo /usr/local/sbin/kellnr-gate-selftest.sh /root/kellnr-credentials.txt

Open https://<KELLNR_HOST>/ in a browser. The image ships a certificate generated for your VM's own address. Because it is self-signed, your browser warns once. Step 14 shows how to install your own certificate.

Sign in as admin with the password from Step 6.

The home page is the registry dashboard: how many crates and versions you hold, how many downloads they have served, and what was published most recently.

On the machine you build from, add the registry to ~/.cargo/config.toml. The index URL is the KELLNR_REGISTRY_INDEX value from Step 6. It is a sparse+https:// URL, which is the modern protocol cargo uses by default:

[registries.kellnr] index = "sparse+https://<KELLNR_HOST>/api/v1/crates/"

Put the token in ~/.cargo/credentials.toml, which cargo expects to be readable only by you:

[registries.kellnr] token = "<KELLNR_API_TOKEN>"

Cargo does not use the address you typed to download crates. It reads the registry's index configuration and follows the URLs published there. This image resolves your VM's own address at first boot and publishes it over HTTPS, so cargo works from a developer machine straight away.

To see exactly what cargo will be told:

sudo bash -c 'T=$(grep "^KELLNR_API_TOKEN=" /root/kellnr-credentials.txt | cut -d= -f2-); H=$(grep "^KELLNR_HOST=" /root/kellnr-credentials.txt | cut -d= -f2-); curl -s --cacert /etc/ssl/kellnr/kellnr.crt --resolve "$H:443:127.0.0.1" -H "Authorization: $T" "https://$H/api/v1/crates/config.json"; echo'

When auth-required is true, cargo sends your token when it fetches the index and downloads crates.

The --resolve flag is there because an Azure VM cannot dial its own public IP. The Standard Load Balancer does not hairpin, so a request from the VM to its own public address times out. --resolve keeps your real address in the URL and in the TLS check while sending the connection to loopback. From your laptop, use the URL as is.

From your own crate's directory, publish to the registry. Run this on the machine you build from, not on the registry VM, which deliberately carries no Rust toolchain:

cargo publish --registry kellnr

Then depend on it from another project by naming the registry:

[dependencies] my-internal-crate = { version = "0.1.0", registry = "kellnr" }

The crate page in the web interface shows the version, the licence, the owners and the exact dependency line to paste:

You do not need a Rust toolchain on the registry VM to check that publishing works end to end. The image ships a self test that does the complete round trip with your own token through the real TLS front door, then puts the registry back exactly as it found it:

sudo /usr/local/sbin/kellnr-publish-probe.sh /root/kellnr-credentials.txt

The probe publishes a crate using cargo's own wire format and requires the sparse index to list it with a matching checksum. It downloads the crate back and requires the bytes to be identical, rather than merely a 200. It then deletes the crate and requires the registry to be empty again on disk and in the database.

Along the way, the probe requires the emptiness check to fail while the crate is present, because a check that could not see a crate that is genuinely there would be worthless.

Confirm nothing was left behind:

sudo /usr/local/sbin/kellnr-registry-empty.sh --with-db /root/kellnr-credentials.txt

The token in your credentials file belongs to the admin account. Give each CI pipeline its own token instead, so you can revoke one without disturbing anything else.

In the web interface, choose Settings, then Auth. Tokens. Name the token and select Create Token. Copy the value immediately, because it is shown once.

For a build agent, put the token in the environment rather than in a file. Set these on the CI runner, not on the registry VM:

export CARGO_REGISTRIES_KELLNR_TOKEN="the token you just created"
export CARGO_REGISTRIES_KELLNR_INDEX="sparse+https://your-registry-address/api/v1/crates/"

Under Settings, User Management lets you add users and mark accounts read-only, so they can consume crates but not publish. Group Management grants several people access to the same crates at once.

Kellnr can cache public crates alongside your private ones, so a build keeps working when the public index is slow or unreachable. The proxy is off by default in this image. A registry that silently reaches out to the internet and mirrors whatever is asked of it is not what most people want on first boot, and the cache grows without bound.

To turn it on, edit /etc/kellnr/kellnr.toml and set enabled = true under [proxy]:

sudo sed -n '/^\[proxy\]/,/^$/p' /etc/kellnr/kellnr.toml

After you edit the file, apply the change with sudo systemctl restart kellnr. Allow for the extra disk the cache will use.

The whole registry is one directory: the SQLite database and every .crate file live under /var/lib/kellnr. This is deliberate: a backup is a copy of one path, and a restore cannot leave metadata describing crates that are not there.

sudo tar -czf /tmp/kellnr-backup.tar.gz -C /var/lib kellnr && sudo ls -lh /tmp/kellnr-backup.tar.gz

Copy the archive off the VM with scp and keep it somewhere durable. Your /etc/kellnr/kellnr.env file belongs with it. It carries the administrator password and API token, and Kellnr fixes the administrator credential when the database is created, so a restored database with no matching environment file cannot be signed into. Back up both together.

sudo rm -f /tmp/kellnr-backup.tar.gz

The image generates a self-signed certificate for your VM's IP address on first boot. For a registry your whole team will use, point a DNS name at the VM and install a certificate for it.

Put your certificate chain at /etc/ssl/kellnr/kellnr.crt and your private key at /etc/ssl/kellnr/kellnr.key (0600 root:root).

Then set KELLNR_ORIGIN__HOSTNAME in /etc/kellnr/kellnr.env to the hostname Kellnr should advertise to cargo, and restart both services. If you obtain a certificate with certbot, use its --nginx installer or copy the issued files into the paths above.

The hostname matters as much as the certificate. It is the value cargo is handed in the index configuration, so changing the certificate without changing the hostname leaves every client being told to fetch from the old address.

Unattended security upgrades are enabled. To patch now:

sudo apt-get update && sudo apt-get upgrade -y

Kellnr itself is a pinned upstream release rather than an Ubuntu package, so apt never updates it and never warns you that it is old.

To move to a newer release, take the Step 13 backup first. Then download the kellnr-x86_64-unknown-linux-gnu.zip asset from the Kellnr releases page and verify its SHA-256 against the value GitHub publishes for that asset. Stop the service, replace /usr/local/bin/kellnr, and start the service again. Your data directory is untouched, and Kellnr migrates its own database on the next start.

Run the rotation helper, passing the new password on standard input:

printf '%s' '<new-password>' | sudo /usr/local/sbin/kellnr-set-admin-password.sh /root/kellnr-credentials.txt

Replace <new-password> with a password of at least 12 characters. The helper reads the password from standard input rather than the command line, so it does not land in your shell history or the process table.

Kellnr's own endpoint accepts anything that is not empty. This wrapper refuses blank, short, all-digit and well-known weak values, and refuses the password you are already using. It then proves the rotation took by requiring the new password to be accepted and the old one to be refused before it updates your credentials file.

To see the helper refuse a weak value without changing anything:

if printf '%s' 'short' | sudo /usr/local/sbin/kellnr-set-admin-password.sh /root/kellnr-credentials.txt >/dev/null 2>&1; then echo "UNEXPECTED: a 5-character password was accepted"; exit 1; else echo "a weak password was REJECTED and nothing changed"; fi

Because the administrator credential is fixed when the registry database is created, this is the only way to change it. Re-provisioning the VM does not rotate it. First boot deliberately preserves the credentials of a registry that already exists, because creating new ones would hand you a credentials file your own registry has never heard of, with your crates still inside it.