diff options
Diffstat (limited to 'README.markdown')
| -rw-r--r-- | README.markdown | 464 |
1 files changed, 416 insertions, 48 deletions
diff --git a/README.markdown b/README.markdown index 130753d..76c546f 100644 --- a/README.markdown +++ b/README.markdown @@ -1,5 +1,7 @@ # Puppet Labs Standard Library # +[](https://travis-ci.org/puppetlabs/puppetlabs-stdlib) + This module provides a "standard library" of resources for developing Puppet Modules. This modules will include the following additions to Puppet @@ -15,7 +17,7 @@ Puppet Labs writes and distributes will make heavy use of this standard library. To report or research a bug with any part of this module, please go to -[http://projects.puppetlabs.com/projects/stdlib](http://projects.puppetlabs.com/projects/stdlib) +[http://tickets.puppetlabs.com/browse/PUP](http://tickets.puppetlabs.com/browse/PUP) # Versions # @@ -26,9 +28,12 @@ older versions of Puppet Enterprise that Puppet Labs still supports will have bugfix maintenance branches periodically "merged up" into master. The current list of integration branches are: - * v2.1.x (v2.1.1 released in PE 1.2, 1.2.1, 1.2.3, 1.2.4) + * v2.1.x (v2.1.1 released in PE 1) * v2.2.x (Never released as part of PE, only to the Forge) - * v2.3.x (Released in PE 2.5.x) + * v2.3.x (Released in PE 2) + * v3.0.x (Released in PE 3) + * v4.0.x (Maintains compatibility with v3.x despite the major semantic version bump. Compatible with Puppet 2.7.x) + * v5.x (To be released when stdlib can drop support for Puppet 2.7.x. Please see [this discussion](https://github.com/puppetlabs/puppetlabs-stdlib/pull/176#issuecomment-30251414)) * master (mainline development branch) The first Puppet Enterprise version including the stdlib module is Puppet @@ -36,6 +41,12 @@ Enterprise 1.2. # Compatibility # +Puppet Versions | < 2.6 | 2.6 | 2.7 | 3.x | +:---------------|:-----:|:---:|:---:|:----: +**stdlib 2.x** | no | **yes** | **yes** | no +**stdlib 3.x** | no | no | **yes** | **yes** +**stdlib 4.x** | no | no | **yes** | **yes** + The stdlib module does not work with Puppet versions released prior to Puppet 2.6.0. @@ -46,14 +57,40 @@ All stdlib releases in the 2.0 major version support Puppet 2.6 and Puppet 2.7. ## stdlib 3.x ## The 3.0 major release of stdlib drops support for Puppet 2.6. Stdlib 3.x -supports Puppet 2.7. +supports Puppet 2 and Puppet 3. + +## stdlib 4.x ## + +The 4.0 major release of stdlib was intended to drop support for Puppet 2.7, +but the impact on end users was too high. The decision was made to treat +stdlib 4.x as a continuation of stdlib 3.x support. Stdlib 4.x supports Puppet +2.7 and 3. Notably, ruby 1.8.5 is no longer supported though ruby +1.8.7, 1.9.3, and 2.0.0 are fully supported. # Functions # abs --- -Returns the absolute value of a number, for example -34.56 becomes 34.56. Takes -a single integer and float value as an argument. +Returns the absolute value of a number, for example -34.56 becomes +34.56. Takes a single integer and float value as an argument. + + +- *Type*: rvalue + +any2array +--------- +This converts any object to an array containing that object. Empty argument +lists are converted to an empty array. Arrays are left untouched. Hashes are +converted to arrays of alternating keys and values. + + +- *Type*: rvalue + +base64 +-------- +Converts a string to and from base64 encoding. +Requires an action ['encode','decode'] and either a plain or base64 encoded +string - *Type*: rvalue @@ -78,9 +115,9 @@ Requires either a single string or an array as an input. chomp ----- -Removes the record separator from the end of a string or an array of strings, -for example `hello\n` becomes `hello`. Requires a single string or array as an -input. +Removes the record separator from the end of a string or an array of +strings, for example `hello\n` becomes `hello`. +Requires a single string or array as an input. - *Type*: rvalue @@ -96,6 +133,30 @@ Requires a string or array of strings as input. - *Type*: rvalue +concat +------ +Appends the contents of array 2 onto array 1. + +*Example:* + + concat(['1','2','3'],['4','5','6']) + +Would result in: + + ['1','2','3','4','5','6'] + + +- *Type*: rvalue + +count +----- +Takes an array as first argument and an optional second argument. +Count the number of elements in array that matches second argument. +If called with only an array it counts the number of elements that are not nil/undef. + + +- *Type*: rvalue + defined_with_params ------------------- Takes a resource reference and an optional hash of attributes. @@ -116,13 +177,19 @@ to the catalog, and false otherwise. delete ------ -Deletes a selected element from an array. +Deletes all instances of a given element from an array, substring from a +string, or key from a hash. *Examples:* - delete(['a','b','c'], 'b') + delete(['a','b','c','b'], 'b') + Would return: ['a','c'] -Would return: ['a','c'] + delete({'a'=>1,'b'=>2,'c'=>3}, 'b') + Would return: {'a'=>1,'c'=>3} + + delete('abracadabra', 'bra') + Would return: 'acada' - *Type*: rvalue @@ -140,6 +207,57 @@ Would return: ['a','c'] - *Type*: rvalue +delete_values +------------- +Deletes all instances of a given value from a hash. + +*Examples:* + + delete_values({'a'=>'A','b'=>'B','c'=>'C','B'=>'D'}, 'B') + +Would return: {'a'=>'A','c'=>'C','B'=>'D'} + + +- *Type*: rvalue + +delete_undef_values +------------------- +Deletes all instances of the undef value from an array or hash. + +*Examples:* + + $hash = delete_undef_values({a=>'A', b=>'', c=>undef, d => false}) + +Would return: {a => 'A', b => '', d => false} + + $array = delete_undef_values(['A','',undef,false]) + +Would return: ['A','',false] + +- *Type*: rvalue + +difference +---------- +This function returns the difference between two arrays. +The returned array is a copy of the original array, removing any items that +also appear in the second array. + +*Examples:* + + difference(["a","b","c"],["b","c","d"]) + +Would return: ["a"] + +dirname +------- +Returns the `dirname` of a path. + +*Examples:* + + dirname('/path/to/a/file.ext') + +Would return: '/path/to/a' + downcase -------- Converts the case of a string or all strings in an array to lower case. @@ -154,6 +272,13 @@ Returns true if the variable is empty. - *Type*: rvalue +ensure_packages +--------------- +Takes a list of packages and only installs them if they don't already exist. + + +- *Type*: statement + ensure_resource --------------- Takes a resource type, title, and a list of attributes that describe a @@ -165,16 +290,41 @@ resource. This example only creates the resource if it does not already exist: - ensure_resource('user, 'dan', {'ensure' => 'present' }) + ensure_resource('user', 'dan', {'ensure' => 'present' }) If the resource already exists but does not match the specified parameters, this function will attempt to recreate the resource leading to a duplicate resource definition error. +An array of resources can also be passed in and each will be created with +the type and parameters specified if it doesn't already exist. + + ensure_resource('user', ['dan','alex'], {'ensure' => 'present'}) + - *Type*: statement +file_line +--------- +This resource ensures that a given line is contained within a file. You can also use +"match" to replace existing lines. + +*Examples:* + + file_line { 'sudo_rule': + path => '/etc/sudoers', + line => '%sudo ALL=(ALL) ALL', + } + + file_line { 'change_mount': + path => '/etc/fstab', + line => '10.0.0.1:/vol/data /opt/data nfs defaults 0 0', + match => '^172.16.17.2:/vol/old', + } + +- *Type*: resource + flatten ------- This function flattens any deeply nested arrays and returns a single flat array @@ -189,6 +339,14 @@ Would return: ['a','b','c'] - *Type*: rvalue +floor +----- +Returns the largest integer less or equal to the argument. +Takes a single numeric value as an argument. + + +- *Type*: rvalue + fqdn_rotate ----------- Rotates an array a random number of times based on a nodes fqdn. @@ -207,6 +365,27 @@ Example: - *Type*: rvalue +getparam +-------- +Takes a resource reference and name of the parameter and +returns value of resource's parameter. + +*Examples:* + + define example_resource($param) { + } + + example_resource { "example_resource_instance": + param => "param_value" + } + + getparam(Example_resource["example_resource_instance"], "param") + +Would return: param_value + + +- *Type*: rvalue + getvar ------ Lookup a variable in a remote namespace. @@ -241,6 +420,48 @@ Would return: - *Type*: rvalue +has_interface_with +------------------ +Returns boolean based on kind and value: +* macaddress +* netmask +* ipaddress +* network + +*Examples:* + + has_interface_with("macaddress", "x:x:x:x:x:x") + has_interface_with("ipaddress", "127.0.0.1") => true + +etc. + +If no "kind" is given, then the presence of the interface is checked: + + has_interface_with("lo") => true + + +- *Type*: rvalue + +has_ip_address +-------------- +Returns true if the client has the requested IP address on some interface. + +This function iterates through the 'interfaces' fact and checks the +'ipaddress_IFACE' facts, performing a simple string comparison. + + +- *Type*: rvalue + +has_ip_network +-------------- +Returns true if the client has an IP address within the requested network. + +This function iterates through the 'interfaces' fact and checks the +'network_IFACE' facts, performing a simple string comparision. + + +- *Type*: rvalue + has_key ------- Determine if a hash has a certain key value. @@ -261,7 +482,7 @@ Example: hash ---- -This function converts and array into a hash. +This function converts an array into a hash. *Examples:* @@ -272,10 +493,25 @@ Would return: {'a'=>1,'b'=>2,'c'=>3} - *Type*: rvalue +intersection +----------- +This function returns an array an intersection of two. + +*Examples:* + + intersection(["a","b","c"],["b","c","d"]) + +Would return: ["b","c"] + is_array -------- Returns true if the variable passed to this function is an array. +- *Type*: rvalue + +is_bool +-------- +Returns true if the variable passed to this function is a boolean. - *Type*: rvalue @@ -283,13 +519,19 @@ is_domain_name -------------- Returns true if the string passed to this function is a syntactically correct domain name. - - *Type*: rvalue is_float -------- Returns true if the variable passed to this function is a float. +- *Type*: rvalue + +is_function_available +--------------------- +This function accepts a string as an argument, determines whether the +Puppet runtime has access to a function by that name. It returns a +true if the function exists, false if not. - *Type*: rvalue @@ -297,47 +539,41 @@ is_hash ------- Returns true if the variable passed to this function is a hash. - - *Type*: rvalue is_integer ---------- Returns true if the variable returned to this string is an integer. - - *Type*: rvalue is_ip_address ------------- Returns true if the string passed to this function is a valid IP address. - - *Type*: rvalue is_mac_address -------------- Returns true if the string passed to this function is a valid mac address. - - *Type*: rvalue is_numeric ---------- Returns true if the variable passed to this function is a number. - - *Type*: rvalue is_string --------- Returns true if the variable passed to this function is a string. - - *Type*: rvalue join ---- -This function joins an array into a string using a seperator. +This function joins an array into a string using a separator. *Examples:* @@ -345,6 +581,19 @@ This function joins an array into a string using a seperator. Would result in: "a,b,c" +- *Type*: rvalue + +join_keys_to_values +------------------- +This function joins each key of a hash to that key's corresponding value with a +separator. Keys and values are cast to strings. The return value is an array in +which each element is one joined key/value pair. + +*Examples:* + + join_keys_to_values({'a'=>1,'b'=>2}, " is ") + +Would result in: ["a is 1","b is 2"] - *Type*: rvalue @@ -352,7 +601,6 @@ keys ---- Returns the keys of a hash as an array. - - *Type*: rvalue loadyaml @@ -371,6 +619,12 @@ lstrip ------ Strips leading spaces to the left of a string. +- *Type*: rvalue + +max +--- +Returns the highest value of all arguments. +Requires at least one argument. - *Type*: rvalue @@ -388,7 +642,6 @@ Would return: true Would return: false - - *Type*: rvalue merge @@ -397,23 +650,28 @@ Merges two or more hashes together and returns the resulting hash. For example: - $hash1 = {'one' => 1, 'two', => 2} - $hash2 = {'two' => 'dos', 'three', => 'tres'} + $hash1 = {'one' => 1, 'two' => 2} + $hash2 = {'two' => 'dos', 'three' => 'tres'} $merged_hash = merge($hash1, $hash2) # The resulting hash is equivalent to: # $merged_hash = {'one' => 1, 'two' => 'dos', 'three' => 'tres'} When there is a duplicate key, the key in the rightmost hash will "win." +- *Type*: rvalue +min +--- +Returns the lowest value of all arguments. +Requires at least one argument. - *Type*: rvalue num2bool -------- -This function converts a number into a true boolean. Zero becomes false. Numbers -higher then 0 become true. - +This function converts a number or a string representation of a number into a +true boolean. Zero or anything non-numeric becomes false. Numbers higher then 0 +become true. - *Type*: rvalue @@ -422,7 +680,6 @@ parsejson This function accepts JSON as a string and converts into the correct Puppet structure. - - *Type*: rvalue parseyaml @@ -430,6 +687,22 @@ parseyaml This function accepts YAML as a string and converts it into the correct Puppet structure. +- *Type*: rvalue + +pick +---- +This function is similar to a coalesce function in SQL in that it will return +the first value in a list of values that is not undefined or an empty string +(two things in Puppet that will return a boolean false value). Typically, +this function is used to check for a value in the Puppet Dashboard/Enterprise +Console, and failover to a default value like the following: + + $real_jenkins_version = pick($::jenkins_version, '1.449') + +The value of $real_jenkins_version will first look for a top-scope variable +called 'jenkins_version' (note that parameters set in the Puppet Dashboard/ +Enterprise Console are brought into Puppet as top-scope variables), and, +failing that, will use a default value of 1.449. - *Type*: rvalue @@ -437,13 +710,12 @@ prefix ------ This function applies a prefix to all elements in an array. -*Examles:* +*Examples:* prefix(['a','b','c'], 'p') Will return: ['pa','pb','pc'] - - *Type*: rvalue range @@ -459,8 +731,8 @@ Will return: [0,1,2,3,4,5,6,7,8,9] range("00", "09") -Will return: [0,1,2,3,4,5,6,7,8,9] (Zero padded strings are converted to -integers automatically) +Will return: [0,1,2,3,4,5,6,7,8,9] - Zero padded strings are converted to +integers automatically range("a", "c") @@ -470,6 +742,21 @@ Will return: ["a","b","c"] Will return: ["host01", "host02", ..., "host09", "host10"] +- *Type*: rvalue + +reject +------ +This function searches through an array and rejects all elements that match +the provided regular expression. + +*Examples:* + + reject(['aaa','bbb','ccc','aaaddd'], 'aaa') + +Would return: + + ['bbb','ccc'] + - *Type*: rvalue @@ -477,35 +764,30 @@ reverse ------- Reverses the order of a string or array. - - *Type*: rvalue rstrip ------ Strips leading spaces to the right of the string. - - *Type*: rvalue shuffle ------- Randomizes the order of a string or array elements. - - *Type*: rvalue size ---- Returns the number of elements in a string or array. - - *Type*: rvalue sort ---- Sorts strings and arrays lexically. - - *Type*: rvalue squeeze @@ -513,12 +795,11 @@ squeeze Returns a new string where runs of the same character that occur in this set are replaced by a single character. - - *Type*: rvalue str2bool -------- -This converts a string to a boolean. This attempt to convert strings that +This converts a string to a boolean. This attempts to convert strings that contain things like: y, 1, t, true to 'true' and strings that contain things like: 0, f, n, false, no to 'false'. @@ -527,10 +808,10 @@ like: 0, f, n, false, no to 'false'. str2saltedsha512 ---------------- -This converts a string to a salted-SHA512 password hash (which is used for OS X -versions >= 10.7). Given any simple string, you will get a hex version of a -salted-SHA512 password hash that can be inserted into your Puppet manifests as -a valid password attribute. +This converts a string to a salted-SHA512 password hash (which is used for +OS X versions >= 10.7). Given any simple string, you will get a hex version +of a salted-SHA512 password hash that can be inserted into your Puppet +manifests as a valid password attribute. - *Type*: rvalue @@ -570,8 +851,7 @@ To return the date: %L - Millisecond of the second (000..999) %m - Month of the year (01..12) %M - Minute of the hour (00..59) - %n - Newline ( -) + %n - Newline (\n) %N - Fractional seconds digits, default is 9 digits (nanosecond) %3N millisecond (3 digits) %6N microsecond (6 digits) @@ -619,6 +899,19 @@ Would result in: "aaa" - *Type*: rvalue +suffix +------ +This function applies a suffix to all elements in an array. + +*Examples:* + + suffix(['a','b','c'], 'p') + +Will return: ['ap','bp','cp'] + + +- *Type*: rvalue + swapcase -------- This function will swap the existing case of a string. @@ -667,6 +960,17 @@ Returns the type when passed a variable. Type can be one of: - *Type*: rvalue +union +----- +This function returns a union of two arrays. + +*Examples:* + + union(["a","b","c"],["b","c","d"]) + +Would return: ["a","b","c","d"] + + unique ------ This function will remove duplicates from strings and arrays. @@ -705,6 +1009,14 @@ Will return: - *Type*: rvalue +uriescape +--------- +Urlencodes a string or array of strings. +Requires either a single string or an array as an input. + + +- *Type*: rvalue + validate_absolute_path ---------------------- Validate the string represents an absolute path in the filesystem. This function works @@ -751,6 +1063,39 @@ The following values will fail, causing compilation to abort: - *Type*: statement +validate_augeas +--------------- +Perform validation of a string using an Augeas lens +The first argument of this function should be a string to +test, and the second argument should be the name of the Augeas lens to use. +If Augeas fails to parse the string with the lens, the compilation will +abort with a parse error. + +A third argument can be specified, listing paths which should +not be found in the file. The `$file` variable points to the location +of the temporary file being tested in the Augeas tree. + +For example, if you want to make sure your passwd content never contains +a user `foo`, you could write: + + validate_augeas($passwdcontent, 'Passwd.lns', ['$file/foo']) + +Or if you wanted to ensure that no users used the '/bin/barsh' shell, +you could use: + + validate_augeas($passwdcontent, 'Passwd.lns', ['$file/*[shell="/bin/barsh"]'] + +If a fourth argument is specified, this will be the error message raised and +seen by the user. + +A helpful error message can be returned like this: + + validate_augeas($sudoerscontent, 'Sudoers.lns', [], 'Failed to validate sudoers content with Augeas') + + + +- *Type*: statement + validate_bool ------------- Validate that all passed values are either true or false. Abort catalog @@ -773,6 +1118,28 @@ The following values will fail, causing compilation to abort: - *Type*: statement +validate_cmd +------------ +Perform validation of a string with an external command. +The first argument of this function should be a string to +test, and the second argument should be a path to a test command +taking a file as last argument. If the command, launched against +a tempfile containing the passed string, returns a non-null value, +compilation will abort with a parse error. + +If a third argument is specified, this will be the error message raised and +seen by the user. + +A helpful error message can be returned like this: + +Example: + + validate_cmd($sudoerscontent, '/usr/sbin/visudo -c -f', 'Visudo failed to validate sudoers content') + + + +- *Type*: statement + validate_hash ------------- Validate that all passed values are hash data structures. Abort catalog @@ -862,7 +1229,6 @@ The following values will fail, causing compilation to abort: validate_string($undefined) - - *Type*: statement values @@ -927,3 +1293,5 @@ Would result in: - *Type*: rvalue + +*This page autogenerated on 2013-04-11 13:54:25 -0700* |