Skip to content

known_hosts

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin
Added in version 1.9.

Synopsis

  • The M(ansible.builtin.known_hosts) module lets you add or remove host keys from the C(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 M(ansible.builtin.git) module over ssh, for example.
  • If you have a very large number of host keys to manage, you will find the M(ansible.builtin.template) module more useful.

Parameters

Parameter Defaults / Choices Comments
hash_host
bool		 Default: no
 Hash the hostname in the known_hosts file.
Version Added: 2.3
key
str		 The SSH public host key, as a string.
Required if O(state=present), optional when O(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 C( ssh-rsa ).
For custom SSH port, O(key) needs to specify port as well. See example section.
name
str
required		 The host to add or remove (must match a host specified in key). It will be converted to lowercase so that C(ssh-keygen) can find it.
Must match with or present in key attribute.
For custom SSH port, O(name) needs to specify port as well. See example section.
path
path		 Default: ~/.ssh/known_hosts
 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.
state
str		 Default: present
Choices: absent, present		 V(present) to add host keys.
V(absent) to remove host keys.

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)