summaryrefslogtreecommitdiff
path: root/README.markdown
diff options
context:
space:
mode:
Diffstat (limited to 'README.markdown')
-rw-r--r--README.markdown205
1 files changed, 176 insertions, 29 deletions
diff --git a/README.markdown b/README.markdown
index a880222..526b573 100644
--- a/README.markdown
+++ b/README.markdown
@@ -76,18 +76,56 @@ The `stdlib::stages` class declares various run stages for deploying infrastruct
### Types
#### `file_line`
- Ensures that a given line, including whitespace at the beginning and end, is contained within a file. If the line is not contained in the given file, Puppet will add the line. Multiple resources can be declared to manage multiple lines in the same file. You can also use `match` to replace existing lines.
- ~~~
- file_line { 'sudo_rule':
- path => '/etc/sudoers',
- line => '%sudo ALL=(ALL) ALL',
- }
- file_line { 'sudo_rule_nopw':
- path => '/etc/sudoers',
- line => '%sudonopw ALL=(ALL) NOPASSWD: ALL',
- }
- ~~~
+Ensures that a given line is contained within a file. The implementation
+matches the full line, including whitespace at the beginning and end. If
+the line is not contained in the given file, Puppet will append the line to
+the end of the file to ensure the desired state. Multiple resources may
+be declared to manage multiple lines in the same file.
+
+Example:
+
+ file_line { 'sudo_rule':
+ path => '/etc/sudoers',
+ line => '%sudo ALL=(ALL) ALL',
+ }
+
+ file_line { 'sudo_rule_nopw':
+ path => '/etc/sudoers',
+ line => '%sudonopw ALL=(ALL) NOPASSWD: ALL',
+ }
+
+In this example, Puppet will ensure both of the specified lines are
+contained in the file /etc/sudoers.
+
+Match Example:
+
+ file_line { 'bashrc_proxy':
+ ensure => present,
+ path => '/etc/bashrc',
+ line => 'export HTTP_PROXY=http://squid.puppetlabs.vm:3128',
+ match => '^export\ HTTP_PROXY\=',
+ }
+
+In this code example match will look for a line beginning with export
+followed by HTTP_PROXY and replace it with the value in line.
+
+Match Example With `ensure => absent`:
+
+ file_line { 'bashrc_proxy':
+ ensure => absent,
+ path => '/etc/bashrc',
+ line => 'export HTTP_PROXY=http://squid.puppetlabs.vm:3128',
+ match => '^export\ HTTP_PROXY\=',
+ match_for_absence => true,
+ }
+
+In this code example match will look for a line beginning with export
+followed by HTTP_PROXY and delete it. If multiple lines match, an
+error will be raised unless the `multiple => true` parameter is set.
+
+**Autorequires:** If Puppet is managing the file that will contain the line
+being managed, the file_line resource will autorequire that file.
##### Parameters
All parameters are optional, unless otherwise noted.
@@ -95,13 +133,13 @@ All parameters are optional, unless otherwise noted.
* `after`: Specifies the line after which Puppet will add any new lines. (Existing lines are added in place.) Valid options: String. Default: Undefined.
* `ensure`: Ensures whether the resource is present. Valid options: 'present', 'absent'. Default: 'present'.
* `line`: **Required.** Sets the line to be added to the file located by the `path` parameter. Valid options: String. Default: Undefined.
-* `match`: Specifies a regular expression to run against existing lines in the file; if a match is found, it is replaced rather than adding a new line. Valid options: String containing a regex. Default: Undefined.
+* `match`: Specifies a regular expression to run against existing lines in the file; if a match is found, it is replaced rather than adding a new line. A regex comparison is performed against the line value and if it does not match an exception will be raised. Valid options: String containing a regex. Default: Undefined.
+* `match_for_absence`: An optional value to determine if match should be applied when `ensure => absent`. If set to true and match is set, the line that matches match will be deleted. If set to false (the default), match is ignored when `ensure => absent` and the value of `line` is used instead. Default: false.
* `multiple`: Determines if `match` and/or `after` can change multiple lines. If set to false, an exception will be raised if more than one line matches. Valid options: 'true', 'false'. Default: Undefined.
* `name`: Sets the name to use as the identity of the resource. This is necessary if you want the resource namevar to differ from the supplied `title` of the resource. Valid options: String. Default: Undefined.
* `path`: **Required.** Defines the file in which Puppet will ensure the line specified by `line`. Must be an absolute path to the file.
* `replace`: Defines whether the resource will overwrite an existing line that matches the `match` parameter. If set to false and a line is found matching the `match` param, the line will not be placed in the file. Valid options: true, false, yes, no. Default: true
-
### Functions
#### `abs`
@@ -132,9 +170,25 @@ Converts a boolean to a number. Converts values:
* 'true', 't', '1', 'y', and 'yes' to 1.
Requires a single boolean or string as an input. *Type*: rvalue.
+#### `bool2str`
+
+Converts a boolean to a string using optionally supplied arguments. The optional
+second and third arguments represent what true and false will be converted to
+respectively. If only one argument is given, it will be converted from a boolean
+to a string containing 'true' or 'false'.
+
+*Examples:*
+~~~
+bool2str(true) => 'true'
+bool2str(true, 'yes', 'no') => 'yes'
+bool2str(false, 't', 'f') => 'f'
+~~~
+
+Requires a single boolean as input. *Type*: rvalue.
+
#### `capitalize`
-Capitalizes the first letter of a string or array of strings. Requires either a single string or an array as an input. *Type*: rvalue.
+Capitalizes the first character of a string or array of strings, and lower-cases the remaining characters of each string. Requires either a single string or an array as an input. *Type*: rvalue.
#### `ceiling`
@@ -224,7 +278,7 @@ Converts the case of a string or of all strings in an array to lowercase. *Type*
#### `empty`
-Returns 'true' if the variable is empty. *Type*: rvalue.
+Returns true if the argument is an array or hash that contains no elements, or an empty string. Returns false when the argument is a numerical value. *Type*: rvalue.
#### `ensure_packages`
@@ -403,6 +457,29 @@ Converts an array into a hash. For example, `hash(['a',1,'b',2,'c',3])` returns
Returns an array an intersection of two. For example, `intersection(["a","b","c"],["b","c","d"])` returns ["b","c"]. *Type*: rvalue.
+#### `is_a`
+
+Boolean check to determine whether a variable is of a given data type. This is equivalent to the `=~` type checks. This function is only available in Puppet 4, or when using the "future" parser.
+
+ ~~~
+ foo = 3
+ $bar = [1,2,3]
+ $baz = 'A string!'
+
+ if $foo.is_a(Integer) {
+ notify { 'foo!': }
+ }
+ if $bar.is_a(Array) {
+ notify { 'bar!': }
+ }
+ if $baz.is_a(String) {
+ notify { 'baz!': }
+ }
+ ~~~
+
+See the documentation for "The Puppet Type System" for more information about types.
+See the `assert_type()` function for flexible ways to assert the type of a value.
+
#### `is_array`
Returns 'true' if the variable passed to this function is an array. *Type*: rvalue.
@@ -478,6 +555,15 @@ Loads the metadata.json of a target module. Can be used to determine module vers
notify { $metadata['author']: }
~~~
+If you do not want to fail the catalog compilation if the metadata file for a module is not present:
+
+ ~~~
+ $metadata = load_module_metadata('mysql', true)
+ if empty($metadata) {
+ notify { "This module does not have a metadata.json file.": }
+ }
+ ~~~
+
*Type*: rvalue.
#### `lstrip`
@@ -521,10 +607,12 @@ Converts a number or a string representation of a number into a true boolean. Ze
#### `parsejson`
Converts a string of JSON into the correct Puppet structure. *Type*: rvalue.
+The optional second argument will be returned if the data was not correct.
#### `parseyaml`
Converts a string of YAML into the correct Puppet structure. *Type*: rvalue.
+The optional second argument will be returned if the data was not correct.
#### `pick`
@@ -536,6 +624,10 @@ From a list of values, returns the first value that is not undefined or an empty
*Type*: rvalue.
+#### `pick_default`
+
+Will return the first value in a list of values. Contrary to the 'pick()' function, the 'pick_default()' does not fail if all arguments are empty. This allows it to use an empty value as default. *Type*: rvalue.
+
#### `prefix`
Applies a prefix to all elements in an array, or to the keys in a hash.
@@ -623,7 +715,7 @@ Returns a new string where runs of the same character that occur in this set are
#### `str2bool`
-Converts a string to a boolean. This attempts to convert strings that contain values such as '1', 't', 'y', and 'yes' to 'true' and strings that contain values such as '0', 'f', 'n', and 'no' to 'false'. *Type*: rvalue.
+Converts certain strings to a boolean. This attempts to convert strings that contain the values '1', 't', 'y', and 'yes' to 'true'. Strings that contain values '0', 'f', 'n', and 'no', or are an an empty string or undefined are converted to 'false'. Any other value will cause an error. *Type*: rvalue.
#### `str2saltedsha512`
@@ -706,12 +798,18 @@ Converts the argument into bytes, for example "4 kB" becomes "4096". Takes a sin
*Type*: rvalue.
-Looks up into a complex structure of arrays and hashes and returns a value
-or the default value if nothing was found.
+Looks up into a complex structure of arrays and hashes to extract a value by
+its path in the structure. The path is a string of hash keys or array indexes
+starting with zero, separated by the path separator character (default "/").
+The function will go down the structure by each path component and will try to
+return the value at the end of the path.
-Key can contain slashes to describe path components. The function will go down
-the structure and try to extract the required value.
+In addition to the required "path" argument the function accepts the default
+argument. It will be returned if the path is not correct, no value was found or
+a any other error have occurred. And the last argument can set the path
+separator character.
+```ruby
$data = {
'a' => {
'b' => [
@@ -722,19 +820,28 @@ $data = {
}
}
+$value = try_get_value($data, 'a/b/2')
+# $value = 'b3'
+
+# with all possible options
$value = try_get_value($data, 'a/b/2', 'not_found', '/')
-=> $value = 'b3'
+# $value = 'b3'
-a -> first hash key
-b -> second hash key
-2 -> array index starting with 0
+# using the default value
+$value = try_get_value($data, 'a/b/c/d', 'not_found')
+# $value = 'not_found'
-not_found -> (optional) will be returned if there is no value or the path did not match. Defaults to nil.
-/ -> (optional) path delimiter. Defaults to '/'.
+# using custom separator
+$value = try_get_value($data, 'a|b', [], '|')
+# $value = ['b1','b2','b3']
+```
-In addition to the required "key" argument, "try_get_value" accepts default
-argument. It will be returned if no value was found or a path component is
-missing. And the fourth argument can set a variable path separator.
+1. **$data** The data structure we are working with.
+2. **'a/b/2'** The path string.
+3. **'not_found'** The default value. It will be returned if nothing is found.
+ (optional, defaults to *undef*)
+4. **'/'** The path separator character.
+ (optional, defaults to *'/'*)
#### `type3x`
@@ -972,6 +1079,39 @@ Validates that the first argument is an integer (or an array of integers). Abort
*Type*: statement.
+#### `validate_ip_address`
+
+Validates that argument is an IP address, regardless of it is an IPv4 or an IPv6
+address. It validates as well IP address with netmask. It must be an String, as
+well.
+
+The following values will pass:
+
+ ~~~
+ validate_ip_address('0.0.0.0')
+ validate_ip_address('8.8.8.8')
+ validate_ip_address('127.0.0.1')
+ validate_ip_address('194.232.104.150')
+ validate_ip_address('3ffe:0505:0002::')
+ validate_ip_address('::1/64')
+ validate_ip_address('fe80::a00:27ff:fe94:44d6/64')
+ validate_ip_address('8.8.8.8/32')
+ ~~~
+
+The following values will fail, causing compilation to abort:
+
+ ~~~
+ validate_ip_address(1)
+ validate_ip_address(true)
+ validate_ip_address(0.0.0.256)
+ validate_ip_address('::1', {})
+ validate_ip_address('0.0.0.0.0')
+ validate_ip_address('3.3.3')
+ validate_ip_address('23.43.9.22/64')
+ validate_ip_address('260.2.32.43')
+ ~~~
+
+
#### `validate_numeric`
Validates that the first argument is a numeric value (or an array of numeric values). Aborts catalog compilation if any of the checks fail.
@@ -1014,6 +1154,13 @@ test, and the second argument should be a stringified regular expression (withou
validate_re($::puppetversion, '^2.7', 'The $puppetversion fact value does not match 2.7')
~~~
+ Note: Compilation will also abort, if the first argument is not a String. Always use
+ quotes to force stringification:
+
+ ~~~
+ validate_re("${::operatingsystemmajrelease}", '^[57]$')
+ ~~~
+
*Type*: statement.
#### `validate_slength`
generated by cgit v1.2.3 (git 2.25.1) at 2025-04-05 20:30:51 +0000