ansible.builtin.known_hosts (v2.16.5) — module

Install Ansible via pip

Install with pip install ansible-core==2.16.5

Description

The M(ansible.builtin.known_hosts) module lets you add or remove a 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.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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') }}"

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Inputs

    
key:
    description:
    - 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(<hostname[,IP]> ssh-rsa <pubkey>).
    - For custom SSH port, O(key) needs to specify port as well. See example section.
    type: str

name:
    aliases:
    - host
    description:
    - 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, O(name) needs to specify port as well. See example section.
    required: true
    type: str

path:
    default: ~/.ssh/known_hosts
    description:
    - 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.
    type: path

state:
    choices:
    - absent
    - present
    default: present
    description:
    - V(present) to add the host key.
    - V(absent) to remove it.
    type: str

hash_host:
    default: 'no'
    description:
    - Hash the hostname in the known_hosts file.
    type: bool
    version_added: '2.3'
    version_added_collection: ansible.builtin