hop3-rootd
Privileged-operations agent for Hop3. Runs as root; exposes a narrow control-plane API to hop3-server (running unprivileged as the hop3 user) over a Unix domain socket.
See notes/adrs/041-privileged-operations-agent.md for the design rationale and notes/adrs/040-network-firewall-and-port-exposure.md for the firewall integration that motivated v1's op set.
What this is
hop3-rootd is the kernel-boundary executor for Hop3's runtime privileged actions. The unprivileged hop3-server reaches it via a Unix socket; rootd validates each request structurally, applies the privileged action (nftables mutation, nginx reload, etc.), and returns a typed result.
In v1 the operations are:
firewall.add_rule,firewall.remove_rule,firewall.list_rules— manage rules in a dedicatedinet hop3nftables table.nginx.reload,nginx.validate_config— wrap the privileged nginx commands previously granted tohop3-servervia/etc/sudoers.d/hop3(now retired).daemon.health,daemon.handshake— introspection.
What this is not
- A policy enforcement layer. SO_PEERCRED admits the
hop3user; structural validation rejects malformed requests. There is no per-op authorization, no policy file. Operator-level "did you mean this?" prompts live inhop3 deploy, not in rootd. - A general-purpose privileged-shell daemon. Rootd never accepts shell strings; every operation is a typed intent with a fixed argument schema.
Deployment
hop3-rootd ships as a stdlib-only Python package and is installed by hop3-installer alongside hop3-server. It runs as a hardened systemd unit (full ProtectX suite, CapabilityBoundingSet=CAP_NET_ADMIN, syscall filter, resource limits). The socket is at /run/hop3-rootd/socket, mode 0660, group hop3.
Development
# Run unit tests (no privileges needed)
pytest tests/a_unit/ -v
# Run integration tests (requires root + nftables)
sudo pytest tests/b_integration/ -v
# Lint
ruff check src tests
ruff format src tests
License
Apache-2.0 — Copyright (c) 2026, Abilian SAS
Metadata
Release files for hop3-rootd 0.8.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hop3_rootd-0.8.1.tar.gz | 69.8 kB | Without provenance | Details for hop3_rootd-0.8.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hop3_rootd-0.8.1-py3-none-any.whl | Python 3 | none | any | Details for hop3_rootd-0.8.1-py3-none-any.whl |
Total release size: 158.1 kB
Release files / hop3_rootd-0.8.1.tar.gz
| Download URL | hop3_rootd-0.8.1.tar.gz |
|---|---|
| Size | 69.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
851b3d2543c7977ce13d4bfe77638c6452735b4476cb3e9b0b4b2dafd4e30370
|
|
BLAKE2b-256 checksum How to use checksums |
9c618d6a80736131a0bddc30395a61bd58077050ba9ce666f7525054cb31b045
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / hop3_rootd-0.8.1-py3-none-any.whl
| Download URL | hop3_rootd-0.8.1-py3-none-any.whl |
|---|---|
| Size | 88.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b0419fb4cd63641d74198fb287796f2e54be7387735a58253b0100ce71aa08f1
|
|
BLAKE2b-256 checksum How to use checksums |
df8b5de4efe4d4152a0fb6a2d2b3466c061e62ab6e4632ad472a551b820362e8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Security for hop3-rootd 0.8.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.