diff options
author | Bobosila Victor <victor.bobosila@puppet.com> | 2021-10-04 12:16:24 +0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-10-04 12:16:24 +0300 |
commit | efd4d1b3213336c4f7f4a04fb5075a0ce1682fa6 (patch) | |
tree | 3fd2f83f284b673ea19187b395101e1663171cf8 /REFERENCE.md | |
parent | 9a54482d64ef21e8b6b1063845a96b1a72cd8f3c (diff) | |
parent | b2565ef72fd744e31cc3e3836dc5b69e193fa88c (diff) | |
download | puppet-sshkeys_core-efd4d1b3213336c4f7f4a04fb5075a0ce1682fa6.tar.gz puppet-sshkeys_core-efd4d1b3213336c4f7f4a04fb5075a0ce1682fa6.tar.bz2 |
Merge pull request #48 from GabrielNagy/MODULES-11197/pdk-update
(MODULES-11197) Update to pdk-templates 2.2.0
Diffstat (limited to 'REFERENCE.md')
-rw-r--r-- | REFERENCE.md | 195 |
1 files changed, 115 insertions, 80 deletions
diff --git a/REFERENCE.md b/REFERENCE.md index 1e6b933..82340d0 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -1,38 +1,24 @@ # 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 +<!-- DO NOT EDIT: This document was generated by Puppet Strings --> -### ssh_authorized_key +## Table of Contents -Manages SSH authorized keys. Currently only type 2 keys are supported. +### Resource types -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_authorized_key`](#ssh_authorized_key): Manages SSH authorized keys. Currently only type 2 keys are supported. +* [`sshkey`](#sshkey): Installs and manages ssh host keys. - ssh-rsa AAAAB3Nza[...]qXfdaQ== nick@magpie.example.com +## Resource types -...would translate to the following resource: +### <a name="ssh_authorized_key"></a>`ssh_authorized_key` - ssh_authorized_key { 'nick@magpie.example.com': - ensure => present, - user => 'nick', - type => 'ssh-rsa', - key => 'AAAAB3Nza[...]qXfdaQ==', - } +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. 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, - } +unmanaged SSH keys on a per-user basis. This will remove any keys in `~/.ssh/authorized_keys` that aren't being managed with `ssh_authorized_key` resources. See the documentation of the @@ -42,26 +28,48 @@ managed with `ssh_authorized_key` resources. See the documentation of the SSH key should be installed, the `ssh_authorized_key` resource will autorequire that user. +#### Examples -#### Properties +##### Thus, a key that appears in your `~/.ssh/id_rsa.pub` file like this... -The following properties are available in the `ssh_authorized_key` type. +```puppet -##### `ensure` +ssh-rsa AAAAB3Nza[...]qXfdaQ== nick@magpie.example.com +``` -Valid values: present, absent +##### ...would translate to the following resource: -The basic property that the resource should be in. +```puppet -Default value: present +ssh_authorized_key { 'nick@magpie.example.com': + ensure => present, + user => 'nick', + type => 'ssh-rsa', + key => 'AAAAB3Nza[...]qXfdaQ==', +} +``` -##### `type` +##### Do this with the `user` resource type's `purge_ssh_keys` attribute: -Valid values: ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, ssh-ed25519, dsa, ed25519, rsa +```puppet -Aliases: "dsa"=>"ssh-dss", "ed25519"=>"ssh-ed25519", "rsa"=>"ssh-rsa" +user { 'nick': + ensure => present, + purge_ssh_keys => true, +} +``` -The encryption type used. +#### 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` ##### `key` @@ -75,10 +83,20 @@ other attributes): * Key identifiers / comments, such as 'joe@joescomputer.local' --- put these in the `name` attribute/resource title. -##### `user` +##### `options` -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. +Key options; see sshd(8) for possible values. Multiple values +should be specified as an array. For example, you could use the +following to install a SSH CA that allows someone with the +'superuser' principal to log in as root + + ssh_authorized_key { 'Company SSH CA': + ensure => present, + user => 'root', + type => 'ssh-ed25519', + key => 'AAAAC3NzaC[...]CeA5kG', + options => [ 'cert-authority', 'principals=\"superuser\"' ], + } ##### `target` @@ -88,28 +106,41 @@ are stored in a non-standard location, for instance when not in `~user/.ssh/authorized_keys`. The parent directory must be present if the target is in a privileged path. -Default value: absent +Default value: `absent` -##### `options` +##### `type` -Key options; see sshd(8) for possible values. Multiple values -should be specified as an array. For example, you could use the -following to install a SSH CA that allows someone with the -'superuser' principal to log in as root +Valid values: `ssh-dss`, `ssh-rsa`, `ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384`, `ecdsa-sha2-nistp521`, `ssh-ed25519`, `sk-ecdsa-sha2-nistp256@openssh.com`, `sk-ssh-ed25519@openssh.com`, `ssh-rsa-cert-v01@openssh.com`, `ssh-ed25519-cert-v01@openssh.com`, `ssh-dss-cert-v01@openssh.com`, `ecdsa-sha2-nistp256-cert-v01@openssh.com`, `ecdsa-sha2-nistp384-cert-v01@openssh.com`, `ecdsa-sha2-nistp521-cert-v01@openssh.com`, `dsa`, `ed25519`, `rsa`, `ecdsa-sk`, `ed25519-sk` - ssh_authorized_key { 'Company SSH CA': - ensure => present, - user => 'root', - type => 'ssh-ed25519', - key => 'AAAAC3NzaC[...]CeA5kG', - options => [ 'cert-authority', 'principals="superuser"' ], - } +Aliases: `"dsa"=>"ssh-dss", "ed25519"=>"ssh-ed25519", "rsa"=>"ssh-rsa", "ecdsa-sk"=>"sk-ecdsa-sha2-nistp256@openssh.com", "ed25519-sk"=>"sk-ssh-ed25519@openssh.com"` + +The encryption type used. + +##### `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. #### Parameters The following parameters are available in the `ssh_authorized_key` type. -##### `name` +* [`drop_privileges`](#drop_privileges) +* [`name`](#name) +* [`provider`](#provider) + +##### <a name="drop_privileges"></a>`drop_privileges` + +Valid values: ``true``, ``false``, `yes`, `no` + +Whether to drop privileges when writing the key file. This is +useful for creating files in paths not writable by the target user. Note +the possible security implications of managing file ownership and +permissions as a privileged user. + +Default value: ``true`` + +##### <a name="name"></a>`name` namevar @@ -120,23 +151,17 @@ 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. -##### `drop_privileges` - -Whether to drop privileges when writing the key file. This is -useful for creating files in paths not writable by the target user. Note -the possible security implications of managing file ownership and -permissions as a privileged user. - -Default value: `true` +##### <a name="provider"></a>`provider` -### sshkey +The specific backend to use for this `ssh_authorized_key` resource. You will seldom need to specify this --- Puppet will +usually discover the appropriate provider for your platform. -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. +### <a name="sshkey"></a>`sshkey` +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 @@ -144,19 +169,16 @@ The following properties are available in the `sshkey` type. ##### `ensure` -Valid values: present, absent +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 +Default value: `present` -Aliases: "dsa"=>"ssh-dss", "ed25519"=>"ssh-ed25519", "rsa"=>"ssh-rsa" +##### `host_aliases` -The encryption type used. Probably ssh-dss or ssh-rsa. +Any aliases the host might have. Multiple values must be +specified as an array. ##### `key` @@ -170,11 +192,6 @@ other attributes): * 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 @@ -184,10 +201,28 @@ the `parsed` provider. The following parameters are available in the `sshkey` type. -##### `name` +* [`name`](#name) +* [`provider`](#provider) +* [`type`](#type) + +##### <a name="name"></a>`name` namevar The host name that the key is associated with. +##### <a name="provider"></a>`provider` + +The specific backend to use for this `sshkey` resource. You will seldom need to specify this --- Puppet will usually +discover the appropriate provider for your platform. + +##### <a name="type"></a>`type` + +Valid values: `ssh-dss`, `ssh-ed25519`, `ssh-rsa`, `ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384`, `ecdsa-sha2-nistp521`, `sk-ecdsa-sha2-nistp256@openssh.com`, `sk-ssh-ed25519@openssh.com`, `dsa`, `ed25519`, `rsa`, `ecdsa-sk`, `ed25519-sk` + +namevar + +Aliases: `"dsa"=>"ssh-dss", "ed25519"=>"ssh-ed25519", "rsa"=>"ssh-rsa", "ecdsa-sk"=>"sk-ecdsa-sha2-nistp256@openssh.com", "ed25519-sk"=>"sk-ssh-ed25519@openssh.com"` + +The encryption type used. Probably ssh-dss or ssh-rsa. |