| name | remote-systems-administration |
| description | Administer and troubleshoot remote Linux, FreeBSD, NetBSD, OpenBSD, and macOS systems safely, one host or a fleet at a time. Use when a task requires SSH, Ansible, Paramiko, POSIX diagnostics, service management, software updates, system configuration, firewall changes, or evidence-led remote operations. |
| license | MIT |
| compatibility | Requires legitimate remote access. Native SSH is the baseline; Ansible or Python with Paramiko is optional for fleet automation. |
Remote Systems Administration
Use this as an operating decision layer, not a bag of remote commands. Unix-like systems share a vocabulary but not an implementation. Identify the target's platform and active control plane before choosing a command.
Operating contract
- Discover before changing. Record target identity, production status, OS and release, service manager, package manager, firewall, access route, privilege path, and current state. Do not infer them from hostname, memory, or inventory labels.
- Use the smallest valid control plane. Native SSH for a bounded one-host task; Ansible for repeatable desired state across a fleet; Paramiko only when a Python program genuinely needs SSH protocol control that the first two cannot provide.
- Protect access first. Before changing SSH, routing, DNS, a firewall, privilege escalation, or a network interface, establish a tested rollback and a second recovery path. Keep the current session alive until the new path works.
- Preview, constrain, verify. Limit the target set; use native validation, dry-run, diff, or a canary when available; then verify the affected service and its user-visible boundary. A zero exit code proves only that command ran.
- Report evidence, not a story. Preserve bounded per-host results: target, command category, before/after evidence, failures, rollback state, and the remaining uncertainty. Never paste secrets, keys, full configuration files, or unbounded logs into the response.
Run the shared classification probe in references/portable-operations.md, then load the matching OS/family overlay and run its command preflight. Select a mutation command only after the required preflight and safety gate.
Read-only discovery handoff
Use this compact format after a preflight. Fill a field only from observed evidence; otherwise write unknown or not supplied.
- Target and scope:
- Observed platform and control planes:
- Bounded evidence:
- Unknown or blocked:
- Next safe action:
First response: classify the job
| Situation | Default path | Do not do |
|---|
| Diagnose or make one bounded change on one host | Native ssh with a read-only preflight and bounded command/range; do not use a live-follow stream such as tail -f | Do not open an interactive shell and make unrecorded edits |
| Repeat the same desired state across hosts | Ansible inventory + playbook, canary/serial rollout | Do not loop ssh blindly across production hosts |
| Python must coordinate SSH channels, SFTP, or a custom protocol flow | Paramiko with strict host-key verification and explicit timeouts | Do not disable host-key checks or turn a script into ad hoc fleet control |
| The platform/control plane is unknown | Run bounded discovery from references/portable-operations.md | Do not use systemctl, apt, pfctl, or launchctl based on a guess |
| Change affects connectivity, firewall, authentication, reboot, storage, or deletion | Load references/safety-and-verification.md first | Do not mutate before a rollback and recovery path are explicit |
Required preflight for every mutation
Before the first state-changing command, confirm:
- exact host(s), environment, and authorized scope;
- OS/release and applicable platform overlay;
- service manager, package manager, firewall implementation, and configuration owner;
- access identity, elevation method, and whether the connection traverses a bastion;
- intended state, expected blast radius, rollback command or artifact, and stop condition;
- validation at both the component layer and the relevant external boundary.
Connectivity/access pre-execution gate: explicitly name authorization, retained session, independent recovery path, tested rollback, stop condition, and component plus external-boundary verification. If any is unknown, stop before execution.
Read-only discovery may proceed without confirmation. Read-only means no persistent state: do not create rollback scripts or captures, stage update metadata, alter files, or call a state-changing operation preflight. Stop once the needed platform and control-plane evidence is established. Destructive actions, privilege changes, firewall/remote-access changes, package removals, storage operations, and reboot/shutdown require an explicit directive after this preflight.
Routing references
| Need | Load | File |
|---|
| SSH, POSIX diagnostics, bounded output, file transfer, logs, and host discovery | Portable operations | references/portable-operations.md |
| Ansible administration, inventories, roles, collections, secrets, linting, Molecule, rollout, troubleshooting, or platform-specific automation | Ansible administration | references/ansible.md |
| Paramiko, or a compact comparison of fleet-control choices and result-accounting requirements | Fleet automation | references/fleet-automation.md |
| Linux classification, init discovery, cross-family safety, or an unknown/minimal derivative | Linux classification | references/linux.md |
| Debian, Ubuntu, or an APT/dpkg host after release and ownership discovery | Debian/Ubuntu overlay | references/linux-debian-ubuntu.md |
| RHEL, Fedora, or a compatible RPM/DNF host after vendor support and lifecycle discovery | RHEL/Fedora overlay | references/linux-rhel-fedora.md |
| SLES, openSUSE, or a zypper/RPM host, including transactional-root discovery | SUSE overlay | references/linux-suse.md |
| Arch Linux or an Arch-derived pacman host after support/repository discovery | Arch overlay | references/linux-arch.md |
| Alpine Linux or an apk/OpenRC host after persistence-mode discovery | Alpine overlay | references/linux-alpine.md |
| FreeBSD rc(8), rc.conf, pkg, jails, and pf/ipfw routing | FreeBSD overlay | references/freebsd.md |
| NetBSD rc.d, rc.conf, service, and pkgsrc routing | NetBSD overlay | references/netbsd.md |
| OpenBSD rcctl, rc.conf.local, pkg_add, syspatch, and pf | OpenBSD overlay | references/openbsd.md |
| launchd, softwareupdate, configuration profiles, pf, and macOS operational limits | macOS overlay | references/macos.md |
| Mutation gates, safety classes, rollback, and verification evidence | Safety and verification | references/safety-and-verification.md |
| Primary documentation and source freshness | Source index | references/source-index.md |
Platform boundary
Do not flatten platform differences:
systemctl is not a BSD or macOS service manager.rcctl is OpenBSD-specific; FreeBSD uses rc scripts and service.launchctl domains and labels are not systemd units.apt, dnf, pacman, pkg, pkg_add, softwareupdate, and brew have different update, rollback, and package-origin semantics.- Linux nftables, BSD PF, and the macOS Application Firewall are separate control planes. Never translate rules mechanically.
Scope boundaries
This skill covers host-level Unix operations. Route containers to docker-compose, clusters to kubernetes, encrypted tailnet policy to tailscale, detection/remediation components to crowdsec, and reliability process design to site-reliability-engineering.
It does not authorize credential recovery, security-boundary bypass, production deletion, provider-console operations, or an unreviewed operating-system upgrade.
Common pitfalls
- Running the right command on the wrong platform. Discover the service/package/firewall manager before acting.
- Treating an SSH connection as proof of authority. Connection success does not confirm sudo policy, host identity, or authorization for the change.
- Using
StrictHostKeyChecking=no or Paramiko AutoAddPolicy. An unknown host key is an identity event, not a convenience prompt.
- Parallelizing first. Establish the procedure on one canary, then roll out in bounded batches with a stop condition.
- Calling a service healthy because it started. Check process/unit state, logs, listening endpoint, and the relevant dependent or external boundary.
- Confusing package upgrades with OS upgrades. Platform release lifecycle, kernel/base-system updates, and third-party packages have different procedures.
- Repairing a remote host through an access-path change without a rollback. Preserve a live session and independent recovery channel.
Verification checklist
