diff options
author | Gabriel Nagy <gabriel.nagy@puppet.com> | 2021-09-30 19:34:09 +0300 |
---|---|---|
committer | Gabriel Nagy <gabriel.nagy@puppet.com> | 2021-09-30 19:48:48 +0300 |
commit | 5762b07a5447684ab75b4cf0d2ed989d37b25459 (patch) | |
tree | 0b276ccba799bf6f097186b7963565cad80d106e /REFERENCE.md | |
parent | 8f8c5a5b8f2addd157d353740202539218f2be9c (diff) | |
download | puppet-augeas_core-5762b07a5447684ab75b4cf0d2ed989d37b25459.tar.gz puppet-augeas_core-5762b07a5447684ab75b4cf0d2ed989d37b25459.tar.bz2 |
(MODULES-8183) Fix ToC truncation in REFERENCE.md
Puppet Strings prefers a `@summary` tag with a max of 140 characters to
fill in the Table of Contents summary. Without this, the description
will appear truncated.
Add `@summary` and `@example` tags to the type documentation.
Diffstat (limited to 'REFERENCE.md')
-rw-r--r-- | REFERENCE.md | 199 |
1 files changed, 112 insertions, 87 deletions
diff --git a/REFERENCE.md b/REFERENCE.md index 5304160..8019100 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -1,42 +1,48 @@ # Reference + <!-- DO NOT EDIT: This document was generated by Puppet Strings --> ## Table of Contents -**Resource types** +### Resource types -* [`augeas`](#augeas): Apply a change or an array of changes to the filesystem using the augeas tool. Requires: - [Augeas](http://www.augeas.net) - The ruby-augea +* [`augeas`](#augeas): Apply a change or an array of changes to the filesystem using the augeas tool. ## Resource types -### augeas - -Apply a change or an array of changes to the filesystem -using the augeas tool. +### <a name="augeas"></a>`augeas` Requires: - [Augeas](http://www.augeas.net) - The ruby-augeas bindings -Sample usage with a string: +#### Examples + +##### Sample usage with a string: - augeas{"test1" : - context => "/files/etc/sysconfig/firstboot", - changes => "set RUN_FIRSTBOOT YES", - onlyif => "match other_value size > 0", - } +```puppet -Sample usage with an array and custom lenses: +augeas { "test1": + context => "/files/etc/sysconfig/firstboot", + changes => "set RUN_FIRSTBOOT YES", + onlyif => "match other_value size > 0", +} +``` - augeas{"jboss_conf": - context => "/files", - changes => [ - "set etc/jbossas/jbossas.conf/JBOSS_IP $ipaddress", - "set etc/jbossas/jbossas.conf/JAVA_HOME /usr", - ], - load_path => "$/usr/share/jbossas/lenses", - } +##### Sample usage with an array and custom lenses: + +```puppet + +augeas { "jboss_conf": + context => "/files", + changes => [ + "set etc/jbossas/jbossas.conf/JBOSS_IP $ipaddress", + "set etc/jbossas/jbossas.conf/JAVA_HOME /usr", + ], + load_path => "$/usr/share/jbossas/lenses", +} +``` #### Properties @@ -46,27 +52,88 @@ The following properties are available in the `augeas` type. The expected return code from the augeas command. Should not be set. -Default value: 0 +Default value: `0` #### Parameters The following parameters are available in the `augeas` type. -##### `name` +* [`changes`](#changes) +* [`context`](#context) +* [`force`](#force) +* [`incl`](#incl) +* [`lens`](#lens) +* [`load_path`](#load_path) +* [`name`](#name) +* [`onlyif`](#onlyif) +* [`provider`](#provider) +* [`root`](#root) +* [`show_diff`](#show_diff) +* [`type_check`](#type_check) + +##### <a name="changes"></a>`changes` -namevar +The changes which should be applied to the filesystem. This +can be a command or an array of commands. The following commands are supported: -The name of this task. Used for uniqueness. +* `set <PATH> <VALUE>` --- Sets the value `VALUE` at location `PATH` +* `setm <PATH> <SUB> <VALUE>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `VALUE` +* `rm <PATH>` --- Removes the node at location `PATH` +* `remove <PATH>` --- Synonym for `rm` +* `clear <PATH>` --- Sets the node at `PATH` to `NULL`, creating it if needed +* `clearm <PATH> <SUB>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `NULL` +* `touch <PATH>` --- Creates `PATH` with the value `NULL` if it does not exist +* `ins <LABEL> (before|after) <PATH>` --- Inserts an empty node `LABEL` either before or after `PATH`. +* `insert <LABEL> <WHERE> <PATH>` --- Synonym for `ins` +* `mv <PATH> <OTHER PATH>` --- Moves a node at `PATH` to the new location `OTHER PATH` +* `move <PATH> <OTHER PATH>` --- Synonym for `mv` +* `rename <PATH> <LABEL>` --- Rename a node at `PATH` to a new `LABEL` +* `defvar <NAME> <PATH>` --- Sets Augeas variable `$NAME` to `PATH` +* `defnode <NAME> <PATH> <VALUE>` --- Sets Augeas variable `$NAME` to `PATH`, creating it with `VALUE` if needed + +If the `context` parameter is set, that value is prepended to any relative `PATH`s. -##### `context` +##### <a name="context"></a>`context` Optional context path. This value is prepended to the paths of all changes if the path is relative. If the `incl` parameter is set, defaults to `/files + incl`; otherwise, defaults to the empty string. -Default value: '' +Default value: `''` + +##### <a name="force"></a>`force` + +Optional command to force the augeas type to execute even if it thinks changes +will not be made. This does not override the `onlyif` parameter. + +Default value: ``false`` + +##### <a name="incl"></a>`incl` + +Load only a specific file, such as `/etc/hosts`. This can greatly speed +up the execution the resource. When this parameter is set, you must also +set the `lens` parameter to indicate which lens to use. + +##### <a name="lens"></a>`lens` + +Use a specific lens, such as `Hosts.lns`. When this parameter is set, you +must also set the `incl` parameter to indicate which file to load. +The Augeas documentation includes [a list of available lenses](http://augeas.net/stock_lenses.html). + +##### <a name="load_path"></a>`load_path` + +Optional colon-separated list or array of directories; these directories are searched for schema definitions. +The agent's `$libdir/augeas/lenses` path will always be added to support pluginsync. + +Default value: `''` + +##### <a name="name"></a>`name` + +namevar + +The name of this task. Used for uniqueness. -##### `onlyif` +##### <a name="onlyif"></a>`onlyif` Optional augeas command and comparisons to control the execution of this type. @@ -95,72 +162,22 @@ where: * `INT` is a number * `AN_ARRAY` is in the form `['a string', 'another']` -Default value: '' +Default value: `''` -##### `changes` +##### <a name="provider"></a>`provider` -The changes which should be applied to the filesystem. This -can be a command or an array of commands. The following commands are supported: - -* `set <PATH> <VALUE>` --- Sets the value `VALUE` at location `PATH` -* `setm <PATH> <SUB> <VALUE>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `VALUE` -* `rm <PATH>` --- Removes the node at location `PATH` -* `remove <PATH>` --- Synonym for `rm` -* `clear <PATH>` --- Sets the node at `PATH` to `NULL`, creating it if needed -* `clearm <PATH> <SUB>` --- Sets multiple nodes (matching `SUB` relative to `PATH`) to `NULL` -* `touch <PATH>` --- Creates `PATH` with the value `NULL` if it does not exist -* `ins <LABEL> (before|after) <PATH>` --- Inserts an empty node `LABEL` either before or after `PATH`. -* `insert <LABEL> <WHERE> <PATH>` --- Synonym for `ins` -* `mv <PATH> <OTHER PATH>` --- Moves a node at `PATH` to the new location `OTHER PATH` -* `move <PATH> <OTHER PATH>` --- Synonym for `mv` -* `rename <PATH> <LABEL>` --- Rename a node at `PATH` to a new `LABEL` -* `defvar <NAME> <PATH>` --- Sets Augeas variable `$NAME` to `PATH` -* `defnode <NAME> <PATH> <VALUE>` --- Sets Augeas variable `$NAME` to `PATH`, creating it with `VALUE` if needed - -If the `context` parameter is set, that value is prepended to any relative `PATH`s. +The specific backend to use for this `augeas` resource. You will seldom need to specify this --- Puppet will usually +discover the appropriate provider for your platform. -##### `root` +##### <a name="root"></a>`root` A file system path; all files loaded by Augeas are loaded underneath `root`. -Default value: / - -##### `load_path` - -Optional colon-separated list or array of directories; these directories are searched for schema definitions. The agent's `$libdir/augeas/lenses` path will always be added to support pluginsync. +Default value: `/` -Default value: '' +##### <a name="show_diff"></a>`show_diff` -##### `force` - -Optional command to force the augeas type to execute even if it thinks changes -will not be made. This does not override the `onlyif` parameter. - -Default value: `false` - -##### `type_check` - -Valid values: `true`, `false` - -Whether augeas should perform typechecking. Defaults to false. - -Default value: `false` - -##### `lens` - -Use a specific lens, such as `Hosts.lns`. When this parameter is set, you -must also set the `incl` parameter to indicate which file to load. -The Augeas documentation includes [a list of available lenses](http://augeas.net/stock_lenses.html). - -##### `incl` - -Load only a specific file, such as `/etc/hosts`. This can greatly speed -up the execution the resource. When this parameter is set, you must also -set the `lens` parameter to indicate which lens to use. - -##### `show_diff` - -Valid values: `true`, `false`, yes, no +Valid values: ``true``, ``false``, `yes`, `no` Whether to display differences when the file changes, defaulting to true. This parameter is useful for files that may contain passwords or @@ -168,5 +185,13 @@ other secret data, which might otherwise be included in Puppet reports or other insecure outputs. If the global `show_diff` setting is false, then no diffs will be shown even if this parameter is true. -Default value: `true` +Default value: ``true`` + +##### <a name="type_check"></a>`type_check` + +Valid values: ``true``, ``false`` + +Whether augeas should perform typechecking. Defaults to false. + +Default value: ``false`` |