salt.resources.ssh#

SSH resource module — exposes remote Linux/Unix machines as Salt Resources using the salt-ssh Shell transport layer.

Each ssh resource maps to one remote host reachable via SSH. Because resources share a single loader per type, a minion managing 500 SSH hosts uses one loader rather than 500 proxy processes, each with its own key pair.

This module uses salt.client.ssh.shell.Shell for raw command execution (cmd_run, ping) and salt.client.ssh.Single with the salt-thin bundle for grain collection (grains.items), giving the same complete, accurate grain set that salt-ssh provides.

Configuration (via Pillar; top-level key defaults to resources, overridable with minion option resource_pillar_key):

resources:
  ssh:
    hosts:
      web-01:
        host: 192.168.1.10
        user: root
        priv: /etc/salt/ssh_keys/web-01
      web-02:
        host: 192.168.1.11
        user: admin
        passwd: secretpassword
        no_host_keys: true

Per-host connection parameters:

host: Hostname or IP address of the remote machine (required).
user: SSH login user (default: root).
port: SSH port (default: 22).
priv: Path to the SSH private key file. Mutually exclusive with passwd but both may be specified; when priv is set Salt uses key-based option strings even if passwd is also set.
passwd: SSH password. Prefer key-based authentication for production.
priv_passwd: Passphrase protecting the private key.
sudo: Run commands as root via sudo (default: False).
timeout: SSH connection timeout in seconds (default: 30).
identities_only: Pass -o IdentitiesOnly=yes to prevent the SSH agent from offering unrelated keys (default: False).
no_host_keys: Disable host key checking entirely — sets both StrictHostKeyChecking=no and UserKnownHostsFile=/dev/null (default: False).
ignore_host_keys: Pass -o StrictHostKeyChecking=no without discarding the known-hosts database (default: False).
known_hosts_file: Path to a custom known_hosts file for this host.
ssh_options: List of additional -o Key=Value options passed verbatim to the ssh binary.
keepalive: Enable TCP keepalives (default: True).
keepalive_interval: ServerAliveInterval in seconds (default: from Salt opts or 60).
keepalive_count_max: ServerAliveCountMax (default: from Salt opts or 3).

salt.resources.ssh.cmd_run(cmd, timeout=None)#

Execute a shell command on the current SSH resource.

This is the primary building block for execution modules that target SSH resources — analogous to __proxy__["ssh_sample.cmd"]() in the proxy model. Execution module overrides for the ssh resource type delegate their work here.

Returns a dict with keys:

stdout — standard output from the remote command
stderr — standard error from the remote command
retcode — exit code (0 on success)

Parameters:

cmd (str) -- The shell command to run on the remote host.
timeout (int) -- Optional per-call SSH timeout in seconds. When provided, overrides the connection-level timeout for this call only.

Return type:

dict

CLI Example (via resource execution module):

salt -C 'T@ssh:web-01' ssh_cmd.run 'uptime'

salt.resources.ssh.discover(opts)#

Return the list of SSH resource IDs managed by this minion.

The list is the set of keys under hosts for the ssh type under the configured resource pillar subtree. Adding or removing a host from that Pillar key and running saltutil.refresh_resources updates the Master's Resource Registry without any process restart.

Parameters:: opts (dict) -- The Salt opts dict.
Return type:: list[str]

salt.resources.ssh.grains()#

Return full Salt grains for the current SSH resource.

Runs grains.items on the remote host via the salt-thin bundle (the same mechanism used by salt-ssh), giving us the complete, accurate grain set rather than a hand-crafted subset.

Results are cached in __context__ per resource ID. Call grains_refresh() to force re-collection.

Return type:: dict

salt.resources.ssh.grains_refresh()#

Invalidate the grains cache for the current SSH resource and re-collect.

Return type:: dict

salt.resources.ssh.init(opts)#

Initialize the ssh resource type for this minion.

Called once when the resource type is loaded, before any per-resource operations are dispatched. Reads host configs from the ssh entry under the pillar subtree selected by resource_pillar_key (see salt.utils.resources.pillar_resources_tree()), caches them in __context__["ssh_resource"], and pre-resolves the SSH binary version so that _shell_opts() never has to run a subprocess during a job.

Parameters:: opts (dict) -- The Salt opts dict.

salt.resources.ssh.initialized()#

Return True if init() has completed successfully.

Return type:: bool

salt.resources.ssh.ping()#

Return True if the current SSH resource is reachable via SSH.

Runs echo ping on the remote host. A zero exit code and the expected output indicate that the SSH connection is healthy.

salt.resources.ssh.shutdown(opts)#

Tear down the ssh resource type.

Called when the minion shuts down or the resource type is unloaded. Clears shared type-level state from __context__.

Parameters:: opts (dict) -- The Salt opts dict.

Table of Contents

salt.resources.ssh#