Metadata-Version: 2.5
Name: runspec-linux-root
Version: 0.1.0
Summary: Linux admin runnables that need root (packages, reboot, sysctl) for runspec
Project-URL: Documentation, https://runspec.app/
Project-URL: Source, https://github.com/jasonfinestone/runspec/tree/main/packages/python/runspec-linux-root
Project-URL: Changelog, https://github.com/jasonfinestone/runspec/blob/main/packages/python/runspec-linux-root/CHANGELOG.md
Project-URL: Issues, https://github.com/jasonfinestone/runspec/issues
Keywords: linux,packages,root,runnable,runspec,sysadmin
Requires-Python: >=3.10
Requires-Dist: runspec-linux-core>=0.13.0
Requires-Dist: runspec>=0.68.0
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff==0.15.20; extra == 'dev'
Description-Content-Type: text/markdown

# runspec-linux-root

Linux admin tools that need **root**, as [runspec](https://runspec.app/) runnables:

| Tool | What it does | Autonomy |
|---|---|---|
| `list-upgrades` | List packages with an available upgrade (refreshes the index) | autonomous |
| `upgrade-packages` | Refresh the index and upgrade every package | confirm |
| `install-package` | Install packages by name | confirm |
| `remove-package` | Remove packages (`--purge` for config files too) | confirm |
| `autoremove-packages` | Remove packages nothing depends on (`--dry-run` to preview) | confirm |
| `set-sysctl` | Set a kernel parameter, optionally persisted under `/etc/sysctl.d` | confirm |
| `reboot-host` | Reboot, optionally after a delay | confirm |
| `enable-passwordless-sudo` | One-time bootstrap: a validated `/etc/sudoers.d` drop-in | confirm |

They work across apt, dnf, yum, zypper and pacman. The logic lives in
[`runspec-linux-core`](https://pypi.org/project/runspec-linux-core/). The
everyday tools that never need root are in
[`runspec-linux`](https://pypi.org/project/runspec-linux/).

## Install into a root-owned venv

Every tool here declares `run_as = "root"`: root runs this code. So install it
into a venv **only root can change**. A venv owned by a service account would
let that account edit code root later runs.

```bash
sudo python3 -m venv /opt/venvs/admin
sudo /opt/venvs/admin/bin/pip install runspec-linux-root
```

## Who can run them

sudoers decides. An admin runs a tool with sudo:

```bash
sudo /opt/venvs/admin/bin/upgrade-packages
```

runspec checks the process really is root (`enforce_run_as`) and refuses
otherwise, naming the account to `sudo -u` to.

**From runspec-console or the MCP gateway**, the tool is run with `sudo -n`,
which never prompts for a password, so the admin needs a passwordless sudo rule.
`enable-passwordless-sudo` installs one:

- `--scope scoped` allows only this venv's tools, run directly
  (`sudo /opt/venvs/admin/bin/<tool>` from a shell or cron). It does **not**
  cover the console or the gateway, which pass variables to the tool through a
  `sh` prelude so that secrets never go on a command line; sudo then sees `sh`,
  not the tool.
- `--scope all` grants `NOPASSWD: ALL`, which the console and the gateway need.
