A private Docker registry
Host your own Docker registry with users and passwords in one JailOps jail. Two packages, a few lines of configuration, passwords from htpasswd, the images on a volume, and a firewall that lets in only who you choose.
The idea
A registry of your own, with users in a file.
Two programs do the work. docker-registry stores the images. docker_auth says who may push and pull: a user logs in there, gets a short-lived token, and shows it to the registry. Both live in one jail, the images live on a volume that outlives the jail, and the firewall of the jail lets in only the addresses you name.
Nothing else runs. The users are lines in a configuration file and the passwords are bcrypt hashes from htpasswd.
A jail and a volume
The images on a volume, so the jail stays disposable.
Make the volume first, then the jail, and attach the volume while the jail is stopped:
$ jailops volume create registry-data --comment "the images of the registry" $ jailops create registry --image freebsd-15-1 --network lan --storage default --autostart --comment "a private Docker registry" $ jailops volume attach registry registry-data /var/db/registry $ jailops start registry
Delete or rebuild the jail whenever you like. The volume keeps every image.
Two packages
One from the ports, one from the JailOps repository.
docker-registry comes from the FreeBSD ports. docker-auth comes from the JailOps package repository, which the jail trusts once, with the key and the repository file described in the README of the repository. Then:
$ jailops exec registry -- pkg install -y docker-registry docker-auth $ jailops shell registry
The rest of the page happens inside the jail, in that shell.
A key and a certificate
The server signs the tokens, the registry checks them.
docker_auth signs every token with a key of its own. The registry trusts the matching certificate. Make the pair once:
# cd /usr/local/etc/docker_auth # openssl req -x509 -newkey rsa:4096 -nodes -sha256 -days 3650 -subj "/CN=docker-auth.example.com" -keyout token.key -out token.crt # chgrp docker_auth token.key && chmod 640 token.key
The two services also speak TLS, with the certificate of registry.example.com (from your own CA or from Let's Encrypt). Put it in the same directory as server.crt and its key as server.key, readable by the group docker_auth:
# chgrp docker_auth server.key && chmod 640 server.keyUsers and rules
A password hash and a few lines of rules.
A password is a bcrypt hash. Make it on any machine that has htpasswd (the package apache24 on FreeBSD, apache2-utils on Debian):
$ htpasswd -nB alice
New password:
Re-type new password:
alice:$2y$05$s0meBcryptHashOfThePassword...Everything after alice: goes into /usr/local/etc/docker_auth/auth_config.yml, next to the rules. Alice gets everything under her own name, and every logged-in user may pull library/*:
server:
addr: ":5001"
certificate: "/usr/local/etc/docker_auth/server.crt"
key: "/usr/local/etc/docker_auth/server.key"
token:
issuer: "docker-auth.example.com"
expiration: 900
certificate: "/usr/local/etc/docker_auth/token.crt"
key: "/usr/local/etc/docker_auth/token.key"
users:
"alice":
password: "$2y$05$s0meBcryptHashOfThePassword..."
acl:
- match: {account: "/.+/", name: "${account}/*"}
actions: ["*"]
comment: "A user has full access to the images under the own name"
- match: {account: "/.+/", name: "library/*"}
actions: ["pull"]
comment: "Every user can pull library/*"The first rule that matches decides, and what no rule allows is refused. token.issuer must be the same text in the registry's configuration.
The registry
Point it at the login service.
The registry keeps its images on the volume, serves TLS, and sends every client to docker_auth for a token:
version: 0.1
log:
fields:
service: registry
storage:
filesystem:
rootdirectory: /var/db/registry
http:
addr: :5000
tls:
certificate: /usr/local/etc/docker_auth/server.crt
key: /usr/local/etc/docker_auth/server.key
auth:
token:
realm: https://registry.example.com:5001/auth
service: registry
issuer: docker-auth.example.com
rootcertbundle: /usr/local/etc/docker_auth/token.crtrealm is the address clients are sent to, so it must be a name they can reach. issuer is the same text as in docker_auth.
Start both
Enabled now, and at every boot of the jail.
# sysrc docker_auth_enable=YES docker_registry_enable=YES # service docker_auth start # service docker_registry start
Open the ports
Closed until you allow a source.
A jail answers nobody until a rule lets them in. Clients need both ports: 5000 for the registry and 5001 for the login. Name the addresses of your office as a set and let only them in:
$ jailops firewall address-set create office --address 192.0.2.0/24 --comment "the offices" $ jailops firewall policy create registry --comment "the registry and its login service" $ jailops firewall rule add registry in --port 5000 --from set:office --comment "the registry" $ jailops firewall rule add registry in --port 5001 --from set:office --comment "the login of the registry" $ jailops config set registry firewall.policies registry
Leave out --from to let everyone in. Check a connection before anyone tries it: jailops firewall test --from 192.0.2.7 --to jail:registry --port 5000.
Log in and push
From any machine with Docker.
$ docker login registry.example.com:5000 Username: alice Password: Login Succeeded $ docker tag alpine registry.example.com:5000/alice/alpine $ docker push registry.example.com:5000/alice/alpine
The login service checks the password, signs a token for what alice may do, and the registry lets the push through. Anyone else is refused.
One more user
One more line, and it takes effect.
Make the hash with htpasswd -nB bob, add "bob" under users: in auth_config.yml and save. docker_auth watches its file and reloads it when it changes; a file with a mistake is refused and the server keeps running with the old one.
See also
- The images stay when the jail goes: Volumes for jails, and a volume is backed up once: Back up volumes once.
- Rules, sets and the test command: Firewall for jails.
More articles
Jail updates without cron
Replace the nightly script that upgrades every jail: automatic jail upgrades per image, with a health check, a rollback and a record of every run, what they leave alone, and how a new FreeBSD release comes in.
Read the article: Jail updates without cronJail search and shell
Ctrl+K, a few letters, Shift+Enter: find a jail by name, label or app and open its shell. Labels that filter the jail list, bash in new jails, and the jailops command next to every step.
Read the article: Jail search and shellGetting started with the JailOps CLI
Root on the host, the command line and nothing else: install JailOps, build an image, create a network and a jail, reach it by name, snapshot it, open a port and install an app.
Read the article: Getting started with the JailOps CLIJailOps on a netcup server, with IPv6 that stays up
A /64, a router pair and a FreeBSD default that drops their probes. How every jail gets its own IPv6 address on netcup, and the one sysctl that ends the random unreachable alerts.
Read the article: JailOps on a netcup server, with IPv6 that stays upOne small cloud server, many services, solid IPv6
Run your database, web tier and workers on one low-cost server, each jail with its own IPv6 address, and fix the alerts a shared /64 causes with one sysctl.
Read the article: One small cloud server, many services, solid IPv6Write your own app: memcached, from package to catalog
Turn a small FreeBSD package into a JailOps app: the definition line by line, the offline check, a local install, the five traps, and the pull request that puts it in the catalog.
Read the article: Write your own app: memcached, from package to catalogFrom catalog to running service in one command
Install nginx from the app catalog with one command, see each of its steps, and find the data, the configuration, the logs and the snapshot afterwards.
Read the article: From catalog to running service in one commandA firewall you can read
Policies, address sets and jails by name (jail:web), each with a comment, so the firewall can be reviewed by someone who did not write it.
Read the article: A firewall you can readPostgreSQL and git, closed except for who needs them
Close a database and a git server, then let in exactly the web jail and the office, with a comment on every entry.
Read the article: PostgreSQL and git, closed except for who needs themProjects are boundaries
A project is a boundary. Another project is an external host, so only addresses cross it, written out on both sides. Why that is simpler to review, and what a project does not isolate.
Read the article: Projects are boundariesThe life of a jail
A jail starts at boot only when you declared it with --autostart. Why JailOps does it this way, how the order is decided, and how to see it with jailops boot.
Read the article: The life of a jailTab completion for jailops
Press Tab and get the names of your jails, networks and firewall policies, even on another host. How to install and turn on completion in bash, zsh and fish.
Read the article: Tab completion for jailopsTest the firewall before you trust it
Ask the firewall whether a connection would pass, and why, before you try it. Read the answer, put it in a script, and know what it cannot tell you.
Read the article: Test the firewall before you trust itSee a connection before it happens
Pick a From and a To, a protocol and a port, press Run, and see the connection flow through the firewall: what passes, what stops it, and which rule decides.
Read the article: See a connection before it happensLimit what a jail can use
Give a jail a ceiling for memory, processes, CPU, disk, firewall states and bandwidth, one command each, and know what happens when it reaches it.
Read the article: Limit what a jail can useStop every jail cleanly when the host shuts down
A host that reboots should stop its databases before it stops the disks. How JailOps stops the jails in order, and how to start them in order again.
Read the article: Stop every jail cleanly when the host shuts downOne line in pf.conf
The host's firewall stays yours. JailOps asks for one line, and everything for the jails lives below it.
Read the article: One line in pf.confWhat the host tells you by itself
A pool that reports an error, an uplink that goes down, a jail that reaches a limit: they show up in the event stream by themselves.
Read the article: What the host tells you by itselfNetworks the host controls
No bridge, no DHCP. The host hands out the addresses, gives each jail a link of its own and is the router, so jails cannot see or impersonate each other.
Read the article: Networks the host controlsVolumes: data that outlives a jail
Keep the data in a volume and the jail disposable. One volume can be attached to several jails, has its own snapshots and its own backup.
Read the article: Volumes: data that outlives a jailBack up volumes once
One copy of a volume, however many jails use it. Leave volumes out when you want to, bring them back with the jail.
Read the article: Back up volumes onceNames for jails
A jail is reached by its name inside its project: db.shop.internal, or just db. Create a jail and its name is there; delete it and the name is gone.
Read the article: Names for jails
Try it on one server.
Try the console from the screenshots, install on a clean FreeBSD 15.1 machine, or add JailOps to a host you already run.