3rdparty/modules/stdlib/README.md

   1 # stdlib
   2
   3 #### Table of Contents
   4
   5 1. [Overview](#overview)
   6 1. [Module Description](#module-description)
   7 1. [Setup](#setup)
   8 1. [Usage](#usage)
   9 1. [Reference](#reference)
  10     1. [Data Types](#data-types)
  11     1. [Facts](#facts)
  12 1. [Limitations](#limitations)
  13 1. [Development](#development)
  14 1. [Contributors](#contributors)
  15
  16 ## Overview
  17
  18 This module provides a standard library of resources for Puppet modules.
  19
  20 ## Module Description
  21
  22 Puppet modules make heavy use of this standard library. The stdlib module adds the following resources to Puppet:
  23
  24  * Stages
  25  * Facts
  26  * Functions
  27  * Defined types
  28  * Data types
  29  * Providers
  30
  31 > *Note:* As of version 3.7, Puppet Enterprise no longer includes the stdlib module. If you're running Puppet Enterprise, you should install the most recent release of stdlib for compatibility with Puppet modules.
  32
  33 ## Setup
  34
  35 [Install](https://puppet.com/docs/puppet/latest/modules_installing.html) the stdlib module to add the functions, facts, and resources of this standard library to Puppet.
  36
  37 If you are authoring a module that depends on stdlib, be sure to [specify dependencies](https://puppet.com/docs/puppet/latest/modules_installing.html) in your metadata.json.
  38
  39 ## Usage
  40
  41 Most of stdlib's features are automatically loaded by Puppet. To use standardized run stages in Puppet, declare this class in your manifest with `include stdlib`.
  42
  43 When declared, stdlib declares all other classes in the module. The only other class currently included in the module is `stdlib::stages`.
  44
  45 The `stdlib::stages` class declares various run stages for deploying infrastructure, language runtimes, and application layers. The high level stages are (in order):
  46
  47   * setup
  48   * main
  49   * runtime
  50   * setup_infra
  51   * deploy_infra
  52   * setup_app
  53   * deploy_app
  54   * deploy
  55
  56 Sample usage:
  57
  58 ```puppet
  59 node default {
  60   include stdlib
  61   class { java: stage => 'runtime' }
  62 }
  63 ```
  64
  65 ## Reference
  66
  67 For information on the classes and types, see the [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-stdlib/blob/master/REFERENCE.md).
  68
  69 <a id="data-types"></a>
  70 ### Data types
  71
  72 #### `Stdlib::Absolutepath`
  73
  74 A strict absolute path type. Uses a variant of Unixpath and Windowspath types.
  75
  76 Acceptable input examples:
  77
  78 ```shell
  79 /var/log
  80 ```
  81
  82 ```shell
  83 /usr2/username/bin:/usr/local/bin:/usr/bin:.
  84 ```
  85
  86 ```shell
  87 C:\\WINDOWS\\System32
  88 ```
  89
  90 Unacceptable input example:
  91
  92 ```shell
  93 ../relative_path
  94 ```
  95
  96 #### `Stdlib::Ensure::Service`
  97
  98 Matches acceptable ensure values for service resources.
  99
 100 Acceptable input examples:
 101
 102 ```shell
 103 stopped
 104 running
 105 ```
 106
 107 Unacceptable input example:
 108
 109 ```shell
 110 true
 111 false
 112 ```
 113
 114 #### `Stdlib::HTTPSUrl`
 115
 116 Matches HTTPS URLs. It is a case insensitive match.
 117
 118 Acceptable input example:
 119
 120 ```shell
 121 https://hello.com
 122
 123 HTTPS://HELLO.COM
 124 ```
 125
 126 Unacceptable input example:
 127
 128 ```shell
 129 httds://notquiteright.org`
 130 ```
 131
 132 #### `Stdlib::HTTPUrl`
 133
 134 Matches both HTTPS and HTTP URLs. It is a case insensitive match.
 135
 136 Acceptable input example:
 137
 138 ```shell
 139 https://hello.com
 140
 141 http://hello.com
 142
 143 HTTP://HELLO.COM
 144 ```
 145
 146 Unacceptable input example:
 147
 148 ```shell
 149 httds://notquiteright.org
 150 ```
 151
 152 #### `Stdlib::MAC`
 153
 154 Matches MAC addresses defined in [RFC5342](https://tools.ietf.org/html/rfc5342).
 155
 156 #### `Stdlib::Unixpath`
 157
 158 Matches absolute paths on Unix operating systems.
 159
 160 Acceptable input example:
 161
 162 ```shell
 163 /usr2/username/bin:/usr/local/bin:/usr/bin:
 164
 165 /var/tmp
 166 ```
 167
 168 Unacceptable input example:
 169
 170 ```shell
 171 C:/whatever
 172
 173 some/path
 174
 175 ../some/other/path
 176 ```
 177
 178 #### `Stdlib::Filemode`
 179
 180 Matches octal file modes consisting of one to four numbers and symbolic file modes.
 181
 182 Acceptable input examples:
 183
 184 ```shell
 185 0644
 186 ```
 187
 188 ```shell
 189 1777
 190 ```
 191
 192 ```shell
 193 a=Xr,g=w
 194 ```
 195
 196 Unacceptable input examples:
 197
 198 ```shell
 199 x=r,a=wx
 200 ```
 201
 202 ```shell
 203 0999
 204 ```
 205
 206 #### `Stdlib::Windowspath`
 207
 208 Matches paths on Windows operating systems.
 209
 210 Acceptable input example:
 211
 212 ```shell
 213 C:\\WINDOWS\\System32
 214
 215 C:\\
 216
 217 \\\\host\\windows
 218 ```
 219
 220 Valid values: A windows filepath.
 221
 222 #### `Stdlib::Filesource`
 223
 224 Matches paths valid values for the source parameter of the Puppet file type.
 225
 226 Acceptable input example:
 227
 228 ```shell
 229 http://example.com
 230
 231 https://example.com
 232
 233 file:///hello/bla
 234 ```
 235
 236 Valid values: A filepath.
 237
 238 #### `Stdlib::Fqdn`
 239
 240 Matches paths on fully qualified domain name.
 241
 242 Acceptable input example:
 243
 244 ```shell
 245 localhost
 246
 247 example.com
 248
 249 www.example.com
 250 ```
 251 Valid values: Domain name of a server.
 252
 253 #### `Stdlib::Host`
 254
 255 Matches a valid host which could be a valid ipv4, ipv6 or fqdn.
 256
 257 Acceptable input example:
 258
 259 ```shell
 260 localhost
 261
 262 www.example.com
 263
 264 192.0.2.1
 265 ```
 266
 267 Valid values: An IP address or domain name.
 268
 269 #### `Stdlib::Port`
 270
 271 Matches a valid TCP/UDP Port number.
 272
 273 Acceptable input examples:
 274
 275 ```shell
 276 80
 277
 278 443
 279
 280 65000
 281 ```
 282
 283 Valid values: An Integer.
 284
 285 #### `Stdlib::Port::Privileged`
 286
 287 Matches a valid TCP/UDP Privileged port i.e. < 1024.
 288
 289 Acceptable input examples:
 290
 291 ```shell
 292 80
 293
 294 443
 295
 296 1023
 297 ```
 298
 299 Valid values: A number less than 1024.
 300
 301 #### `Stdlib::Port::Unprivileged`
 302
 303 Matches a valid TCP/UDP Privileged port i.e. >= 1024.
 304
 305 Acceptable input examples:
 306
 307 ```shell
 308 1024
 309
 310 1337
 311
 312 65000
 313
 314 ```
 315
 316 Valid values: A number more than or equal to 1024.
 317
 318 #### `Stdlib::Base32`
 319
 320 Matches paths a valid base32 string.
 321
 322 Acceptable input example:
 323
 324 ```shell
 325 ASDASDDASD3453453
 326
 327 asdasddasd3453453=
 328
 329 ASDASDDASD3453453==
 330 ```
 331
 332 Valid values: A base32 string.
 333
 334 #### `Stdlib::Base64`
 335
 336 Matches paths a valid base64 string.
 337
 338 Acceptable input example:
 339
 340 ```shell
 341 asdasdASDSADA342386832/746+=
 342
 343 asdasdASDSADA34238683274/6+
 344
 345 asdasdASDSADA3423868327/46+==
 346 ```
 347
 348 Valid values: A base64 string.
 349
 350 #### `Stdlib::Ipv4`
 351
 352 This type is no longer available. To make use of this functionality, use [Stdlib::IP::Address::V4](https://github.com/puppetlabs/puppetlabs-stdlib#stdlibipaddressv4).
 353
 354 #### `Stdlib::Ipv6`
 355
 356 This type is no longer available. To make use of this functionality, use  [Stdlib::IP::Address::V6](https://github.com/puppetlabs/puppetlabs-stdlib#stdlibipaddressv6).
 357
 358 #### `Stdlib::Ip_address`
 359
 360 This type is no longer available. To make use of this functionality, use  [Stdlib::IP::Address](https://github.com/puppetlabs/puppetlabs-stdlib#stdlibipaddress)
 361
 362 #### `Stdlib::IP::Address`
 363
 364 Matches any IP address, including both IPv4 and IPv6 addresses. It will match them either with or without an address prefix as used in CIDR format IPv4 addresses.
 365
 366 Examples:
 367
 368 ```
 369 '127.0.0.1' =~ Stdlib::IP::Address                                # true
 370 '10.1.240.4/24' =~ Stdlib::IP::Address                            # true
 371 '52.10.10.141' =~ Stdlib::IP::Address                             # true
 372 '192.168.1' =~ Stdlib::IP::Address                                # false
 373 'FEDC:BA98:7654:3210:FEDC:BA98:7654:3210' =~ Stdlib::IP::Address  # true
 374 'FF01:0:0:0:0:0:0:101' =~ Stdlib::IP::Address                     # true
 375 ```
 376
 377 #### `Stdlib::IP::Address::V4`
 378
 379 Match any string consisting of an IPv4 address in the quad-dotted decimal format, with or without a CIDR prefix. It will not match any abbreviated form (for example, 192.168.1) because these are poorly documented and inconsistently supported.
 380
 381 Examples:
 382
 383 ```
 384 '127.0.0.1' =~ Stdlib::IP::Address::V4                                # true
 385 '10.1.240.4/24' =~ Stdlib::IP::Address::V4                            # true
 386 '192.168.1' =~ Stdlib::IP::Address::V4                                # false
 387 'FEDC:BA98:7654:3210:FEDC:BA98:7654:3210' =~ Stdlib::IP::Address::V4  # false
 388 '12AB::CD30:192.168.0.1' =~ Stdlib::IP::Address::V4                   # false
 389 ```
 390
 391 Valid values: An IPv4 address.
 392
 393 #### `Stdlib::IP::Address::V6`
 394
 395 Match any string consistenting of an IPv6 address in any of the documented formats in RFC 2373, with or without an address prefix.
 396
 397 Examples:
 398
 399 ```
 400 '127.0.0.1' =~ Stdlib::IP::Address::V6                                # false
 401 '10.1.240.4/24' =~ Stdlib::IP::Address::V6                            # false
 402 'FEDC:BA98:7654:3210:FEDC:BA98:7654:3210' =~ Stdlib::IP::Address::V6  # true
 403 'FF01:0:0:0:0:0:0:101' =~ Stdlib::IP::Address::V6                     # true
 404 'FF01::101' =~ Stdlib::IP::Address::V6                                # true
 405 ```
 406
 407 Valid values: An IPv6 address.
 408
 409 #### `Stdlib::IP::Address::Nosubnet`
 410
 411 Match the same things as the `Stdlib::IP::Address` alias, except it will not match an address that includes an address prefix (for example, it will match '192.168.0.6' but not '192.168.0.6/24').
 412
 413 Valid values: An IP address with no subnet.
 414
 415 #### `Stdlib::IP::Address::V4::CIDR`
 416
 417 Match an IPv4 address in the CIDR format. It will only match if the address contains an address prefix (for example, it will match '192.168.0.6/24'
 418 but not '192.168.0.6').
 419
 420 Valid values: An IPv4 address with a CIDR provided eg: '192.186.8.101/105'. This will match anything inclusive of '192.186.8.101' to '192.168.8.105'.
 421
 422 #### `Stdlib::IP::Address::V4::Nosubnet`
 423
 424 Match an IPv4 address only if the address does not contain an address prefix (for example, it will match '192.168.0.6' but not '192.168.0.6/24').
 425
 426 Valid values: An IPv4 address with no subnet.
 427
 428 #### `Stdlib::IP::Address::V6::Full`
 429
 430 Match an IPv6 address formatted in the "preferred form" as documented in section 2.2 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt), with or without an address prefix as documented in section 2.3 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt).
 431
 432 #### `Stdlib::IP::Address::V6::Alternate`
 433
 434 Match an IPv6 address formatted in the "alternative form" allowing for representing the last two 16-bit pieces of the address with a quad-dotted decimal, as documented in section 2.2.1 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt). It will match addresses with or without an address prefix as documented in section 2.3 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt).
 435
 436 #### `Stdlib::IP::Address::V6::Compressed`
 437
 438 Match an IPv6 address which may contain `::` used to compress zeros as documented in section 2.2.2 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt). It will match addresses with or without an address prefix as documented in section 2.3 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt).
 439
 440 #### `Stdlib::IP::Address::V6::Nosubnet`
 441
 442 Alias to allow `Stdlib::IP::Address::V6::Nosubnet::Full`, `Stdlib::IP::Address::V6::Nosubnet::Alternate` and `Stdlib::IP::Address::V6::Nosubnet::Compressed`.
 443
 444 #### `Stdlib::IP::Address::V6::Nosubnet::Full`
 445
 446 Match an IPv6 address formatted in the "preferred form" as documented in section 2.2 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt). It will not match addresses with address prefix as documented in section 2.3 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt).
 447
 448 #### `Stdlib::IP::Address::V6::Nosubnet::Alternate`
 449
 450 Match an IPv6 address formatted in the "alternative form" allowing for representing the last two 16-bit pieces of the address with a quad-dotted decimal, as documented in section 2.2.1 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt). It will only match addresses without an address prefix as documented in section 2.3 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt).
 451
 452 #### `Stdlib::IP::Address::V6::Nosubnet::Compressed`
 453
 454 Match an IPv6 address which may contain `::` used to compress zeros as documented in section 2.2.2 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt). It will only match addresses without an address prefix as documented in section 2.3 of [RFC 2373](https://www.ietf.org/rfc/rfc2373.txt).
 455
 456 #### `Stdlib::IP::Address::V6::CIDR`
 457
 458 Match an IPv6 address in the CIDR format. It will only match if the address contains an address prefix (for example, it will match   'FF01:0:0:0:0:0:0:101/32', 'FF01::101/60', '::/0',
 459 but not 'FF01:0:0:0:0:0:0:101', 'FF01::101', '::').
 460
 461 #### `Stdlib::ObjectStore`
 462
 463 Matches cloud object store uris.
 464
 465 Acceptable input example:
 466
 467 ```shell
 468 s3://mybucket/path/to/file
 469
 470 gs://bucket/file
 471
 472 ```
 473 Valid values: cloud object store uris.
 474
 475
 476 #### `Stdlib::ObjectStore::GSUri`
 477
 478 Matches Google Cloud object store uris.
 479
 480 Acceptable input example:
 481
 482 ```shell
 483
 484 gs://bucket/file
 485
 486 gs://bucket/path/to/file
 487
 488 ```
 489 Valid values: Google Cloud object store uris.
 490
 491
 492 #### `Stdlib::ObjectStore::S3Uri`
 493
 494 Matches Amazon Web Services S3 object store uris.
 495
 496 Acceptable input example:
 497
 498 ```shell
 499 s3://bucket/file
 500
 501 s3://bucket/path/to/file
 502
 503 ```
 504 Valid values: Amazon Web Services S3 object store uris.
 505
 506 #### `Stdlib::Syslogfacility`
 507
 508 An enum that defines all syslog facilities defined in [RFC5424](https://tools.ietf.org/html/rfc5424). This is based on work in the [voxpupuli/nrpe](https://github.com/voxpupuli/puppet-nrpe/commit/5700fd4f5bfc3e237195c8833039f9ed1045cd6b) module.
 509
 510 <a id="facts"></a>
 511 ### Facts
 512
 513 #### `package_provider`
 514
 515 Returns the default provider Puppet uses to manage packages on this system.
 516
 517 #### `is_pe`
 518
 519 Returns whether Puppet Enterprise is installed. Does not report anything on platforms newer than PE 3.x.
 520
 521 #### `pe_version`
 522
 523 Returns the version of Puppet Enterprise installed. Does not report anything on platforms newer than PE 3.x.
 524
 525 #### `pe_major_version`
 526
 527 Returns the major version Puppet Enterprise that is installed. Does not report anything on platforms newer than PE 3.x.
 528
 529 #### `pe_minor_version`
 530
 531 Returns the minor version of Puppet Enterprise that is installed. Does not report anything on platforms newer than PE 3.x.
 532
 533 #### `pe_patch_version`
 534
 535 Returns the patch version of Puppet Enterprise that is installed.
 536
 537 #### `puppet_vardir`
 538
 539 Returns the value of the Puppet vardir setting for the node running Puppet or Puppet agent.
 540
 541 #### `puppet_environmentpath`
 542
 543 Returns the value of the Puppet environment path settings for the node running Puppet or Puppet agent.
 544
 545 #### `puppet_server`
 546
 547 Returns the Puppet agent's `server` value, which is the hostname of the Puppet master with which the agent should communicate.
 548
 549 #### `root_home`
 550
 551 Determines the root home directory.
 552
 553 Determines the root home directory, which depends on your operating system. Generally this is '/root'.
 554
 555 #### `service_provider`
 556
 557 Returns the default provider Puppet uses to manage services on this system
 558
 559 ## Limitations
 560
 561 As of Puppet Enterprise 3.7, the stdlib module is no longer included in PE. PE users should install the most recent release of stdlib for compatibility with Puppet modules.
 562
 563 For an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-stdlib/blob/master/metadata.json)
 564
 565 ## Development
 566
 567 Puppet modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad hardware, software, and deployment configurations that Puppet is intended to serve. We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. For more information, see our [module contribution guide](https://github.com/puppetlabs/puppetlabs-stdlib/blob/master/CONTRIBUTING.md).
 568
 569 To report or research a bug with any part of this module, please go to
 570 [http://tickets.puppetlabs.com/browse/MODULES](http://tickets.puppetlabs.com/browse/MODULES).
 571
 572 ## Contributors
 573
 574 The list of contributors can be found at: [https://github.com/puppetlabs/puppetlabs-stdlib/graphs/contributors](https://github.com/puppetlabs/puppetlabs-stdlib/graphs/contributors).