diff options
| -rw-r--r-- | README.md | 102 | ||||
| -rw-r--r-- | REFERENCE.md | 174 |
2 files changed, 208 insertions, 68 deletions
@@ -1,95 +1,61 @@ # sshkeys_core -Welcome to your new module. A short overview of the generated parts can be found in the PDK documentation at https://puppet.com/pdk/latest/pdk_generating_modules.html . - -The README template below provides a starting point with details about what information to include in your README. - - - - - - - -#### Table of Contents +## Table of Contents 1. [Description](#description) -2. [Setup - The basics of getting started with sshkeys_core](#setup) - * [What sshkeys_core affects](#what-sshkeys_core-affects) - * [Setup requirements](#setup-requirements) - * [Beginning with sshkeys_core](#beginning-with-sshkeys_core) -3. [Usage - Configuration options and additional functionality](#usage) -4. [Limitations - OS compatibility, etc.](#limitations) -5. [Development - Guide for contributing to the module](#development) +2. [Usage - Configuration options and additional functionality](#usage) +3. [Reference - User documentation](#reference) +4. [Development - Guide for contributing to the module](#development) ## Description -Briefly tell users why they might want to use your module. Explain what your module does and what kind of problems users can solve with it. - -This should be a fairly short description helps the user decide if your module is what they want. - - -## Setup - -### What sshkeys_core affects **OPTIONAL** - -If it's obvious what your module touches, you can skip this section. For example, folks can probably figure out that your mysql_instance module affects their MySQL instances. - -If there's more that they should know about, though, this is the place to mention: - -* Files, packages, services, or operations that the module will alter, impact, or execute. -* Dependencies that your module automatically installs. -* Warnings or other important notices. +Manage SSH `authorized_keys`, and `ssh_known_hosts` files. -### Setup Requirements **OPTIONAL** - -If your module requires anything extra before setting up (pluginsync enabled, another module, etc.), mention it here. +## Usage -If your most recent release breaks compatibility or requires particular steps for upgrading, you might want to include an additional "Upgrading" section here. +To manage an authorized key for a user: -### Beginning with sshkeys_core +``` +ssh_authorized_key { 'nick@magpie.example.com': + ensure => present, + user => 'nick', + type => 'ssh-rsa', + key => 'AAAAB3Nza[...]qXfdaQ==', +} +``` -The very basic steps needed for a user to get the module up and running. This can include setup steps, if necessary, or it can be an example of the most basic use of the module. +To manage a known hosts file entry: -## Usage +``` +sshkey { 'github.com': + ensure => present, + type => 'ssh-rsa', + key => 'AAAAB3Nza[...]UFFAaQ==', +} +``` -Include usage examples for common use cases in the **Usage** section. Show your users how to use your module to solve problems, and be sure to include code examples. Include three to five examples of the most important or common tasks a user can accomplish with your module. Show users how to accomplish more complex tasks that involve different types, classes, and functions working in tandem. +More details cana be found in the `REFERENCE.md` file. ## Reference -This section is deprecated. Instead, add reference information to your code as Puppet Strings comments, and then use Strings to generate a REFERENCE.md in your module. For details on how to add code comments and generate documentation with Strings, see the Puppet Strings [documentation](https://puppet.com/docs/puppet/latest/puppet_strings.html) and [style guide](https://puppet.com/docs/puppet/latest/puppet_strings_style.html) - -If you aren't ready to use Strings yet, manually create a REFERENCE.md in the root of your module directory and list out each of your module's classes, defined types, facts, functions, Puppet tasks, task plans, and resource types and providers, along with the parameters for each. +Please see `REFERENCE.md` for the reference documentation. -For each element (class, defined type, function, and so on), list: +This module is documented using Puppet Strings. - * The data type, if applicable. - * A description of what the element does. - * Valid values, if the data type doesn't make it obvious. - * Default value, if any. - -For example: +For a quick primer on how Strings works, please see [this blog post](https://puppet.com/blog/using-puppet-strings-generate-great-documentation-puppet-modules) or the [README.md](https://github.com/puppetlabs/puppet-strings/blob/master/README.md) for Puppet Strings. +To generate documentation locally, run ``` -### `pet::cat` - -#### Parameters - -##### `meow` - -Enables vocalization in your cat. Valid options: 'string'. - -Default: 'medium-loud'. +bundle install +bundle exec puppet strings generate ./lib/**/*.rb ``` - -## Limitations - -In the Limitations section, list any incompatibilities, known issues, or other warnings. +This command will create a browsable `\_index.html` file in the `doc` directory. The references available here are all generated from YARD-style comments embedded in the code base. When any development happens on this module, the impacted documentation should also be updated. ## Development -In the Development section, tell other users the ground rules for contributing to your project and how they should submit their work. +Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can't access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve. -## Release Notes/Contributors/Etc. **Optional** +We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. -If you aren't using changelog, put your release notes here (though you should consider using changelog). You can also add any additional sections you feel are necessary or important to include here. Please use the `## ` header. +For more information, see our [module contribution guide.](https://docs.puppetlabs.com/forge/contributing.html) diff --git a/REFERENCE.md b/REFERENCE.md new file mode 100644 index 0000000..b72e9ee --- /dev/null +++ b/REFERENCE.md @@ -0,0 +1,174 @@ +# Reference + +## Resource types +* [`ssh_authorized_key`](#ssh_authorized_key): Manages SSH authorized keys. Currently only type 2 keys are supported. In their native habitat, SSH keys usually appear as a single long lin +* [`sshkey`](#sshkey): Installs and manages ssh host keys. By default, this type will install keys into `/etc/ssh/ssh_known_hosts`. To manage ssh keys in a differe +## Resource types + +### ssh_authorized_key + +Manages SSH authorized keys. Currently only type 2 keys are supported. + +In their native habitat, SSH keys usually appear as a single long line, in +the format `<TYPE> <KEY> <NAME/COMMENT>`. This resource type requires you +to split that line into several attributes. Thus, a key that appears in +your `~/.ssh/id_rsa.pub` file like this... + + ssh-rsa AAAAB3Nza[...]qXfdaQ== nick@magpie.example.com + +...would translate to the following resource: + + ssh_authorized_key { 'nick@magpie.example.com': + ensure => present, + user => 'nick', + type => 'ssh-rsa', + key => 'AAAAB3Nza[...]qXfdaQ==', + } + +To ensure that only the currently approved keys are present, you can purge +unmanaged SSH keys on a per-user basis. Do this with the `user` resource +type's `purge_ssh_keys` attribute: + + user { 'nick': + ensure => present, + purge_ssh_keys => true, + } + +This will remove any keys in `~/.ssh/authorized_keys` that aren't being +managed with `ssh_authorized_key` resources. See the documentation of the +`user` type for more details. + +**Autorequires:** If Puppet is managing the user account in which this +SSH key should be installed, the `ssh_authorized_key` resource will autorequire +that user. + + +#### Properties + +The following properties are available in the `ssh_authorized_key` type. + +##### `ensure` + +Valid values: present, absent + +The basic property that the resource should be in. + +Default value: present + +##### `type` + +Valid values: ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ssh-ed25519, dsa, ed25519, rsa + +Aliases: "dsa"=>"ssh-dss", "ed25519"=>"ssh-ed25519", "rsa"=>"ssh-rsa" + +The encryption type used. + +##### `key` + +The public key itself; generally a long string of hex characters. The `key` +attribute may not contain whitespace. + +Make sure to omit the following in this attribute (and specify them in +other attributes): + +* Key headers, such as 'ssh-rsa' --- put these in the `type` attribute. +* Key identifiers / comments, such as 'joe@joescomputer.local' --- put these in + the `name` attribute/resource title. + +##### `user` + +The user account in which the SSH key should be installed. The resource +will autorequire this user if it is being managed as a `user` resource. + +##### `target` + +The absolute filename in which to store the SSH key. This +property is optional and should be used only in cases where keys +are stored in a non-standard location, for instance when not in +`~user/.ssh/authorized_keys`. + +Default value: absent + +##### `options` + +Key options; see sshd(8) for possible values. Multiple values +should be specified as an array. + +#### Parameters + +The following parameters are available in the `ssh_authorized_key` type. + +##### `name` + +namevar + +The SSH key comment. This can be anything, and doesn't need to match +the original comment from the `.pub` file. + +Due to internal limitations, this must be unique across all user accounts; +if you want to specify one key for multiple users, you must use a different +comment for each instance. + + +### sshkey + +Installs and manages ssh host keys. By default, this type will +install keys into `/etc/ssh/ssh_known_hosts`. To manage ssh keys in a +different `known_hosts` file, such as a user's personal `known_hosts`, +pass its path to the `target` parameter. See the `ssh_authorized_key` +type to manage authorized keys. + + +#### Properties + +The following properties are available in the `sshkey` type. + +##### `ensure` + +Valid values: present, absent + +The basic property that the resource should be in. + +Default value: present + +##### `type` + +Valid values: ssh-dss, ssh-ed25519, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, dsa, ed25519, rsa + +Aliases: "dsa"=>"ssh-dss", "ed25519"=>"ssh-ed25519", "rsa"=>"ssh-rsa" + +The encryption type used. Probably ssh-dss or ssh-rsa. + +##### `key` + +The key itself; generally a long string of uuencoded characters. The `key` +attribute may not contain whitespace. + +Make sure to omit the following in this attribute (and specify them in +other attributes): + +* Key headers, such as 'ssh-rsa' --- put these in the `type` attribute. +* Key identifiers / comments, such as 'joescomputer.local' --- put these in + the `name` attribute/resource title. + +##### `host_aliases` + +Any aliases the host might have. Multiple values must be +specified as an array. + +##### `target` + +The file in which to store the ssh key. Only used by +the `parsed` provider. + +#### Parameters + +The following parameters are available in the `sshkey` type. + +##### `name` + +namevar + +The host name that the key is associated with. + + |