Install Rookery
Put the Rookery command on the machine you work from. It is one file.
Rookery sets hosts up from Linux. The program contains everything it puts on a host, so installing it means placing one file on your PATH. On macOS and Windows the same program is a client of a Rookery server on another machine.
curl -fsSL https://raw.githubusercontent.com/aiviarium/rookery/main/install.sh | shThe script downloads the latest release for this machine from GitHub, checks it against its SHA-256 and installs it to ~/.local/bin/rookery. Releases have it for Linux on x86_64 and arm64, and for macOS on Apple silicon and Intel.
| Variable | Effect |
|---|---|
ROOKERY_INSTALL_DIR | Install somewhere else than ~/.local/bin |
ROOKERY_VERSION | Install a release tag such as v0.2.0 instead of the latest |
On other architectures, build it with cargo.
Check it:
rookery --version
rookeryWhat else Rookery uses
| For | Needs |
|---|---|
| Setting up a host over SSH or applying its configuration | ssh, python3, ansible-playbook (ansible-core 2.21, which needs Python 3.12 or newer) |
| Building a USB installer | python3, xorriso, curl |
| Hashing passwords | openssl |
| Installing plugins from a registry | npm |
The install script lists what is missing. A source checkout with a .venv gets its own ansible-playbook from there:
python3 -m venv .venv && .venv/bin/pip install -r provision/requirements.txtWhere Rookery keeps things
| What | Where |
|---|---|
| Settings of this machine, listed below | ~/.config/rookery/config.json |
| The other settings, registries, secret values and registry passwords | Rookery's store, by default ~/.local/share/rookery/rookery.db |
| One profile per host, its generated passwords and the record of a machine Rookery created for it | Rookery's store too. rookery host export HOST prints a profile and rookery host credentials HOST the passwords |
Rookery's SSH keys, and the token and setup key of rookery serve | Rookery's store. A key is written to ~/.local/share/rookery/keys/NAME when ssh needs it, and the token to serve.token |
| The key file of an encrypted store | ~/.config/rookery/store.key (setting store_key) |
| Locks held while Rookery creates or changes a host's machine | ~/.local/share/rookery/locks/ |
| Your own plugins | ~/.config/rookery/plugins/, and in Rookery's store what reinstalls them |
| Provisioning source, unpacked from the program | ~/.local/share/rookery/source/ |
| Build output such as the release archive, seeds and installer images | ~/.local/share/rookery/build/ |
| Downloaded Ubuntu installer ISOs | ~/.local/share/rookery/iso/ (setting iso_dir) |
XDG_CONFIG_HOME and XDG_DATA_HOME are honoured. rookery config list prints the paths and settings, and rookery config set KEY VALUE changes one, in the file or in the store. The Settings tab of the home screen does the same. rookery server store status says where the store is and whether it is encrypted. See The store, which also says how to restore an installation from it.
These settings stay in config.json, as they belong to this machine or are needed to open the store:
| Settings | What they are for |
|---|---|
store, store_key, store_ca | Where the store is and how it is opened |
server, server_token | The Rookery server this machine uses, kept by rookery login |
source, iso_dir | Folders on this machine |
Profiles hold Wi-Fi passwords, and the store holds generated passwords and the tailnet's API key. They are in clear text unless the store is encrypted, see The store. Keep the store and its key file private, and keep files that rookery host export writes out of version control.
The provisioning source
The provisioning source is what Rookery puts on a host. It holds the Ansible role with rookeryd and box, the bootstrap scripts and the built-in plugins. It is built into the program and unpacked into the data directory the first time it is needed, and again after an update. The program can be copied to another machine as it is.
Rookery looks for the source in this order:
ROOKERY_SOURCE- the
sourcesetting - a checkout in the current directory, when Rookery is started inside one
- the built-in copy
To work on the role, point Rookery at your checkout, and clear the setting to go back:
rookery config set source ~/src/rookery
rookery config set source ""Last updated on