diff --git a/README.md b/README.md
index f2014a1..86ede57 100644
--- a/README.md
+++ b/README.md
@@ -1,138 +1,101 @@
# debconf
[](https://github.com/smoeding/puppet-debconf/actions/workflows/CI.yaml)
[](https://forge.puppetlabs.com/stm/debconf)
[](https://raw.githubusercontent.com/smoeding/puppet-debconf/master/LICENSE)
#### Table of Contents
1. [Overview](#overview)
2. [Module Description - What does the module do?](#module-description)
3. [Setup - The basics of getting started with debconf](#setup)
* [What debconf affects](#what-debconf-affects)
* [Setup requirements](#setup-requirements)
4. [Usage - Configuration options and additional functionality](#usage)
5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
5. [Limitations - OS compatibility, etc.](#limitations)
6. [Development - Guide for contributing to the module](#development)
## Overview
Manage entries in the Debian debconf database.
## Module Description
Debian based systems use the debconf database to record configuration choices the user made during the installation of a package. The system uses the stored answers and therefore does not need to query the user again when the package is upgraded or reinstalled at a later time.
The debconf type allows preseeding the database with given answers to allow an unattended package installation or modification of package defaults. The type can optionally also manage the seen flag for an item.
The standard `package` type uses the responsefile parameter to provide a file with preseeded answers during installation. The `debconf` type is a more general solution as it allows to update settings without the need to install the package at the same time.
## Setup
### What debconf affects
The debconf type modifies entries in the Debian debconf database.
### Setup Requirements
This module uses programs provided by the Debian/Ubuntu `debconf` package. Debian assigns the `required` priority to this package so it should already be installed everywhere.
## Usage
Use `debconf-show` or `debconf-get-selections` to find out about valid debconf entries for an installed package.
### Example: Use dash as replacement for the bourne shell
This entry will ensure a symlink from `/bin/sh` to `/bin/dash` if `dpkg-reconfigure dash` is run the next time. It will also mark the question as seen to prevent the installer from asking this question during the installation.
```puppet
debconf { 'dash/sh':
type => 'boolean',
value => 'true',
seen => true,
}
```
**Note**: Although this code is perfectly legal Puppet code, the string `'true'` (not the boolean `true`) will trigger the puppet-lint warning `quoted_booleans`. But we really want to use the string `'true'` and not the boolean truth value here. So in this case we can easily suppress the warning with a [control comment](http://puppet-lint.com/controlcomments/):
```puppet
debconf { 'dash/sh':
type => 'boolean',
value => 'true', # lint:ignore:quoted_booleans
seen => true,
}
```
### Example: Automatically set a root password for MySQL during installation
These two resources preseed the installation of the `mysql-server-5.5` package with the password for the MySQL root user to use. The password has to be set twice because the installation dialog asks two times for the password to detect typos. This password is used if the package is installed after these resources have been created.
```puppet
debconf { 'mysql-root-passwd':
package => 'mysql-server-5.5',
item => 'mysql-server/root_password',
type => 'password',
value => 'secret',
seen => true,
}
debconf { 'mysql-root-passwd-again':
package => 'mysql-server-5.5',
item => 'mysql-server/root_password_again',
type => 'password',
value => 'secret',
seen => true,
}
```
## Reference
-- [**Types**](#types)
- - [Type: debconf](#type-debconf)
-
-### Types
-
-#### Type: `debconf`
-
-Ensures presence or absence of a debconf database entry on Debian based systems.
-
-**Parameters for the `debconf` type:**
-
-##### `ensure`
-
-Ensures whether the resource is present. Valid options: `present`, `absent`. Default value: `present`
-
-##### `item`
-
-The configuration item to manage. This is normally a string with at least one slash character. Valid options: String. Default: the title of the debconf resource.
-
-##### `package`
-
-The name of the package that owns the item. Valid options: String. Default: the prefix of the item parameter up to the first slash character.
-
-##### `type`
-
-The data type of the item. Valid options: `'string'`, `'boolean'`, `'select'`, `'multiselect'`, `'note'`, `'text'`, `'password'`, `'title'`. This parameter is mandatory if `ensure` is `present`. Default: Undefined.
-
-##### `value`
-
-The value to set. Valid options: String. Default: Undefined.
-
-##### `seen`
-
-Optionally set the `seen` flag for `item`. The `seen` flag is used by the packaging system to decide if the associated configuration question should be asked during an installation. This parameter can be left undefined if the `seen` flag should not be managed. The packaging system normally sets this flag to `true` if an item is modified.
-
-The parameter can be a boolean value and the flag is set to the specified value. Valid options: `true`, `false` or undefined. Default value: Undefined.
-
-## Limitations
+See [REFERENCE.md](https://github.com/smoeding/puppet-debconf/blob/master/REFERENCE.md)
This module is only useful on Debian based systems where the debconf database is used.
A control comment may be needed to suppress puppet-lint warnings when you set boolean values. See the [Usage](#usage) section for an example.
The value of the `type` parameter is only used when an item is created. It is not updated if the value of the item is changed later.
## Development
Feel free to send pull requests for new features.
diff --git a/REFERENCE.md b/REFERENCE.md
new file mode 100644
index 0000000..6b7a8eb
--- /dev/null
+++ b/REFERENCE.md
@@ -0,0 +1,112 @@
+# Reference
+
+
+
+## Table of Contents
+
+### Resource types
+
+* [`debconf`](#debconf): Manage debconf database entries on Debian based systems.
+
+## Resource types
+
+### `debconf`
+
+This type can either set or remove a value for a debconf database
+entry. It uses multiple programs from the `debconf` package.
+
+#### Examples
+
+##### Set a select value
+
+```puppet
+debconf { 'tzdata/Areas':
+ type => 'select',
+ value => 'Europe',
+}
+```
+
+##### Set a boolean value
+
+```puppet
+debconf { 'dash/sh':
+ type => 'boolean',
+ value => 'true',
+}
+```
+
+##### Set a boolean value in a specified package and mark as seen
+
+```puppet
+debconf { 'libraries/restart-without-asking':
+ package => 'libc6',
+ type => 'boolean',
+ value => 'true',
+ seen => true,
+}
+```
+
+#### Properties
+
+The following properties are available in the `debconf` type.
+
+##### `ensure`
+
+Valid values: `present`, `absent`
+
+Specifies whether the resource should exist. Setting this to
+"absent" tells Puppet to remove the debconf entry if it exists, and
+negates the effect of any other parameters.
+
+Default value: `present`
+
+##### `seen`
+
+Valid values: ``true``, ``false``
+
+The value of the 'seen' flag. This can be left undefined or be one
+of the boolean values true or false.
+
+##### `value`
+
+Valid values: `%r{\S}`
+
+The value for the item (e.g. 'Europe').
+
+#### Parameters
+
+The following parameters are available in the `debconf` type.
+
+* [`item`](#item)
+* [`package`](#package)
+* [`provider`](#provider)
+* [`type`](#type)
+
+##### `item`
+
+Valid values: `%r{^[a-z0-9][a-z0-9:.+-]+\/[a-zA-Z0-9\/_.+-]+$}`
+
+The item name. This string must have the following format: the
+package name, a literal slash char and the name of the question (e.g.
+'tzdata/Areas').
+
+##### `package`
+
+Valid values: `%r{^[a-z0-9][a-z0-9:.+-]+$}`
+
+The package the item belongs to. The default is the first part (up
+to the first '/') of the item parameter (e.g. 'tzdata').
+
+##### `provider`
+
+The specific backend to use for this `debconf` resource. You will seldom need to specify this --- Puppet will usually
+discover the appropriate provider for your platform.
+
+##### `type`
+
+Valid values: `string`, `boolean`, `select`, `multiselect`, `note`, `text`, `password`, `title`
+
+The type of the item. This can only be one of the following
+values: string, boolean, select, multiselect, note, text, password,
+title.
+
diff --git a/lib/puppet/type/debconf.rb b/lib/puppet/type/debconf.rb
index 86ef82d..95a6029 100644
--- a/lib/puppet/type/debconf.rb
+++ b/lib/puppet/type/debconf.rb
@@ -1,95 +1,102 @@
# debconf.rb --- The debconf type
Puppet::Type.newtype(:debconf) do
desc <<-EOT
- Manage debconf database entries on Debian based systems. This type
- can either set or remove a value for a debconf database entry. It
- uses multiple programs from the 'debconf' package.
-
- Examples:
-
- debconf { 'tzdata/Areas':
- type => 'select',
- value => 'Europe',
- }
-
- debconf { 'dash/sh':
- type => 'boolean',
- value => 'true',
- }
-
- debconf { 'libraries/restart-without-asking':
- package => 'libc6',
- type => 'boolean',
- value => 'true',
- seen => true,
- }
+ @summary
+ Manage debconf database entries on Debian based systems.
+
+ This type can either set or remove a value for a debconf database
+ entry. It uses multiple programs from the `debconf` package.
+
+ @example Set a select value
+ debconf { 'tzdata/Areas':
+ type => 'select',
+ value => 'Europe',
+ }
+
+ @example Set a boolean value
+ debconf { 'dash/sh':
+ type => 'boolean',
+ value => 'true',
+ }
+
+ @example Set a boolean value in a specified package and mark as seen
+ debconf { 'libraries/restart-without-asking':
+ package => 'libc6',
+ type => 'boolean',
+ value => 'true',
+ seen => true,
+ }
EOT
def munge_boolean(value)
case value
when true, 'true', :true
:true
when false, 'false', :false
:false
else
raise(Puppet::Error, 'munge_boolean only takes booleans')
end
end
ensurable do
+ desc 'Specifies whether the resource should exist. Setting this to
+ "absent" tells Puppet to remove the debconf entry if it exists, and
+ negates the effect of any other parameters.'
+
defaultvalues
defaultto :present
end
newparam(:item, namevar: true) do
desc "The item name. This string must have the following format: the
package name, a literal slash char and the name of the question (e.g.
'tzdata/Areas')."
newvalues(%r{^[a-z0-9][a-z0-9:.+-]+\/[a-zA-Z0-9\/_.+-]+$})
end
newparam(:package) do
desc "The package the item belongs to. The default is the first part (up
to the first '/') of the item parameter (e.g. 'tzdata')."
newvalues(%r{^[a-z0-9][a-z0-9:.+-]+$})
defaultto { @resource[:item].split('/', 2).first }
end
newparam(:type) do
desc "The type of the item. This can only be one of the following
values: string, boolean, select, multiselect, note, text, password,
title."
newvalues(:string, :boolean, :select, :multiselect,
:note, :text, :password, :title)
end
newproperty(:value) do
desc "The value for the item (e.g. 'Europe')."
newvalues(%r{\S})
munge { |value| value.strip } # Remove leading and trailing spaces
end
newproperty(:seen, boolean: true) do
desc "The value of the 'seen' flag. This can be left undefined or be one
of the boolean values true or false."
newvalues(:true, :false)
munge do |value|
@resource.munge_boolean(value)
end
end
validate do
unless self[:type]
unless self[:ensure].to_s == 'absent'
raise(Puppet::Error, 'type is a required attribute')
end
end
end
end