docs: add readme, changelog, contributing and man page
This commit is contained in:
+200
@@ -0,0 +1,200 @@
|
||||
.TH SSHCTL 1 "2026-09-12" "sshctl v0.1.1" "SSH Configuration Management"
|
||||
.SH NAME
|
||||
sshctl \- SSH configuration management toolkit
|
||||
.SH SYNOPSIS
|
||||
.B sshctl
|
||||
[\fIoptions\fR] \fIcommand\fR [\fIargs\fR]
|
||||
.SH DESCRIPTION
|
||||
sshctl is a CLI toolkit for managing SSH configurations, including host definitions,
|
||||
proxy jumps, permissions, connectivity checks, and shell completions.
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
.B \-V, \-\-version
|
||||
Show version.
|
||||
.TP
|
||||
.B \-v, \-\-verbose
|
||||
Verbose output.
|
||||
.TP
|
||||
.B \-c, \-\-config \fIPATH\fR
|
||||
Path to ssh_config file (default: ~/.ssh/config).
|
||||
.TP
|
||||
.B \-\-install-completion
|
||||
Install shell completion for the current shell.
|
||||
.TP
|
||||
.B \-\-show-completion
|
||||
Show shell completion script.
|
||||
.TP
|
||||
.B \-\-help
|
||||
Show help message.
|
||||
.SH COMMANDS
|
||||
.SS Core
|
||||
.TP
|
||||
.B init
|
||||
Initialize an SSH config directory structure.
|
||||
.TP
|
||||
.B validate
|
||||
Validate SSH config structure and option correctness.
|
||||
.TP
|
||||
.B diff
|
||||
Show differences between generated and current SSH config.
|
||||
.TP
|
||||
.B tree
|
||||
Show the conf.d directory tree with host counts.
|
||||
.TP
|
||||
.B backup
|
||||
Create a timestamped backup of the SSH config directory.
|
||||
.TP
|
||||
.B restore \fIPATH\fR
|
||||
Restore SSH config from a backup.
|
||||
.TP
|
||||
.B cleanup [\-n]
|
||||
Remove stale SSH control master sockets. Use \-n for dry-run.
|
||||
.TP
|
||||
.B log [\-n \fICOUNT\fR] [\-f]
|
||||
Show recent sshctl activity log. Use \-f to follow (tail mode).
|
||||
.TP
|
||||
.B check [\-p \fIPATTERN\fR] [\-t \fISECS\fR] [\-c \fIMAX\fR]
|
||||
Check connectivity to all hosts in parallel.
|
||||
.TP
|
||||
.B exec \fICOMMAND\fR [\-p \fIPATTERN\fR] [\-t \fISECS\fR]
|
||||
Run a command in parallel across hosts.
|
||||
.TP
|
||||
.B csv [\-o \fIFILE\fR]
|
||||
Export host inventory to CSV.
|
||||
.TP
|
||||
.B ansible [\-o \fIFILE\fR] [\-\-group-by \fIFIELD\fR]
|
||||
Generate Ansible inventory from SSH config.
|
||||
.TP
|
||||
.B chmod [\-\-fix]
|
||||
Check (and optionally fix) SSH directory permissions.
|
||||
.SS Config Management
|
||||
.TP
|
||||
.B config show
|
||||
Show all global Host * options.
|
||||
.TP
|
||||
.B config set \fIKEY\fR \fIVALUE\fR
|
||||
Set an option in the Host * block.
|
||||
.TP
|
||||
.B config unset \fIKEY\fR
|
||||
Remove an option from the Host * block.
|
||||
.SS Host Management
|
||||
.TP
|
||||
.B host list
|
||||
List all host aliases with HostName and ProxyJump.
|
||||
.TP
|
||||
.B host show \fIALIAS\fR
|
||||
Show options for a specific host.
|
||||
.TP
|
||||
.B host add \fIALIAS\fR \fIHOSTNAME\fR [\-u \fIUSER\fR] [\-p \fIPORT\fR] [\-j \fIJUMP\fR]
|
||||
Add a new host alias.
|
||||
.TP
|
||||
.B host edit \fIALIAS\fR \-\-option \fIOPT\fR \-\-value \fIVAL\fR
|
||||
Set an option on an existing host.
|
||||
.TP
|
||||
.B host remove \fIALIAS\fR [\-f]
|
||||
Remove a host from its config file (with confirmation).
|
||||
.SS ProxyJump
|
||||
.TP
|
||||
.B jump on
|
||||
Restore all saved ProxyJump directives.
|
||||
.TP
|
||||
.B jump off
|
||||
Save and remove all ProxyJump lines from conf.d files.
|
||||
.TP
|
||||
.B jump status
|
||||
List all hosts with ProxyJump and show saved state.
|
||||
.TP
|
||||
.B jump auto [\-\-subnet] [\-\-no-subnet]
|
||||
Auto-detect network environment:
|
||||
- Probes jump gateways via TCP (respects HostName/Port from SSH config)
|
||||
- Falls back to SSID matching against known internal networks
|
||||
- Enables or disables ProxyJump accordingly.
|
||||
.TP
|
||||
.B jump networks [list|add|remove] [\-\-ssid \fIPATTERN\fR]
|
||||
Manage internal SSID patterns for auto-detection (defaults: MobinNet*, Mobin*).
|
||||
.SS Setup
|
||||
.TP
|
||||
.B setup completions [\-\-shell \fIbash|zsh|fish\fR]
|
||||
Install shell completions.
|
||||
.TP
|
||||
.B setup agent [start|stop|restart|status]
|
||||
Manage the ssh-agent systemd user service.
|
||||
.TP
|
||||
.B setup timer [cleanup|check] [\-a enable|disable|status]
|
||||
Manage systemd timers.
|
||||
.TP
|
||||
.B setup git
|
||||
Initialize git tracking in ~/.ssh.
|
||||
.TP
|
||||
.B setup init
|
||||
Full setup: git + agent + timers + completions.
|
||||
.SS Diagnostics
|
||||
.TP
|
||||
.B heal [\-\-dry-run]
|
||||
Detect and fix config issues (typos, invalid options).
|
||||
.SH FILES
|
||||
.TP
|
||||
.I ~/.ssh/config
|
||||
Main SSH configuration file.
|
||||
.TP
|
||||
.I ~/.ssh/conf.d/
|
||||
Directory containing host definition files.
|
||||
.TP
|
||||
.I ~/.ssh/control.d/
|
||||
SSH control master socket directory.
|
||||
.TP
|
||||
.I ~/.ssh/keys.d/
|
||||
SSH key files.
|
||||
.TP
|
||||
.I ~/.ssh/scripts/
|
||||
Helper scripts and systemd unit files.
|
||||
.TP
|
||||
.I ~/.ssh/report/events.ndjson
|
||||
Activity event log (NDJSON format).
|
||||
.TP
|
||||
.I ~/.ssh/.proxyjump_save
|
||||
Saved ProxyJump state (temporary, created by \fBjump off\fR).
|
||||
.TP
|
||||
.I ~/.ssh/.internal_ssids
|
||||
Internal SSID patterns for auto-detect.
|
||||
.SH ENVIRONMENT
|
||||
.TP
|
||||
.B SSH_AUTH_SOCK
|
||||
SSH agent socket path. Set to \fI$XDG_RUNTIME_DIR/ssh-agent.socket\fR when using
|
||||
the built-in systemd ssh-agent service.
|
||||
.SH EXAMPLES
|
||||
.TP
|
||||
Initialize a new SSH config directory:
|
||||
sshctl init
|
||||
.TP
|
||||
List all hosts:
|
||||
sshctl host list
|
||||
.TP
|
||||
Show host details:
|
||||
sshctl host show myserver
|
||||
.TP
|
||||
Disable all ProxyJump directives (internal network):
|
||||
sshctl jump off
|
||||
.TP
|
||||
Auto-detect network and toggle ProxyJump:
|
||||
sshctl jump auto
|
||||
.TP
|
||||
Add current Wi-Fi as internal network:
|
||||
sshctl jump networks add
|
||||
.TP
|
||||
Check all hosts connectivity:
|
||||
sshctl check
|
||||
.TP
|
||||
View activity log:
|
||||
sshctl log \-n 20
|
||||
.TP
|
||||
Validate and fix config issues:
|
||||
sshctl heal
|
||||
.SH BUGS
|
||||
Report issues at https://git.panahifar.ir/ahp/sshctl/issues
|
||||
.SH AUTHOR
|
||||
Amir Husayn Panahifar
|
||||
.SH SEE ALSO
|
||||
.BR ssh (1),
|
||||
.BR ssh_config (5),
|
||||
.BR sshd (8)
|
||||
Reference in New Issue
Block a user