Puppet Strings

voxpupuli · Jul 22, 2021 · 9050e38 · 9050e38
1 parent 680bbc9
commit 9050e38
Show file tree

Hide file tree

Showing 5 changed files with 265 additions and 115 deletions.
diff --git a/README.md b/README.md
@@ -2,82 +2,5 @@
 
 [![Build Status](https://travis-ci.org/voxpupuli/puppet-sftp_jail.png?branch=master)](https://travis-ci.org/voxpupuli/puppet-sftp_jail)
 
-#### Table of Contents
-
-1. [Overview](#overview)
-2. [Usage - Configuration options and additional functionality](#usage)
-    * [Examples](#examples)
-      * [Single user](#single-user)
-      * [Shared jail](#shared-jail)
-3. [Parameters](#parameters)
-    * [Jail](#jail)
-    * [User](#user)
-
-This module leverages saz-ssh to more easily create a more robust-ier SFTP jail. Because of how SSH key pairs work in Linux, this module creates a home dir for each jail user, so that keys can be added to `authorized_keys` and a homedir assigned without the nasty problem of the user escaping from the jail and landing in `/` because of a mistaken homedir assignment.
-
-## Usage
-
-### Examples
-
-#### Single user
-
-The `sftp_jail::jail` resource creates a jail with a single home directory and an `incoming` directory. `incoming` is owned by the user and group provided when declaring the resource:
-
-
-```puppet
-    sftp_jail::jail { 'myjail':
-      user  => 'bbriggs',
-      group => 'bbriggs',
-    }
-```
-
-#### Shared jail
-
-Sometimes, more than one user will need to access the same jail, but with different permissions. For instance, one may need read-write access while another is limited to read-only. In such a case, first create the jail with your write user and set up a match_group that redirects users. Again, the users and groups must already exist.
-
-```puppet
-    sftp_jail::jail { 'shared_jail':
-      user        => 'writeuser',
-      group       => 'writegroup',
-      match_group => 'sftpusers',
-    }
-```
-Now add a user to your jail.
-
-```puppet
-    sftp_jail::user { 'readuser':
-      jail => '/chroot/shared_jail',
-    }
-```
-
-To share write access to `/incoming`, set the `group` parameter of `sftp_jail::jail` to a group that is common to both users, such as the `sftpusers` group that you might use to redirect users into a jail.
-
-## Parameters
-
-### Jail
-
-#### user
-
-The user that will own the corresponding home directory in the jail, giving the user a place to land. Also sets user ownership for `/incoming`.
-
-#### group
-
-The group that will own the corresponding home directory in the jail, giving the user a place to land. Also sets group ownership for `/incoming`.
-
-#### match_group
-
-Set the group that SSHd will look for when redirecting users to the jail. Useful for shared jails. Defaults to the value of `group`.
-
-### User
-
-#### user
-
-The username that will own the corresponding home directory in the jail, giving the user a place to land. Defaults to resource title.
-
-#### group
-
-The group that will own the corresponding home directory in the jail, giving the user a place to land. Defaults to resource title.
-
-#### jail
-
-The path of the jail's base directory, such as `/chroot/myjail`. Do not include a trailing slash.
+## Overview
+This module leverages saz-ssh to more easily create a more robust-ier SFTP jail. Because of how SSH key pairs work in Linux, this module creates a home dir for each jail user, so that keys can be added to `authorized_keys` and a homedir assigned without the nasty problem of the user escaping from the jail and landing in `/` because of a mistaken homedir assignment.
diff --git a/REFERENCE.md b/REFERENCE.md
@@ -0,0 +1,189 @@
+# Reference
+
+<!-- DO NOT EDIT: This document was generated by Puppet Strings -->
+
+## Table of Contents
+
+### Classes
+
+* [`sftp_jail`](#sftp_jail): Manage SFTP Jails
+
+### Defined types
+
+* [`sftp_jail::jail`](#sftp_jailjail): One SFTP Jail where users get "chrooted" into
+* [`sftp_jail::user`](#sftp_jailuser): Adds a user's home directory to an SFTP jail.
+
+## Classes
+
+### <a name="sftp_jail"></a>`sftp_jail`
+
+Manage SFTP Jails
+
+#### Parameters
+
+The following parameters are available in the `sftp_jail` class:
+
+* [`chroot_base`](#chroot_base)
+
+##### <a name="chroot_base"></a>`chroot_base`
+
+Data type: `Stdlib::Absolutepath`
+
+All jails are located in this directory.
+
+Default value: `'/chroot'`
+
+## Defined types
+
+### <a name="sftp_jailjail"></a>`sftp_jail::jail`
+
+A jail can have one or multiple users. With multiple users, they can share
+some date via the `/incomming` directory.
+
+#### Examples
+
+##### Single user
+
+```puppet
+# The `sftp_jail::jail` resource creates a jail with a single home directory
+# and an `incoming` directory. `incoming` is owned by the user and group
+# provided when declaring the resource:
+sftp_jail::jail { 'myjail':
+  user  => 'bbriggs',
+  group => 'bbriggs',
+}
+```
+
+##### Shared jail
+
+```puppet
+# Sometimes, more than one user will need to access the same jail, but with
+# different permissions. For instance, one may need read-write access while
+# another is limited to read-only. In such a case, first create the jail with
+# your write user and set up a match_group that redirects users. Again, the
+# users and groups must already exist.
+sftp_jail::jail { 'shared_jail':
+  user        => 'writeuser',
+  group       => 'writegroup',
+  match_group => 'sftpusers',
+}
+# Now add a user to your jail.
+sftp_jail::user { 'readuser':
+  jail => '/chroot/shared_jail',
+}
+# To share write access to `/incoming`, set the `group` parameter of
+# `sftp_jail::jail` to a group that is common to both users, such as the
+# `sftpusers` group that you might use to redirect users into a jail.
+```
+
+#### Parameters
+
+The following parameters are available in the `sftp_jail::jail` defined type:
+
+* [`jail_name`](#jail_name)
+* [`user`](#user)
+* [`group`](#group)
+* [`match_group`](#match_group)
+* [`password_authentication`](#password_authentication)
+
+##### <a name="jail_name"></a>`jail_name`
+
+Data type: `Any`
+
+The jails name.
+
+Default value: `$name`
+
+##### <a name="user"></a>`user`
+
+Data type: `Any`
+
+The user that will own the corresponding home directory in the jail, giving
+the user a place to land. Also sets user ownership for `/incoming`.
+
+Default value: ``undef``
+
+##### <a name="group"></a>`group`
+
+Data type: `Any`
+
+The group that will own the corresponding home directory in the jail,
+giving the user a place to land. Also sets group ownership for `/incoming`.
+
+Default value: ``undef``
+
+##### <a name="match_group"></a>`match_group`
+
+Data type: `Any`
+
+Set the group that SSHd will look for when redirecting users to the jail.
+Useful for shared jails. Defaults to the value of `group`.
+
+Default value: ``undef``
+
+##### <a name="password_authentication"></a>`password_authentication`
+
+Data type: `Any`
+
+OpenSSH Password Authentication
+
+Default value: `'no'`
+
+### <a name="sftp_jailuser"></a>`sftp_jail::user`
+
+Used for shared jails to allow multiple users to write, or to allow one user
+to write and others to read-only.
+
+#### Examples
+
+##### Add user to the jail `myjail`
+
+```puppet
+sftp_jail::user {'bob':
+  jail => '/chroot/myjail',
+}
+```
+
+##### Add user to the jail `myjail` and assign permissions
+
+```puppet
+sftp_jail::user{'bob':
+  group => 'myjail_write',
+  jail  => '/chroot/myjail',
+}
+```
+
+#### Parameters
+
+The following parameters are available in the `sftp_jail::user` defined type:
+
+* [`user`](#user)
+* [`group`](#group)
+* [`jail`](#jail)
+
+##### <a name="user"></a>`user`
+
+Data type: `Any`
+
+The username that will own the corresponding home directory in the jail,
+giving the user a place to land.
+
+Default value: `$name`
+
+##### <a name="group"></a>`group`
+
+Data type: `Any`
+
+The group that will own the corresponding home directory in the jail.
+
+Default value: `$name`
+
+##### <a name="jail"></a>`jail`
+
+Data type: `Any`
+
+The path of the jail's base directory, such as `/chroot/myjail`. Do not
+include a trailing slash.
+
+Default value: ``undef``
+
diff --git a/manifests/init.pp b/manifests/init.pp
@@ -1,14 +1,7 @@
-# Class: sftp_jail
-# ===========================
+# @summary Manage SFTP Jails
 #
-# Full description of class sftp_jail here.
-#
-# Parameters
-# ----------
-#
-# * `sample parameter`
-#   Explanation of what this parameter affects and what it defaults to.
-#   e.g. "Specify one or more upstream ntp servers as an array."
+# @param chroot_base
+#   All jails are located in this directory.
 #
 class sftp_jail (
   Stdlib::Absolutepath $chroot_base = '/chroot',

diff --git a/manifests/jail.pp b/manifests/jail.pp
@@ -1,3 +1,54 @@
+# @summary One SFTP Jail where users get "chrooted" into
+#
+# A jail can have one or multiple users. With multiple users, they can share
+# some date via the `/incomming` directory.
+#
+# @example Single user
+#   # The `sftp_jail::jail` resource creates a jail with a single home directory
+#   # and an `incoming` directory. `incoming` is owned by the user and group
+#   # provided when declaring the resource:
+#   sftp_jail::jail { 'myjail':
+#     user  => 'bbriggs',
+#     group => 'bbriggs',
+#   }
+#
+# @example Shared jail
+#   # Sometimes, more than one user will need to access the same jail, but with
+#   # different permissions. For instance, one may need read-write access while
+#   # another is limited to read-only. In such a case, first create the jail with
+#   # your write user and set up a match_group that redirects users. Again, the
+#   # users and groups must already exist.
+#   sftp_jail::jail { 'shared_jail':
+#     user        => 'writeuser',
+#     group       => 'writegroup',
+#     match_group => 'sftpusers',
+#   }
+#   # Now add a user to your jail.
+#   sftp_jail::user { 'readuser':
+#     jail => '/chroot/shared_jail',
+#   }
+#   # To share write access to `/incoming`, set the `group` parameter of
+#   # `sftp_jail::jail` to a group that is common to both users, such as the
+#   # `sftpusers` group that you might use to redirect users into a jail.
+#
+# @param jail_name
+#   The jails name.
+#
+# @param user
+#   The user that will own the corresponding home directory in the jail, giving
+#   the user a place to land. Also sets user ownership for `/incoming`.
+#
+# @param group
+#   The group that will own the corresponding home directory in the jail,
+#   giving the user a place to land. Also sets group ownership for `/incoming`.
+#
+# @param match_group
+#   Set the group that SSHd will look for when redirecting users to the jail.
+#   Useful for shared jails. Defaults to the value of `group`.
+#
+# @param password_authentication
+#   OpenSSH Password Authentication
+#
 define sftp_jail::jail (
   $jail_name               = $name,
   $user                    = undef,