ssh-systemd-diagnostics

Files (1)

• SKILL.md

SKILL.md (first lines)

# SSH Systemd Diagnostics

Safe-tier read tools for inspecting systemd services without root access, plus
dedicated mutation tools for lifecycle operations that require root.

All tools in Section 1 carry `tags={"safe", "read", "group:systemctl"}` and
work without any `ALLOW_*` flag. Lifecycle operations in Section 3 are
dangerous-tier wrappers (`ssh_systemctl_start` / `_stop` / `_restart` /
`_reload` / `_enable` / `_disable` / `_mask` / `_unmask` / `_reset_failed`)
that require `ALLOW_DANGEROUS_TOOLS=true` and root on the target (use a
sudoers-enabled SSH account or `ssh_sudo_exec` for the rare `daemon-reload`
case that has no dedicated wrapper).

## Default-on cheatsheet rejection (since v1.9.0)

`ssh_exec_run` refuses commands that have a native MCP tool -- see
`skills/ssh-exec-run/SKILL.md`. The native-tool flow below avoids
that. Composite scripts (where the script IS the artefact) opt out
via `SSH_EXEC_ALLOW_CHEATSHEET_PATTERNS=true` at the operator level.

---

## 1. Tools

### `ssh_systemctl_status`

Full status output for one unit, equivalent to `systemctl status <unit>
--no-pager`. Returns `{stdout, exit_code, active_state}` where `active_state`
is parsed from the `Active:` line. Exit code 3 (inactive/dead) is data, not
an error.

```python
ssh_systemctl_status(host="web01", unit="nginx.service")
```

### `ssh_systemctl_is_active`

Checks whether a unit is active. Returns `{state}` which is one of
`active | inactive | failed | activating | deactivating | reloading | unknown`.

```python
ssh_systemctl_is_active(host="web01", unit="nginx.service")
```

### `ssh_systemctl_is_enabled`

Checks the unit's enablement state. Returns `{state}` which is one of
`enabled | disabled | masked | static | indirect | linked | generated |
transient | bad | not-found | unknown` (and their `-runtime` variants).

```python
ssh_systemctl_is_enabled(host="web01", unit="nginx.service")
```

### `ssh_systemctl_is_failed`

Checks whether a unit is in a `failed` state. Returns `{failed, state,
exit_code}`. `failed=True` when the unit IS in a failed state (exit code 0
from `systemctl is-failed`).

```python
ssh_systemctl_is_failed(host="web01", unit="nginx.service")
```

### `ssh_systemctl_list_units`

Lists loaded units, optionally filtered by glob pattern, state, or unit type.
Parsed into `{units: [{unit, load, active, sub, description}, ...]}`.

```python
# All running services
ssh_systemctl_list_units(host="web01", state="running")

# Failed units of any type
ssh_systemctl_list_units(host="web01", state="failed", unit_type="service")

# Units matching a glob
ssh_systemctl_list_units(host="web01", pattern="nginx*")
```

### `ssh_systemctl_show`

Returns machine-readable properties for a unit as `{properties: dict[str,
str]}`. Use `properties=` to limit output to specific keys.

```python
# All properties
ssh_systemctl_show(host="web01", unit="nginx.service")

# Targeted diagnostic properties
ssh_systemctl_show(
    host="web01",
    unit="nginx.service",
    properties=["ActiveState", "ExecMainStatus", "Result", "NRestarts"],
)
```

### `ssh_systemctl_cat`

Returns the full unit file content (including drop-in overrides) as raw
stdout. Equivalent to `systemctl cat <unit>`.

```python
ssh_systemctl_cat(host="web01", unit="nginx.service")
```

### `ssh_journalctl`

Returns recent journal entries for a unit. Defaults to the last 200 lines.
Hard cap at 1000 lines per call; use `since=` to narrow instead of raising
the line count.

```python
# Last 200 lines (default)
ssh_journalctl(host="web01", unit="nginx.service")

# Last 15 minutes with a keyword filter
ssh_journalctl(host="web01", unit="nginx.service", since="15m", grep="error")

From Nightreaver/python-ssh-mcp, GPL-3.0.

More from Nightreaver/python-ssh-mcp