Skip to main content

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 dedicated inet hop3 nftables table.
  • nginx.reload, nginx.validate_config — wrap the privileged nginx commands previously granted to hop3-server via /etc/sudoers.d/hop3 (now retired).
  • daemon.health, daemon.handshake — introspection.

What this is not

  • A policy enforcement layer. SO_PEERCRED admits the hop3 user; structural validation rejects malformed requests. There is no per-op authorization, no policy file. Operator-level "did you mean this?" prompts live in hop3 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)

Source distribution for hop3-rootd 0.8.1
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)

Table of built distributions (wheels) for hop3-rootd 0.8.1
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page