sshkeys

ssh key generaton and distribution with puppet

Module Stats

15,068 downloads

5,965 latest version

3.2 quality score

Support the Puppet Community by contributing to this module

You are welcome to contribute to this module by suggesting new features, currency updates, or fixes. Every contribution is valuable to help ensure that the module remains compatible with the latest Puppet versions and continues to meet community needs. Complete the following steps:

Review the module’s contribution guidelines and any licenses. Ensure that your planned contribution aligns with the author’s standards and any legal requirements.
Fork the repository on GitHub, make changes on a branch of your fork, and submit a pull request. The pull request must clearly document your proposed change.

For questions about updating the module, contact the module’s author.

Version information

released Oct 25th 2018

This version is compatible with:

Start using this module

Installation method

Add this module to your Puppetfile:

mod 'geoffwilliams-sshkeys', '1.1.1'

Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add geoffwilliams-sshkeys

Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install geoffwilliams-sshkeys --version 1.1.1

Documentation

geoffwilliams/sshkeys — version 1.1.1 Oct 25th 2018

sshkeys

Description
Features
Usage - Configuration options and additional functionality
Limitations - OS compatibility, etc.
Development - Guide for contributing to the module

Overview

Provides several methods for generation, distribution and authorization of SSH keys

Features

Per-user management of:

~/.ssh
~/.ssh/id_rsa
~/.ssh/id_rsa.pub
~/.ssh/known_hosts
~/.ssh/authorized_keys
~/.ssh/some_other_key (sshkeys::install_keypair only)
~/.ssh/some_other_key.pub (sshkeys::install_keypair only)

Usage

There are two methods of operation (consult REFERENCE for detailed instructions):

Manual management

Create files with known data sourced from Puppet (Hiera, files from modules, etc):

sshkeys::manual

Suggested uses:

Distributing known keys for sysadmins
Enabling logins from applications using a known key

Generation

Generate files as needed (will be stored on the Puppet Master in /etc/puppetlabs/puppetserver/sshkeys):

sshkeys::authorize
sshkeys::install_keypair
sshkeys::known_host

Suggested uses:

SSH being used as a transport mechanism where the value of the key itself is immaterial and limited in scope, with all parties under puppet control. A good example of this would be rsync between puppet nodes and this is what the module was originally written for.

Important

Since SSH keys are stored on the master when using generation methods, this weakens security somewhat vs how PKIs are intended to work. This can be mitigated by applying the principle of least privilege to accounts that use keys in this way. Also if your Puppet Master is compromised, its game over anyway. Be sure your comfortable with this before using.

Note SSH Keys are read from and generated on the Puppet Master using the sshkeys::sshkey function that ships with this module. When running Puppet in apply mode, the user running the function will normally be root however in agent mode the user would be pe-puppet or equivalent. This prevents us creating files in /etc as pe-puppet has no ability to write there. Instead, we create our own directory at /etc/puppetlabs/puppetserver/sshkeys. Since /etc/puppetlabs/puppetserver is writable by pe-puppet, we are able to write files to this location.

Setup Requirements

Requires all SSH packages are already installed

Limitations

Tested on Debian and Ubuntu
If generation is used, SSH keys will be stored on the master
Only one copy of a given key can be installed per-node when using sshkeys::install_keypair

Development

PRs accepted :)

Testing

This module supports testing using PDQTest.

Test can be executed with:

bundle install
make

See .travis.yml for a working CI example

Reference

Defined types

sshkeys::authorize: Setup authorized_keys file with keys read from the Puppet Master
sshkeys::install_keypair: Generate a public/private keypair on the Puppet Master and distribute to node
sshkeys::known_host: Setup known_hosts file for a given user and host
sshkeys::manual: Distribute pre-generated SSH keys, authorized_hosts and known_hosts

Functions

sshkeys::sshkey: Read an SSH Key from the puppet master, creating it if doesn't already exist

Defined types

sshkeys::authorize

Retrieve the keys listed in the authorized_keys parameter from the Puppet Master and use them to write the authorized_keys file for the local unix user specified in the title. If a key does not exist on the Puppet Master, it will be created when read.

Note replaces any existing authorized_keys file when used

Examples

Reading a single key and adding to `authorized keys`

sshkeys::authorize { "gill":
  authorized_keys => "gill@localhost",
}
# creates /home/gill/.ssh/authorized_keys with the gil@localhost.pub file
# as its content

Reading multiple keys and adding to `authorized_keys`

sshkeys::authorize { "helen":
  authorized_keys => ["gill@localhost", "helen@localhost"],
}
# creates /home/helen/.ssh/authorized_keys with the gil@localhost.pub and
# helen@localhost files concatentated as its content

Parameters

The following parameters are available in the sshkeys::authorize defined type.

`authorized_keys`

Data type: Variant[String, Array[String]]

Array of key names to source from the Puppet Master. These will be used to create the authorized_keys file

`user`

Data type: String

Local system account that this resource is granting access to via SSH. Defaults to $title

Default value: $title

`ssh_dir`

Data type: Optional[String]

Override the default .ssh directory location. Defaults to /home/$user/.ssh

Default value: undef

sshkeys::install_keypair

We use a custom function sshkeys::sshkey to run ssh-keygen on the Puppet Master to generate the keys to download if they are missing. This allows us to install they keypairs without using exported resources etc. One obvious downside of this approach is that the private keys will exist on the master. This is an accepted risk if you want to use this approach.

If you already have a set of keys you want to use, you could replace the files on the master yourself in the /etc/puppetlabs/puppetserver/sshkeys directory, or look at the sshkeys::manual type to copy known keys directly.

You can also use this class to remove a keypair from a node. The files will remain on master until removed manually, however.

to copy the same key multiple times, copy it once with this class and then come up with some other way to copy the remaining files.

Note Limitation: only one user@host combination can be defined per host. If you need

Examples

Creating default SSH keys

sshkeys::install_keypair { "charles@localhost":
  default_files => true,
}
# Would create /home/charles/.ssh/id_rsa

Creating SSH keys based on name

sshkeys::install_keypair { "diane@localhost": }
# Would create /home/diane/.ssh/diane@localhost

Removing default SSH keys for `eve` user

sshkeys::install_keypair { "eve@localhost":
  ensure        => absent,
  default_files => true,
}
# Would delete `/home/eve/.ssh/id_rsa` and `/home/eve/.ssh/id_rsa.pub`

Parameters

The following parameters are available in the sshkeys::install_keypair defined type.

`title`

identify the key to copy from the puppet master to the local machine. Must be in the form user@host. As well as specifying the keypair to copy from the Puppet Master, the title also denotes the local system user to install the keys for

`ensure`

Data type: Enum['present', 'absent']

Whether a keypair should be present or absent

Default value: present

`source`

Data type: String

File on the Puppet Master to source the private key from. The filename of the public key will be computed by appending .pub to this string. This is normally derived fully from the sshkeys::params class and the resource title so is not normally needed

Default value: $title

`ssh_dir`

Data type: Optional[String]

Override the default SSH directory of /home/$user/.ssh

Default value: undef

`default_files`

Data type: Boolean

Write files to id_rsa and id_rsa.pub. This is useful if your only managing a single set of keys. If not, leave this off and key files will be generated based on title. You can then use ssh -i to use the key you want.

Default value: false

`default_filename`

Data type: String

Base filename to use when generating files with the default name.

Default value: "id_rsa"

sshkeys::known_host

Test to see whether ssh-keygen thinks a particular host is in the known_hosts file. If it isn't, obtain and store the key using ssh-keyscan.

Examples

sshkeys::known_host{"frank@localhost":}
# `ssh-keyscan` on `localhost`, results saved to `/home/frank/.ssh/known_hosts`

Parameters

The following parameters are available in the sshkeys::known_host defined type.

`title`

Specify the local system user and remote host to connect to in the format user@host

`ssh_dir`

Data type: Optional[String]

Override the standard location of the SSH directory. Defaults to /home/user/ssh. Note that user is specified in title ONLY

Default value: undef

sshkeys::manual

Manage the ~/.ssh directory and any or all of:

~/.ssh/id_rsa
~/.ssh/id_rsa.pub
~/.ssh/known_hosts
~/.ssh/authorized_keys

For the given user, normally supplied in title.

Files can be supplied:

Inline - Write the supplied content directly to file (file resource content)
Filename - Write file using this URI (file resource source)

It is an error to specify both content and source. Where content is not explicitly mananagd by this Puppet type, we will leave it alone and just fix permissions unless the purge_unmanaged parameter is set true, in which case any of the above files will be deleted if we were not supposed to set content inside them.

Examples

Writing SSH connection settings by content

sshkeys::manual { "alice":
  id_rsa          => $id_rsa,
  id_rsa_pub      => $id_rsa_pub,
  known_hosts     => $known_hosts,
  authorized_keys => $authorized_keys,
}

Writing SSH connection settings by file URI

# You can use any URI supported by the puppet `file` resource `source` parameter...
sshkeys::manual { "bob":
  id_rsa_file          => "/testcase/spec/mock/keys/bob/id_rsa",
  id_rsa_pub_file      => "/testcase/spec/mock/keys/bob/id_rsa.pub",
  known_hosts_file     => "/testcase/spec/mock/keys/known_hosts",
  authorized_keys_file => "/testcase/spec/mock/keys/bob/authorized_keys",
}

Purge unmanaged SSH files

# deletes Ingrid's `known_hosts`, `id_rsa`, `id_rsa.pub`) and sets content
# of `authorized_keys` file to the string `ingrid authorized keys`
sshkeys::manual { "ingrid":
  authorized_keys => "ingrid authorized keys",
  purge_unmanaged => true,
}

Source of the regular authorized_keys file. This can be any location understood by the puppet file resource

Data type: Optional[Any]

Key size to create if we need to create a key

Modules

Discover

Contribute

Puppet

Premium features

Downloads

Resources

About Forge

Getting Started

sshkeys

Support the Puppet Community by contributing to this module

Version information

This version is compatible with:

Start using this module

Documentation

sshkeys

Table of Contents

Overview

Features

Usage

Manual management

Generation

Setup Requirements

Limitations

Development

Testing

Reference

Table of Contents

Defined types

sshkeys::authorize

Examples

Reading a single key and adding to authorized keys

Reading multiple keys and adding to authorized_keys

Parameters

authorized_keys

user

ssh_dir

sshkeys::install_keypair

Examples

Creating default SSH keys

Creating SSH keys based on name

Removing default SSH keys for eve user

Parameters

title

ensure

source

ssh_dir

default_files

default_filename

sshkeys::known_host

Examples

Parameters

title

ssh_dir

sshkeys::manual

Examples

Writing SSH connection settings by content

Writing SSH connection settings by file URI

Purge unmanaged SSH files

Parameters

user

home

group

purge_unmanaged

id_rsa

id_rsa_file

id_rsa_pub

id_rsa_pub_file

known_hosts

known_hosts_file

authorized_keys

authorized_keys_file

Functions

sshkeys::sshkey

sshkeys::sshkey(Any $key_name, Optional[Any] $pub = false, Optional[Any] $passphrase = '', Optional[Any] $comment = '', Optional[Any] $type = 'rsa', Optional[Any] $size = '2048')

key_name

pub

passphrase

comment

type

Reading a single key and adding to `authorized keys`

Reading multiple keys and adding to `authorized_keys`

`authorized_keys`

`user`

`ssh_dir`

Removing default SSH keys for `eve` user

`title`

`ensure`

`source`

`ssh_dir`

`default_files`

`default_filename`

`title`

`ssh_dir`

`user`

`home`

`group`

`purge_unmanaged`

`id_rsa`

`id_rsa_file`

`id_rsa_pub`

`id_rsa_pub_file`

`known_hosts`

`known_hosts_file`

`authorized_keys`

`authorized_keys_file`

`sshkeys::sshkey(Any $key_name, Optional[Any] $pub = false, Optional[Any] $passphrase = '', Optional[Any] $comment = '', Optional[Any] $type = 'rsa', Optional[Any] $size = '2048')`

`key_name`

`pub`

`passphrase`

`comment`

`type`

`size`