Ansible Role: serdigital64.security.sec_key_ssh¶
Purpose¶
Manage SSH Keys provisioning.
Supported features in the current version:
- Create private/public key pairs
- Install public key from file or string to remote user@host
- Register remote host as known
The sec_key_ssh Ansible-Role is part of the A:Platform64 project and is available in the security Ansible-Collection.
Usage¶
The following example is an Ansible Playbook that includes all the supported features:
use this link if viewing the doc on github
---
- name: "Security / Key / SSH / Usage example"
hosts: "localhost"
gather_facts: true
vars:
test_user: "{{ lookup('env', 'USER') }}"
test_group: "{{ test_user }}"
test_home: "/home/{{ test_user }}"
test_repo: "/home/{{ test_user }}/keys"
test_host: "localhost"
pre_tasks:
- name: "Create key path"
ansible.builtin.file:
state: "directory"
mode: "0700"
path: "{{ test_repo }}"
tasks:
- name: "Example: Create OpenSSH RSA private/public key pair"
vars:
sec_key_ssh:
setup: true
sec_key_ssh_pairs:
- file: "rsa-4096b"
path: "{{ test_repo }}"
owner: "{{ test_user }}"
group: "{{ test_group }}"
type: "rsa"
size: "4096"
ansible.builtin.include_role:
name: "serdigital64.security.sec_key_ssh"
- name: "Example: Register host in known_hosts file"
vars:
sec_key_ssh:
setup: true
sec_key_ssh_knownhosts:
- file: "{{ test_repo }}/known_hosts"
owner: "{{ test_user }}"
group: "{{ test_group }}"
hash: false
hosts:
- "{{ test_host }}"
ansible.builtin.include_role:
name: "serdigital64.security.sec_key_ssh"
...
The playbook can be run by executing:
# Set ANSIBLE_COLLECTIONS_PATHS to the default location. Change as needed.
ANSIBLE_COLLECTIONS_PATHS="${HOME}/.ansible/collections"
ansible-playbook "${ANSIBLE_COLLECTIONS_PATHS}/ansible_collections/serdigital64/security/playbooks/sec_key_ssh.yml"
Role Parameters¶
Actions¶
- Use action-parameters to control what tasks are enabled for the role to execute.
- Parameters should be declared as task level vars as they are intented to be dynamic.
sec_key_ssh:
setup:
Parameter | Required? | Type | Default | Purpose / Value |
---|---|---|---|---|
sec_key_ssh.setup | no | boolean | false | Enable SSH key setup tasks |
End State¶
- Use end-state parameters to define the target state after role execution.
- Parameters should be declared in host_vars or group_vars as they are intended to be permanent.
sec_key_ssh_pairs:
- file:
path:
owner:
group:
type:
size:
sec_key_ssh_remotes:
- key_file:
key_string:
host:
user:
sec_key_ssh_knownhosts:
- file:
owner:
group:
hash:
hosts:
Parameter | Required? | Type | Default | Purpose / Value |
---|---|---|---|---|
sec_key_ssh_pairs | no | list | Define list of ssh key pairs | |
sec_key_ssh_pairs.0.file | yes | string | Private key file name. Public file will add the .pub extension | |
sec_key_ssh_pairs.0.path | yes | string | Full path where the key pair will be written to | |
sec_key_ssh_pairs.0.owner | yes | string | Key pair owner | |
sec_key_ssh_pairs.0.group | yes | string | Key pair group owner | |
sec_key_ssh_pairs.0.type | no | string | Key pair type. Valid format as in ssh-keygen | |
sec_key_ssh_pairs.0.size | no | string | Key pair size | |
sec_key_ssh_remotes | no | list | Define list of remote hosts where public keys will be installed to | |
sec_key_ssh_remotes.0.key_file | yes | string | Full path to the public key file in the source host | |
sec_key_ssh_remotes.0.key_string | yes | string | Public key content. If set ignore key_file | |
sec_key_ssh_remotes.0.host | yes | string | Host name where the key will be installed to | |
sec_key_ssh_remotes.0.user | yes | string | To what user the key will be installed to | |
sec_key_ssh_knownhosts | no | list | Define list of hosts to register as known | |
sec_key_ssh_knownhosts.0.file | yes | string | Full path to the known_hosts file | |
sec_key_ssh_knownhosts.0.owner | yes | string | Known_hosts file owner | |
sec_key_ssh_knownhosts.0.group | yes | string | Known_hosts file group owner | |
sec_key_ssh_knownhosts.0.hash | no | bolean | false | Hash the hostname before registering? |
sec_key_ssh_knownhosts.0.hosts | yes | list | List of hosts to register in the known_hosts file. Use FQDNs |
Deployment¶
OS Compatibility¶
The operating system compatibility list is defined in the variable: sec_key_ssh_platforms
Dependencies¶
- Ansible Collections:
- community.crypto
- openssh_keypair
- ansible.posix
- authorized_key
- community.crypto
Prerequisites¶
The Ansible engine must be already installed and configured for privileged access and remote execution.
In addition the following prerequisites must be met:
- Packages:
- OpenSSH Client
Installation Procedure¶
Manually install Ansible Collections from the Ansible Galaxy repository:
ansible-galaxy collection install --upgrade serdigital64.security
Automatic installation is also available by deploying A:Platform64
Contributing¶
Help on implementing new features and maintaining the code base is welcomed.
Please see the guidelines for further details.