What this module does #
SSH is the way into your server: the encrypted channel you connect through to administer it. Making sure that door is properly fitted —with the right keys and no extra locks— is what separates a secure server from an exposed one.
The ssh module brings the tasks of that remote access together in a single command: it manages the user's authorized keys (add, list, remove), controls the host keys the server identifies itself with to clients, shows the active sessions, and checks or reapplies the sshd hardening defined in your configuration. Every operation that touches sshd validates the configuration first (sshd -t) so a mistaken change can't lock you out.
Keep a session open while you change keys or restart sshd: that way, if something goes wrong, you're still in to fix it. By default the module works on the managed user ubuntu; use --user to operate on another.
Common tasks #
Pick what you want to do. Each recipe comes with the command already written — just swap in your own user or key, and hit Copy.
1
View SSH access status
Check at a glance that sshd is active and properly configured.
Connect to your server over SSH as the ubuntu user and run:
$ sudo imaxe ssh statusNeed it for a script? Add --json and you'll get the same information, machine-readable:
$ sudo imaxe ssh status --jsonsshd is active, which port it listens on, and a summary of the applied hardening.2
Add or remove an authorized key
Grant access to a new machine or revoke one you no longer use.
First, look at which keys are currently authorized for the managed user:
$ sudo imaxe ssh keys listAdd a public key by passing it as an argument (or use - to read it from standard input):
$ sudo imaxe ssh keys add "ssh-ed25519 AAAAC3Nz... ana@portatil" --comment "ana@portatil"No longer need it? Remove it by its fingerprint or its comment:
$ sudo imaxe ssh keys remove "ana@portatil"authorized_keys is updated. Check the result with keys list.3
Regenerate host keys after cloning
Essential after creating a machine from an AMI.
When you clone an image, every copy inherits the same server identity. Generate fresh, unique host keys for this machine:
$ sudo imaxe ssh hostkeys regenerate --yes4
Review and reapply the hardening
Check that sshd is still configured as it should be, and fix it if not.
Compare the current hardening with the desired one (the one your configuration defines):
$ sudo imaxe ssh harden showAny differences? Reapply the hardening from the YAML and reload sshd safely:
$ sudo imaxe ssh harden reapplysshd reloads without dropping your session.5
View sessions and restart sshd
See who's connected and apply changes without fear of locking yourself out.
List the SSH sessions active right now:
$ sudo imaxe ssh sessionsTo apply configuration changes, prefer reload (it doesn't drop connections); use restart only if a full restart is needed. Both validate the configuration first:
$ sudo imaxe ssh reload
$ sudo imaxe ssh restartBefore restarting sshd or changing the port, keep a second emergency session open. If, on reconnecting, you get a different host key warning after a hostkeys regenerate, that's expected: accept the new identity.
Synopsis #
imaxe ssh <subcomando> [<subcomando-anidado>] [argumentos] [flags]Operations that read or modify sshd, the authorized keys or the host keys require root privileges (use sudo). The keys, hostkeys and harden groups gather their own nested subcommands. Add --json to status, sessions, keys list or harden show for output suitable for scripting.
Subcommands #
| Subcommand | What it does | Relevant flags |
|---|---|---|
| status | sshd status: active, port and hardening summary. | --json |
| keys list | Lists the managed user's authorized keys. | --user, --json |
| keys add | Adds a public key (from argument or stdin). | --user, --comment |
| keys remove | Removes a key by fingerprint or comment. | --user |
| hostkeys regenerate | Regenerates the host keys (critical after cloning an AMI; changes the fingerprint). | --yes |
| sessions | Lists the active SSH sessions. | --json |
| harden show | Shows the current hardening against the desired one. | --json |
| harden reapply | Reapplies the hardening from the YAML and reloads sshd. | — |
| restart | Restarts sshd, validating the configuration first (sshd -t). | — |
| reload | Reloads sshd, validating the configuration first (sshd -t). | — |
Arguments and flags #
| Argument / Flag | Type | Default | Description |
|---|---|---|---|
| <clave> req. | string | — | In keys add: the public key, or - to read it from stdin. |
| <selector> req. | string | — | In keys remove: fingerprint (SHA256:...) or comment of the key to remove. |
| --user | string | ubuntu | User whose authorized_keys is queried or modified (in keys list/add/remove). |
| --comment | string | — | In keys add: comment associated with the key to identify it later. |
| --yes | bool | false | In hostkeys regenerate: confirms without prompting (changes the fingerprint clients see). |
| --json | bool | false | In status, sessions, keys list and harden show: emits the result as JSON on stdout. |
Files and paths #
| Path | Contents |
|---|---|
| /etc/imaxe/ssh.yml | Module configuration: port, login policies (root, password, public key), allowed users, managed user and host key regeneration. |
| /home/<usuario>/.ssh/authorized_keys | The managed user's authorized public keys that keys add/remove modify. |
| /etc/ssh/sshd_config.d/ | Fragments of sshd configuration where the hardening is applied. |
| /etc/ssh/ssh_host_*_key | Host keys that identify the server and that hostkeys regenerate renews. |
Example ssh.yml:
port: 22
permit_root_login: "no"
password_authentication: "no"
pubkey_authentication: "yes"
allow_users: []
managed_user: ubuntu
hostkeys:
regenerate_on_first_boot: trueExit codes and logs #
Each run returns a code you can check with echo $? — handy for chaining in scripts:
sshd -t validation failed; nothing was applied.Follow the service log live while debugging:
$ sudo journalctl -u ssh -f
$ sudo imaxe ssh harden show --jsonTroubleshooting #
| Symptom | Likely cause | Fix |
|---|---|---|
| Returns CONFIG (code 3) | The hardening or a manual change left sshd with an invalid configuration. | Review the diff with imaxe ssh harden show and fix it; validation prevents applying a broken config. |
| On reconnecting, a different host key warning | The host keys were regenerated (expected after cloning an AMI). | This is normal: accept the new identity on the client and update your known_hosts. |
keys add returns NOTFOUND (code 4) | The user given in --user doesn't exist on the system. | Check the username or use the default managed one (ubuntu). |
| I can no longer log in with a password | password_authentication is set to "no" by the hardening. | This is intentional: log in with a public key and manage them with imaxe ssh keys. |
Stuck with the SSH module?
Write to us with the output of «imaxe <module> status --json» and we'll get back to you fast.