community.general.ssh_config module – Manage SSH config for user

Note

This module is part of the community.general collection (version 10.7.5).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.ssh_config.

New in community.general 2.0.0

Synopsis

  • Configures SSH hosts with special IdentityFiles and hostnames.

Requirements

The below requirements are needed on the host that executes this module.

  • paramiko

Parameters

Parameter

Comments

add_keys_to_agent

boolean

added in community.general 8.2.0

Sets the AddKeysToAgent option.

Choices:

  • false

  • true

controlmaster

string

added in community.general 8.1.0

Sets the ControlMaster option.

Choices:

  • "yes"

  • "no"

  • "ask"

  • "auto"

  • "autoask"

controlpath

string

added in community.general 8.1.0

Sets the ControlPath option.

controlpersist

string

added in community.general 8.1.0

Sets the ControlPersist option.

dynamicforward

string

added in community.general 10.1.0

Sets the DynamicForward option.

forward_agent

boolean

added in community.general 4.0.0

Sets the ForwardAgent option.

Choices:

  • false

  • true

group

string

Which group this configuration file belongs to.

If none given, user is used.

host

string / required

The endpoint this configuration is valid for.

Can be an actual address on the internet or an alias that will connect to the value of hostname.

host_key_algorithms

string

added in community.general 6.1.0

Sets the HostKeyAlgorithms option.

hostname

string

The actual host to connect to when connecting to the host defined.

identities_only

boolean

added in community.general 8.2.0

Specifies that SSH should only use the configured authentication identity and certificate files (either the default files, or those explicitly configured in the ssh_config files or passed on the ssh command-line), even if ssh-agent or a PKCS11Provider or SecurityKeyProvider offers more identities.

Choices:

  • false

  • true

identity_file

path

The path to an identity file (SSH private key) that will be used when connecting to this host.

File need to exist and have mode 0600 to be valid.

other_options

dictionary

added in community.general 10.4.0

Provides the option to specify arbitrary SSH config entry options via a dictionary.

The key names must be lower case. Keys with upper case values are rejected.

The values must be strings. Other values are rejected.

port

string

The actual port to connect to when connecting to the host defined.

proxycommand

string

Sets the ProxyCommand option.

Mutually exclusive with proxyjump.

proxyjump

string

added in community.general 6.5.0

Sets the ProxyJump option.

Mutually exclusive with proxycommand.

remote_user

string

Specifies the user to log in as.

ssh_config_file

path

SSH config file.

If user and this option are not specified, /etc/ssh/ssh_config is used.

Mutually exclusive with user.

state

string

Whether a host entry should exist or not.

Choices:

  • "present" ← (default)

  • "absent"

strict_host_key_checking

string

Whether to strictly check the host key when doing connections to the remote host.

The value accept-new is supported since community.general 8.6.0.

Choices:

  • "yes"

  • "no"

  • "ask"

  • "accept-new"

user

string

Which user account this configuration file belongs to.

If none given and ssh_config_file is not specified, /etc/ssh/ssh_config is used.

If a user is given, ~/.ssh/config is used.

Mutually exclusive with ssh_config_file.

user_known_hosts_file

string

Sets the user known hosts file option.

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Add a host in the configuration
  community.general.ssh_config:
    user: akasurde
    host: "example.com"
    hostname: "github.com"
    identity_file: "/home/akasurde/.ssh/id_rsa"
    port: '2223'
    state: present
    other_options:
      serveraliveinterval: '30'

- name: Add SSH config with key auto-added to agent
  community.general.ssh_config:
    user: devops
    host: "example.com"
    hostname: "staging.example.com"
    identity_file: "/home/devops/.ssh/id_rsa"
    add_keys_to_agent: true
    state: present

- name: Delete a host from the configuration
  community.general.ssh_config:
    ssh_config_file: "{{ ssh_config_test }}"
    host: "example.com"
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

hosts_added

list / elements=string

A list of host added.

Returned: success

Sample: ["example.com"]

hosts_change_diff

list / elements=string

A list of host diff changes.

Returned: on change

Sample: [{"example.com": {"new": {"hostname": "github.com", "identityfile": ["/tmp/test_ssh_config/fake_id_rsa"], "port": "2224"}, "old": {"hostname": "github.com", "identityfile": ["/tmp/test_ssh_config/fake_id_rsa"], "port": "2224"}}}]

hosts_changed

list / elements=string

A list of host changed.

Returned: success

Sample: ["example.com"]

hosts_removed

list / elements=string

A list of host removed.

Returned: success

Sample: ["example.com"]

Authors

  • Björn Andersson (@gaqzi)

  • Abhijeet Kasurde (@Akasurde)