ansible.builtin.known_hosts module – Add or remove a host from the `known_hosts` file

Note

This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name known_hosts even without specifying the collections keyword. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.known_hosts for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

Synopsis 

The ansible.builtin.known_hosts module lets you add or remove host keys from the known_hosts file.
Starting at Ansible 2.2, multiple entries per host are allowed, but only one for each key type supported by ssh. This is useful if you’re going to want to use the ansible.builtin.git module over ssh, for example.
If you have a very large number of host keys to manage, you will find the ansible.builtin.template module more useful.

Parameters 

Parameter	Comments
hash_host boolean	Hash the hostname in the known_hosts file. Choices: `false` ← (default) `true`
key string	The SSH public host key, as a string. Required if `state=present`, optional when `state=absent`, in which case all keys for the host are removed. The key must be in the right format for SSH (see sshd(8), section “SSH_KNOWN_HOSTS FILE FORMAT”). Specifically, the key should not match the format that is found in an SSH pubkey file, but should rather have the hostname prepended to a line that includes the pubkey, the same way that it would appear in the known_hosts file. The value prepended to the line must also match the value of the name parameter. Should be of format `<hostname[,IP]> ssh-rsa <pubkey>`. For custom SSH port, `key` needs to specify port as well. See example section.
name aliases: host string / required	The host to add or remove (must match a host specified in key). It will be converted to lowercase so that `ssh-keygen` can find it. Must match with <hostname> or <ip> present in key attribute. For custom SSH port, `name` needs to specify port as well. See example section.
path path	The known_hosts file to edit. The known_hosts file will be created if needed. The rest of the path must exist prior to running the module. Default: `"~/.ssh/known_hosts"`
state string	`present` to add host keys. `absent` to remove host keys. Choices: `"absent"` `"present"` ← (default)

Attributes 

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.
diff_mode	Support: full	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
platform	Platform: posix	Target OS/families that can be operated against

Examples 

- name: Tell the host about our servers it might want to ssh to
  ansible.builtin.known_hosts:
    path: /etc/ssh/ssh_known_hosts
    name: foo.com.invalid
    key: "{{ lookup('ansible.builtin.file', 'pubkeys/foo.com.invalid') }}"

- name: Another way to call known_hosts
  ansible.builtin.known_hosts:
    name: host1.example.com   # or 10.9.8.77
    key: host1.example.com,10.9.8.77 ssh-rsa ASDeararAIUHI324324  # some key gibberish
    path: /etc/ssh/ssh_known_hosts
    state: present

- name: Add host with custom SSH port
  ansible.builtin.known_hosts:
    name: '[host1.example.com]:2222'
    key: '[host1.example.com]:2222 ssh-rsa ASDeararAIUHI324324' # some key gibberish
    path: /etc/ssh/ssh_known_hosts
    state: present

Authors

Matthew Vernon (@mcv21)

ansible.builtin.known_hosts module – Add or remove a host from the known_hosts file

Synopsis

Parameters

Attributes

Examples