diff options
| -rw-r--r-- | REFERENCE.md | 199 | ||||
| -rw-r--r-- | lib/puppet/type/augeas.rb | 11 |
2 files changed, 117 insertions, 93 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`` diff --git a/lib/puppet/type/augeas.rb b/lib/puppet/type/augeas.rb index 2303fdc..ef93bce 100644 --- a/lib/puppet/type/augeas.rb +++ b/lib/puppet/type/augeas.rb @@ -23,25 +23,24 @@ Puppet::Type.newtype(:augeas) do feature :execute_changes, 'Actually make the changes' @doc = <<-'EOT' - Apply a change or an array of changes to the filesystem - using the augeas tool. + @summary Apply a change or an array of changes to the filesystem using the augeas tool. Requires: - [Augeas](http://www.augeas.net) - The ruby-augeas bindings - Sample usage with a string: + @example Sample usage with a string: - augeas{"test1" : + augeas { "test1": context => "/files/etc/sysconfig/firstboot", changes => "set RUN_FIRSTBOOT YES", onlyif => "match other_value size > 0", } - Sample usage with an array and custom lenses: + @example Sample usage with an array and custom lenses: - augeas{"jboss_conf": + augeas { "jboss_conf": context => "/files", changes => [ "set etc/jbossas/jbossas.conf/JBOSS_IP $ipaddress", |