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.0

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.0
File Size Uploaded Provenance Actions
hop3_rootd-0.8.0.tar.gz 68.7 kB Without provenance Details for hop3_rootd-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hop3-rootd 0.8.0
File Interpreter ABI Platform Actions
hop3_rootd-0.8.0-py3-none-any.whl Python 3 none any Details for hop3_rootd-0.8.0-py3-none-any.whl

Total release size: 155.9 kB

Release files / hop3_rootd-0.8.0.tar.gz

Download URL hop3_rootd-0.8.0.tar.gz
Size 68.7 kB
Tags Source
SHA-256 checksum
How to use checksums
d1906417a9a2f18372aa2be5bac9b521b3bb33d41f3b412f7ab5b753ad88b0e1
BLAKE2b-256 checksum
How to use checksums
c49fe7ac7590abf82bd1ab5c43fe6c2128f0d935fbfd3de500b527cb007d7843
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Release files / hop3_rootd-0.8.0-py3-none-any.whl

Download URL hop3_rootd-0.8.0-py3-none-any.whl
Size 87.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a983ff9e261c7d220ae286da08c08a33dd12335d0f3f5b641b7ff940a68fc8ec
BLAKE2b-256 checksum
How to use checksums
2db448960e1a9fe3318db07ad035e923f271fbae0e2bcf99284a88c280c8c588
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Security for hop3-rootd 0.8.0

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