### Example: Getting Help for an Action

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/help.md

Illustrates a simple example of how to use the `puppet help` command to get help for an action.

```bash
$ puppet help
```

--------------------------------

### Install Puppet Project Dependencies

Source: https://github.com/openvoxproject/puppet/blob/main/docs/quickstart.md

Installs all project dependencies listed in Puppet's Gemfile into a local '.bundle' directory, ensuring they are isolated from system gems.

```Shell
$ bundle install --path .bundle
```

--------------------------------

### Install Bundler Gem

Source: https://github.com/openvoxproject/puppet/blob/main/docs/quickstart.md

Installs the Bundler gem, a dependency manager for Ruby projects, which is essential for managing Puppet's dependencies.

```Shell
$ gem install bundler
```

--------------------------------

### Puppet Package Resource with Custom Install Options

Source: https://github.com/openvoxproject/puppet/blob/main/references/type.md

Demonstrates how to use the `install_options` attribute to pass additional, provider-specific options during package installation. This example shows installing MySQL with a custom installation directory on Windows.

```Puppet
package { 'mysql':
  ensure          => installed,
  source          => 'N:/packages/mysql-5.5.16-winx64.msi',
  install_options => [ '/S', { 'INSTALLDIR' => 'C:\\mysql-5.5' } ],
}
```

--------------------------------

### Installing Puppet and Checking Version on Windows

Source: https://github.com/openvoxproject/puppet/blob/main/docs/windows.md

This snippet demonstrates the steps to set up Puppet on a Windows environment, including navigating to the project directory, installing Bundler, installing project dependencies, and verifying the Puppet version. It assumes Ruby and Git are already installed.

```Shell
C:\> cd C:\work\puppet
C:\work\puppet> gem install bundler
C:\work\puppet> bundle install --path .bundle
C:\work\puppet> bundle exec puppet --version
4.7.1
```

--------------------------------

### Defining RSpec Examples and Expectations in Ruby

Source: https://github.com/openvoxproject/puppet/blob/main/docs/rspec_tutorial.md

This snippet demonstrates the basic syntax for defining RSpec examples using `specify` or `it` and setting expectations with `expect`. Good examples focus on minimal setup and test one or two specific behaviors, ensuring clarity and ease of debugging.

```Ruby
# This is an example; it sets the test name and defines the test to run
specify "one equals one" do
  # add an expectation that left and right arguments are equal
  expect(1).to eq(1)
end

# Examples can be declared with either 'it' or 'specify'
it "one doesn't equal two" do
  expect(1).to_not eq(2)
end
```

--------------------------------

### Run Single Puppet Test by Line Number

Source: https://github.com/openvoxproject/puppet/blob/main/docs/quickstart.md

Executes a specific unit test or group of tests by providing the filename and line number, for example, 'spec/unit/file_system_spec.rb:42'.

```Shell
$ bundle exec rake spec TEST=spec/unit/file_system_spec.rb:42
```

--------------------------------

### Puppet Script Execution Examples

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/script.md

Examples demonstrating how to run `puppet script` with a log file and how to execute inline Puppet code with a specified module path.

```Puppet
$ puppet script -l /tmp/manifest.log manifest.pp
$ puppet script --modulepath=/root/dev/modules -e 'notice("hello world")'
```

--------------------------------

### Puppet Describe Command Usage Examples

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/describe.md

Practical examples demonstrating common uses of the `puppet describe` command, such as listing all resource types, describing a specific type with its providers, and combining short output with metaparameter details.

```Shell
$ puppet describe --list
$ puppet describe file --providers
$ puppet describe user -s -m
```

--------------------------------

### Example: Get facts from the local system using `puppet facts find`

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/facts.md

Demonstrates how to retrieve all facts from the local system using the `puppet facts find` command.

```Shell
$ puppet facts find
```

--------------------------------

### Puppet Apply Command Usage Examples

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/apply.md

Practical examples demonstrating how to use `puppet apply` for various tasks, including executing inline Puppet code, logging output to a file, specifying a module path, and applying a pre-compiled JSON catalog.

```Shell
$ puppet apply -e 'notify { "hello world": }'
$ puppet apply -l /tmp/manifest.log manifest.pp
$ puppet apply --modulepath=/root/dev/modules -e "include ntpd::server"
$ puppet apply --catalog catalog.json
```

--------------------------------

### Downloading Puppet Catalogs with CLI and Ruby API

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/catalog.md

Examples showing how to download and store a Puppet catalog from the command line, and a Ruby API example demonstrating multiple downloads for different Puppet faces.

```Shell
$ puppet catalog download
```

```Ruby
Puppet::Face[:plugin, '0.0.1'].download
Puppet::Face[:facts, '0.0.1'].upload
Puppet::Face[:catalog, '0.0.1'].download
## ...
```

--------------------------------

### Perform Puppet Resource Lookup

Source: https://github.com/openvoxproject/puppet/blob/main/docs/quickstart.md

Runs the 'puppet resource' command via Bundler to look up information about a specific resource, such as 'host localhost'.

```Shell
$ bundle exec puppet resource host localhost
```

--------------------------------

### Applying Puppet Catalogs with CLI and Ruby API

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/catalog.md

Examples demonstrating how to apply a Puppet catalog using the command line with different termini (`yaml` and `rest`), and a Ruby API example showing how to apply a catalog after downloading it.

```Shell
$ puppet catalog apply --terminus yaml
$ puppet catalog apply --terminus rest
```

```Ruby
## ...    Puppet::Face[:catalog, '0.0.1'].download
## (Termini are singletons; catalog.download has a side effect of    ## setting the catalog terminus to yaml)    report  = Puppet::Face[:catalog, '0.0.1'].apply
## ...
```

--------------------------------

### Print Puppet Configuration Setting Examples

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/config.md

Examples showing how to retrieve the value of a single setting like `rundir` or a filtered list of important directories from the 'server' section using `puppet config print`.

```Shell
$ puppet config print rundir
```

```Shell
$ puppet config print all --section server | grep -E "(path|dir)"
```

--------------------------------

### Install Puppet Modules

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/module.md

These commands demonstrate various ways to install Puppet modules from the Forge or local archives. Options include specifying target environments, installing specific versions, directing installation to custom directories, and managing dependency resolution.

```Shell
puppet module install puppetlabs-vcsrepo
```

```Shell
puppet module install puppetlabs-vcsrepo --environment development
```

```Shell
puppet module install puppetlabs-vcsrepo -v 0.0.4
```

```Shell
puppet module install puppetlabs-vcsrepo --target-dir=/opt/puppetlabs/puppet/modules
```

```Shell
puppet module install puppetlabs-vcsrepo --target-dir=/opt/puppetlabs/puppet/modules --modulepath /etc/puppetlabs/code/modules
```

```Shell
puppet module install puppetlabs-vcsrepo-0.0.4.tar.gz
```

```Shell
puppet module install puppetlabs-vcsrepo-0.0.4.tar.gz --ignore-dependencies
```

--------------------------------

### Example Puppet Device Command Execution

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/device.md

Demonstrates how to run the `puppet device` command to target a specific remote host with verbose output.

```Shell
$ puppet device --target remotehost --verbose
```

--------------------------------

### Puppet Help Command Synopsis

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/help.md

Provides the general syntax for using the `puppet help` command to get assistance on specific actions.

```bash
puppet help *action*
```

--------------------------------

### Example Puppet Agent Command Execution

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/agent.md

Demonstrates how to run the `puppet agent` command, specifying a custom Puppet server.

```Shell
$ puppet agent --server puppet.domain.com
```

--------------------------------

### Example Node Data Retrieval

Source: https://github.com/openvoxproject/puppet/blob/main/api/docs/http_node.md

Illustrates a sample HTTP GET request to the `/puppet/v3/node` endpoint with parameters and the corresponding JSON response body, showing typical node information.

```APIDOC
> GET /puppet/v3/node/mycertname?environment=production&transaction_uuid=aff261a2-1a34-4647-8c20-ff662ec11c4c&configured_environment=production HTTP/1.1
> Accept: application/json

< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 4630

{
  "name":"thinky.corp.puppetlabs.net",
  "parameters":{
    "architecture":"amd64",
    "kernel":"Linux",
    "blockdevices":"sda,sr0",
    "clientversion":"3.3.1",
    "clientnoop":"false",
    "environment":"production",
    ...
  },
  "environment":"production"
}
```

--------------------------------

### Puppet Package Provider: windows

Source: https://github.com/openvoxproject/puppet/blob/main/references/type.md

Provides Windows package management, supporting MSI or self-extracting executable installers. It requires a `source` attribute for installation and supports `install_options` and `uninstall_options` for passing command-line flags to the installer, handling silent install/uninstall arguments and automatic quoting of options with spaces.

```APIDOC
Provider: windows
Description: Windows package management. This provider supports either MSI or self-extracting executable installers.
Requirements:
  - Requires a `source` attribute when installing the package. Accepts paths to local files, mapped drives, or UNC paths.
Attributes:
  install_options: Allows command-line flags to be passed to the installer. Specified as an array where each element is either a string or a hash. If the executable requires special arguments for silent install, specify them here. Puppet automatically quotes any option that contains spaces.
  uninstall_options: Allows command-line flags to be passed to the installer. Specified as an array where each element is either a string or a hash. If the executable requires special arguments for silent uninstall, specify them here. Puppet automatically quotes any option that contains spaces.
Default for:
  - os.name == windows
Supported features:
  - install_options
  - installable
  - uninstall_options
  - uninstallable
  - versionable
```

--------------------------------

### Configure Package Installation Options with Puppet

Source: https://github.com/openvoxproject/puppet/blob/main/references/types/package.md

The `install_options` attribute allows passing an array of additional, package-specific options during installation. These options can be strings or hashes, are automatically quoted, and are provider-specific. For Windows packages, file paths must use backslashes, which require escaping in double-quoted strings.

```Puppet
package { 'mysql':
  ensure          => installed,
  source          => 'N:/packages/mysql-5.5.16-winx64.msi',
  install_options => [ '/S', { 'INSTALLDIR' => 'C:\\mysql-5.5' } ],
}
```

--------------------------------

### Run Single Puppet Unit Test File

Source: https://github.com/openvoxproject/puppet/blob/main/docs/quickstart.md

Executes unit tests contained within a specific file, such as 'spec/unit/file_system_spec.rb', allowing for faster and more focused testing.

```Shell
$ bundle exec rake spec TEST=spec/unit/file_system_spec.rb
```

--------------------------------

### Puppet Service Attribute: start

Source: https://github.com/openvoxproject/puppet/blob/main/references/type.md

Allows manual specification of a command to start the service. Most service subsystems support a `start` command, making manual specification often unnecessary.

```APIDOC
Service Attribute: start
  Description: Specify a *start* command manually.
  Most service subsystems support a `start` command, so this will not need to be specified.
```

--------------------------------

### Puppet Service Attribute: start

Source: https://github.com/openvoxproject/puppet/blob/main/references/types/service.md

Manually specifies the command to start the service. Most service subsystems support a `start` command, so this is rarely needed.

```APIDOC
service attribute: start
  description: Specify a *start* command manually. Most service subsystems support a `start` command, so this will not need to be specified.
```

--------------------------------

### Set Puppet Configuration Setting Examples

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/config.md

Examples illustrating how to update a Puppet configuration setting, such as setting the `rundir` globally or setting the `vardir` specifically for the agent section.

```Shell
$ puppet config set rundir /var/run/puppetlabs
```

```Shell
$ puppet config set vardir /opt/puppetlabs/puppet/cache --section agent
```

--------------------------------

### Example Array for tree_each Iteration

Source: https://github.com/openvoxproject/puppet/blob/main/references/function.md

Provides a simple array example used to illustrate the difference in iteration order (`depth_first` vs. `breadth_first`) and the effect of `include_containers` and `include_root` options.

```Puppet
[1, [2, 3], 4]
```

--------------------------------

### Grouping RSpec Examples with `describe` in Ruby

Source: https://github.com/openvoxproject/puppet/blob/main/docs/rspec_tutorial.md

This snippet illustrates how to group similar RSpec examples using the `describe` block. Example groups help organize tests logically and improve the readability of test output, as demonstrated by the `documentation` formatter when running RSpec.

```Ruby
describe "the number one" do

  it "is larger than zero" do
    expect(1).to be > 0
  end

  it "is an odd number" do
    expect(1).to be_odd # calls 1.odd?
  end

  it "is not nil" do
    expect(1).to be
  end
end
```

--------------------------------

### Puppet Package Provider: windows

Source: https://github.com/openvoxproject/puppet/blob/main/references/types/package.md

Documentation for Windows package management provider. It supports MSI or self-extracting executable installers, requires a `source` attribute, and allows `install_options` and `uninstall_options` for passing command-line flags to installers. Puppet automatically quotes options with spaces.

```APIDOC
Provider: windows
Description: Windows package management. This provider supports either MSI or self-extracting executable installers.
Requires: source attribute when installing the package (local files, mapped drives, or UNC paths).
Confined to: os.name == windows
Default for: ["os.name", "windows"]
Supported features: install_options, installable, uninstall_options, uninstallable, versionable
  install_options: Allows command-line flags to be passed to the installer. These options should be specified as an array where each element is either a string or a hash.
  uninstall_options: Allows command-line flags to be passed to the uninstaller. These options should be specified as an array where each element is either a string or a hash.
```

--------------------------------

### Validate Puppet Manifests Command Examples

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/parser.md

Provides examples for using the `puppet parser validate` command to check the syntax of Puppet manifests. Examples include validating the default site manifest, specific manifest files, and content piped from standard input.

```Shell
$ puppet parser validate
```

```Shell
$ puppet parser validate init.pp vhost.pp
```

```Shell
$ cat init.pp | puppet parser validate
```

--------------------------------

### Apply Simple Puppet Test Manifest

Source: https://github.com/openvoxproject/puppet/blob/main/docs/quickstart.md

Applies a simple inline Puppet manifest using 'puppet apply -e', demonstrating basic Puppet execution with a 'notify' resource.

```Shell
$ bundle exec puppet apply -e 'notify { "hello world": }'
```

--------------------------------

### Puppet Function: `get` Data Navigation Examples

Source: https://github.com/openvoxproject/puppet/blob/main/references/function.md

Examples demonstrating the usage of the Puppet `get` function to navigate data structures using dot notation. These examples cover accessing nested values, providing default values, quoting keys with periods, and implementing error handling with a lambda block.

```puppet
#get($facts, 'os.family')
$facts.get('os.family')
```

```puppet
get([1,2,[{'name' =>'waldo'}]], '2.0.name')
```

```puppet
get([1,2,[{'name' =>'waldo'}]], '2.1.name', 'not waldo')
```

```puppet
$x = [1, 2, { 'readme.md' => "This is a readme."}]
$x.get('2."readme.md"')
```

```puppet
$x = [1, 2, { '10' => "ten"}]
$x.get('2."0"')
```

```puppet
$x = 'blue'
$x.get('0.color', 'green') |$error| { undef } # result is undef

$y = ['blue']
$y.get('color', 'green') |$error| { undef } # result is undef
```

```puppet
$x = [1, 2, ['blue']]
$x.get('2.color') |$error| {
  notice("Walked path is ${error.details['walked_path']}")
}
```

--------------------------------

### NIM Package Provider for Puppet (AIX)

Source: https://github.com/openvoxproject/puppet/blob/main/references/type.md

Installation from an AIX NIM LPP source. The `source` parameter is required for this provider, and should specify the name of a NIM `lpp_source` resource that is visible to the puppet agent machine. This provider supports the management of both BFF/installp and RPM packages. Note that package downgrades are *not* supported; if your resource specifies a specific version number and there is already a newer version of the package installed on the machine, the resource will fail with an error message.

```APIDOC
NIM Package Provider:
  Description: Installation from an AIX NIM LPP source.
  Required Binaries: /usr/bin/lslpp, /usr/sbin/nimclient, rpm
  Supported Features: installable, uninstallable, upgradeable, versionable
  Notes:
    - The `source` parameter is required, specifying a visible NIM `lpp_source`.
    - Supports management of both BFF/installp and RPM packages.
    - Package downgrades are NOT supported; will fail if a newer version is installed.
```

--------------------------------

### Example: Retrieve Ignored CSRs via HTTP GET

Source: https://github.com/openvoxproject/puppet/blob/main/api/docs/http_certificate_request.md

An example HTTP GET request to retrieve all ignored Certificate Signing Requests (CSRs) for the 'production' environment from the Puppet CA, along with the expected HTTP 200 OK response containing multiple CSRs in PEM format, separated by `\n---\n`.

```HTTP
GET /puppet-ca/v1/certificate_requests/ignored?environment=production
Accept: s

HTTP/1.1 200 OK
Content-Type: text/plain

-----BEGIN CERTIFICATE REQUEST-----
MIIBnzCCAQwCAQAwYzELMAkGA1UEBhMCVUsxDzANBgNVBAgTBkxvbmRvbjEPMA0G
AUEBxMGTG9uZG9uMSEwHwYDVQQKExhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQx
DzANBgNVBAMTBmFnZW5jeTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAxSCr
FKUKjVGFPuQ0iGM9mZKw94sOIgGohqrHH743kPvjsId3d38Qk+H+1DbVf42bQY0W
kAVcwNDqmBnx0lOtQ0oeGnbbwlJFjhqXr8jFEljPrc9S2/IIILDf/FeYWw9lRiOV
LoU6ZfCIBfq6v4D4KX3utRbOoELNyBeT6VA1ufMCAwEAAaAAMAkGBSsOAwIPBQAD
gYEAno7O1jkR56TNMe1Cw/eyQUIaniG22+0kmoftjlcMYZ/IKCOz+HRgnDtBPf8j
O5nt0PQN8YClW7Xx2U8ZTvBXn/UEKMtCBkbF+SULiayxPgfyKy/axinfutEChnHS
ZtUMUBLlh+gGFqOuH69979SJ2QmQC6FNomTkYI7FOHD/TG0=
-----END CERTIFICATE REQUEST-----

---
-----BEGIN CERTIFICATE REQUEST-----
MIIBnjCCAQsCAQAwYjELMAkGA1UEBhMCVUsxDzANBgNVBAgTBkxvbmRvbjEPMA0G
AUEBxMGTG9uZG9uMSEwHwYDVQQKExhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQx
DjAMBgNVBAMTBWFnZW50MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC1tucK
enT1CkDPgsCU/0e2cbzRsiKF8yHH7+ntF6Q3d9ZCaZWJ00mj0+YmiYrnum+KAikE
45Iaf9vaUV3CPsDVrUPOI8kYehiv868ZhP3nxblE6iuNBK+Fdv9GN/vKQrmL5iRE
bIrOM3/lxpS7SpidGdA6EIVlS3604bwLY4xHNQIDAQABoAAwCQYFKw4DAg8FAAOB
gQAXH0YFuidPqB6P2MyPEEGZ3rzozINBx/oXvGptXI60Zy5mgH6iAkrZfi57pEzP
jFoO2JRaFxTJC1FVpc4zR1K6sq4h3fIMwqppJRX+5wJNKyhU61eY2gR2O/rAJzw4
wcUKf9JhoE7/p1cUulIIIq7t/ibCvf0LYSFwGqTwGqN2TQ==
-----END CERTIFICATE REQUEST-----
```

--------------------------------

### Example: Retrieving a File via HTTP GET

Source: https://github.com/openvoxproject/puppet/blob/main/api/docs/http_file_bucket_file.md

Illustrates an HTTP GET request to retrieve the contents of a file from the Puppet file bucket, showing the successful 200 OK response with the file content.

```HTTP
> GET /puppet/v3/file_bucket_file/md5/4949e56d376cc80ce5387e8e89a75396//home/user/myfile.txt?environment=production HTTP/1.1
> Accept: application/octet-stream


< HTTP/1.1 200 OK
< Content-Length: 24

< This is the file content
```

--------------------------------

### Retrieve Puppet Node Object Examples

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/node.md

Examples demonstrating how to retrieve node objects using the `puppet node find` command with different terminuses and run modes. These examples show how to get an 'empty' node, a node using the Puppet Server's configured ENC, and a node directly from the Puppet Server.

```Shell
$ puppet node find somenode.puppetlabs.lan --terminus plain --render-as yaml
```

```Shell
$ puppet node find somenode.puppetlabs.lan --terminus exec --run_mode server --render-as yaml
```

```Shell
$ puppet node find somenode.puppetlabs.lan --terminus rest --render-as yaml
```

--------------------------------

### Puppet exec Provider: windows and Usage Examples

Source: https://github.com/openvoxproject/puppet/blob/main/references/type.md

Documentation for the `windows` provider of the `exec` type, used for executing external binaries on Windows. It directly calls commands without shell interpolation. To use shell built-ins, commands must explicitly invoke the shell. Windows uses `PATHEXT` to locate executables if no extension is specified. Includes examples for basic command execution and running PowerShell scripts.

```APIDOC
exec provider: windows
  Description: Executes external binaries on Windows systems. Directly calls command with arguments without shell interpolation.
  Behavior:
    - To use shell built-ins, command must explicitly invoke the shell.
  Notes:
    - If no extension is specified, PATHEXT environment variable is used to locate the executable.
    - Default for os.name == windows.
```

```Puppet
exec {'echo foo':
  command => 'cmd.exe /c echo "foo"',
}
```

```Puppet
exec { 'test':
  path    => 'C:/Windows/System32/WindowsPowerShell/v1.0',
  command => 'powershell -executionpolicy remotesigned -file C:/test.ps1',
}
```

--------------------------------

### Get Puppet Environments API Reference

Source: https://github.com/openvoxproject/puppet/blob/main/api/docs/http_environments.md

This section details the `GET` method for the `/puppet/v3/environments` endpoint, including supported response formats, parameters, and an example request and response structure. It provides information about the `modulepath`, `manifest`, `environment_timeout`, and `config_version` for each environment.

```APIDOC
Endpoint: GET /puppet/v3/environments
Description: Get the list of known environments.
Supported Response Formats: application/json
Parameters: None

Example Request:
GET /puppet/v3/environments

Example Response (HTTP 200 OK):
Content-Type: application/json

{
  "search_paths": ["/etc/puppetlabs/code/environments"],
  "environments": {
    "production": {
      "settings": {
        "modulepath": ["/etc/puppetlabs/code/environments/production/modules", "/etc/puppetlabs/code/environments/development/modules"],
        "manifest": ["/etc/puppetlabs/code/environments/production/manifests"],
        "environment_timeout": 180,
        "config_version": "/version/of/config"
      }
    }
  }
}

Note: The 'environment_timeout' attribute could also be the string "unlimited".

Schema Reference: ../schemas/environments.json
```

--------------------------------

### Example: Certificate Request Not Found Error

Source: https://github.com/openvoxproject/puppet/blob/main/api/docs/http_certificate_request.md

This example illustrates an HTTP GET request for a Certificate Signing Request (CSR) that does not exist. The server responds with an HTTP 404 Not Found status and a descriptive error message, indicating that the specified CSR could not be located.

```HTTP
GET /puppet-ca/v1/certificate_request/does_not_exist?environment=env

HTTP/1.1 404 Not Found
Content-Type: text/plain

Not Found: Could not find certificate_request does_not_exist
```

--------------------------------

### Run Puppet Spec Tests via Bundler

Source: https://github.com/openvoxproject/puppet/blob/main/docs/quickstart.md

Executes the Puppet spec tests using the 'rake spec' task within the context of the project's bundled dependencies, ensuring the correct environment.

```Shell
$ bundle exec rake spec
```

--------------------------------

### Puppet Example: Defining and Using a Run Stage

Source: https://github.com/openvoxproject/puppet/blob/main/references/type.md

Demonstrates how to declare a new run stage ('pre') and order it before the 'main' stage, then assign a class ('apt-updates') to this new stage using the `stage` metaparameter.

```Puppet
stage { 'pre':
  before => Stage['main'],
}

class { 'apt-updates':
  stage => 'pre',
}
```

--------------------------------

### Example: Successful Certificate Request Retrieval

Source: https://github.com/openvoxproject/puppet/blob/main/api/docs/http_certificate_request.md

This example demonstrates a successful HTTP GET request to retrieve a Certificate Signing Request (CSR) for a node named 'agency'. The response shows an HTTP 200 OK status, `text/plain` content type, and the full PEM-encoded CSR.

```HTTP
GET /puppet-ca/v1/certificate_request/agency?environment=env

HTTP/1.1 200 OK
Content-Type: text/plain

-----BEGIN CERTIFICATE REQUEST-----
MIIBnzCCAQwCAQAwYzELMAkGA1UEBhMCVUsxDzANBgNVBAgTBkxvbmRvbjEPMA0G
B1UEBxMGTG9uZG9uMSEwHwYDVQQKExhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQx
DzANBgNVBAMTBmFnZW5jeTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAxSCr
FKUKjVGFPuQ0iGM9mZKw94sOIgGohqrHH743kPvjsId3d38Qk+H+1DbVf42bQY0W
kAVcwNDqmBnx0lOtQ0oeGnbbwlJFjhqXr8jFEljPrc9S2/IIILDf/FeYWw9lRiOV
LoU6ZfCIBfq6v4D4KX3utRbOoELNyBeT6VA1ufMCAwEAAaAAMAkGBSsOAwIPBQAD
gYEAno7O1jkR56TNMe1Cw/eyQUIaniG22+0kmoftjlcMYZ/IKCOz+HRgnDtBPf8j
O5nt0PQN8YClW7Xx2U8ZTvBXn/UEKMtCBkbF+SULiayxPgfyKy/axinfutEChnHS
ZtUMUBLlh+gGFqOuH69979SJ2QmQC6FNomTkYI7FOHD/TG0=
-----END CERTIFICATE REQUEST-----
```

--------------------------------

### Download Puppet Plugins via Command Line

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/plugin.md

Example command to retrieve plugins from the configured Puppet master using the `puppet plugin download` command-line interface.

```Shell
$ puppet plugin download
```

--------------------------------

### Example: Missing Node Name in Request

Source: https://github.com/openvoxproject/puppet/blob/main/api/docs/http_certificate_request.md

This example demonstrates an HTTP GET request to the `certificate_request` endpoint without specifying a `:nodename` in the URL path. The server responds with an HTTP 400 Bad Request status and an error message indicating that a request key (node name) was not provided.

```HTTP
GET /puppet-ca/v1/certificate_request?environment=env

HTTP/1.1 400 Bad Request
Content-Type: text/plain

No request key specified in /puppet-ca/v1/certificate_request
```

--------------------------------

### Example: File Metadata for a Directory

Source: https://github.com/openvoxproject/puppet/blob/main/api/docs/http_file_metadata.md

Demonstrates a `GET` request and the expected JSON response when retrieving metadata for a directory using the `file_metadata` endpoint.

```HTTP
GET /puppet/v3/file_metadata/modules/example/subdirectory?environment=env

HTTP/1.1 200 OK
Content-Type: application/json

{
    "checksum": {
        "type": "ctime",
        "value": "{ctime}2013-10-01 13:16:10 -0700"
    },
    "destination": null,
    "group": 20,
    "links": "manage",
    "mode": 493,
    "owner": 501,
    "path": "/etc/puppetlabs/code/modules/example/files/subdirectory",
    "relative_path": null,
    "type": "directory"
}
```

--------------------------------

### Run Puppet Tests in Parallel

Source: https://github.com/openvoxproject/puppet/blob/main/docs/quickstart.md

Executes all unit tests in parallel using a specified number of processes, indicated by 'process_count', to speed up test execution.

```Shell
$ bundle exec rake parallel:spec[process_count]
```

--------------------------------

### Puppet Help Global Options

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/help.md

Describes the general command-line options applicable to `puppet help`, including output rendering format, verbosity, and debug logging. It also notes that any valid configuration setting can be used as a long argument.

```APIDOC
--render-as FORMAT
    The format in which to render output. The most common formats are json, s (string), yaml, and console, but other options such as dot are sometimes available.

--verbose
    Whether to log verbosely.

--debug
    Whether to log debug information.
```

--------------------------------

### Example: File Metadata for a Regular File

Source: https://github.com/openvoxproject/puppet/blob/main/api/docs/http_file_metadata.md

Demonstrates a `GET` request and the expected JSON response when retrieving metadata for a regular file using the `file_metadata` endpoint.

```HTTP
GET /puppet/v3/file_metadata/modules/example/just_a_file.txt?environment=env

HTTP/1.1 200 OK
Content-Type: application/json

{
    "checksum": {
        "type": "md5",
        "value": "{md5}d0a10f45491acc8743bc5a82b228f89e"
    },
    "destination": null,
    "group": 20,
    "links": "manage",
    "mode": 420,
    "owner": 501,
    "path": "/etc/puppetlabs/code/modules/example/files/just_a_file.txt",
    "relative_path": null,
    "type": "file"
}
```

--------------------------------

### Example: File Metadata for a Symbolic Link (Ignoring Permissions)

Source: https://github.com/openvoxproject/puppet/blob/main/api/docs/http_file_metadata.md

Demonstrates a `GET` request and the expected JSON response when retrieving metadata for a symbolic link, specifically showing the effect of `source_permissions=ignore`.

```HTTP
GET /puppet/v3/file_metadata/modules/example/link_to_file.txt?environment=env&source_permissions=ignore

HTTP/1.1 200 OK
Content-Type: application/json

{
    "checksum": {
        "type": "md5",
        "value": "{md5}d0a10f45491acc8743bc5a82b228f89e"
    },
    "destination": "/etc/puppetlabs/code/modules/example/files/just_a_file.txt",
    "group": 20,
    "links": "manage",
    "mode": 420,
    "owner": 501,
    "path": "/etc/puppetlabs/code/modules/example/files/link_to_file.txt",
    "relative_path": null,
    "type": "link"
}
```

--------------------------------

### Puppet Apply Command Options Reference

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/apply.md

A comprehensive reference for all command-line options supported by `puppet apply`, detailing their purpose, accepted values, and how they influence the execution of Puppet manifests.

```APIDOC
- --debug: Enable full debugging.
- --detailed-exitcodes: Provide extra information about the run via exit codes.
  - 0: The run succeeded with no changes or failures; the system was already in the desired state.
  - 1: The run failed.
  - 2: The run succeeded, and some resources were changed.
  - 4: The run succeeded, and some resources failed.
  - 6: The run succeeded, and included both changes and failures.
- --help: Print this help message.
- --loadclasses: Load any stored classes. 'puppet agent' caches configured classes (usually at /etc/puppetlabs/puppet/classes.txt), and setting this option causes all of those classes to be set in your puppet manifest.
- --logdest: Where to send log messages. Choose between 'syslog' (the POSIX syslog service), 'eventlog' (the Windows Event Log), 'console', or the path to a log file. Defaults to 'console'. Multiple destinations can be set using a comma separated list (eg: /path/file1,console,/path/file2)
  - A path ending with '.json' will receive structured output in JSON format. The log file will not have an ending ']' automatically written to it due to the appending nature of logging. It must be appended manually to make the content valid JSON.
  - A path ending with '.jsonl' will receive structured output in JSON Lines format.
- --noop: Use 'noop' mode where Puppet runs in a no-op or dry-run mode. This is useful for seeing what changes Puppet will make without actually executing the changes.
- --execute: Execute a specific piece of Puppet code.
- --test: Enable the most common options used for testing. These are 'verbose', 'detailed-exitcodes' and 'show_diff'.
- --verbose: Print extra information.
- --catalog: Apply a JSON catalog (such as one generated with 'puppet master --compile'). You can either specify a JSON file or pipe in JSON from standard input.
- --write-catalog-summary: After compiling the catalog saves the resource list and classes list to the node in the state directory named classes.txt and resources.txt
```

--------------------------------

### Example: Retrieve File Content (Success)

Source: https://github.com/openvoxproject/puppet/blob/main/api/docs/http_file_content.md

Demonstrates a successful request to the `file_content` endpoint, showing the GET request with `Accept` header and the `HTTP/1.1 200 OK` response with the file content.

```APIDOC
GET /puppet/v3/file_content/modules/example/my_file?environment=env
Accept: application/octet-stream

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: 16

this is my file
```

--------------------------------

### Pkg Package Provider for Puppet (OpenSolaris IPS)

Source: https://github.com/openvoxproject/puppet/blob/main/references/type.md

OpenSolaris image packaging system. See pkg(5) for more information. This provider supports the `install_options` attribute, which allows command-line flags to be passed to pkg. These options should be specified as an array where each element is either a string or a hash.

```APIDOC
Pkg Package Provider:
  Description: OpenSolaris image packaging system.
  Required Binaries: /usr/bin/pkg
  Default for: kernelrelease == 5.11, 5.12 and os.family == solaris
  Supported Features: holdable, install_options, installable, uninstallable, upgradeable, versionable
  Notes:
    - See pkg(5) for more information.
    - Supports `install_options` attribute.
    - Options should be an array where each element is a string or a hash.
```

--------------------------------

### RSpec: Setting Up and Tearing Down Tests with `before` and `after`

Source: https://github.com/openvoxproject/puppet/blob/main/docs/rspec_tutorial.md

Demonstrates how to use `before` and `after` blocks in RSpec to perform setup and teardown actions for tests. This example specifically shows how to temporarily disable and re-enable Ruby warnings around a test that reassigns a constant.

```Ruby
describe "something that could warn" do
  before :each do
    # Disable warnings for this test
    $VERBOSE = nil
  end

  after :each do
    # Enable warnings afterwards
    $VERBOSE = true
  end

  it "doesn't generate a warning" do
    MY_CONSTANT = 1
    # reassigning a constant normally prints out 'warning: already initialized constant FOO'
    MY_CONSTANT = 2
  end
end
```

--------------------------------

### Example: Handling Incorrect File Path during Retrieval

Source: https://github.com/openvoxproject/puppet/blob/main/api/docs/http_file_bucket_file.md

Shows an HTTP GET request attempting to retrieve a file with an incorrect `original_path`, resulting in a 404 Not Found error response from the Puppet file bucket.

```HTTP
> GET /puppet/v3/file_bucket_file/md5/4949e56d376cc80ce5387e8e89a75396//home/user/wrong_name?environment=production HTTP/1.1
> Accept: application/octet-stream


< HTTP/1.1 404 Not Found
<
< Not Found: Could not find file_bucket_file md5/4949e56d376cc80ce5387e8e89a75396/home/user/wrong_name
```

--------------------------------

### Puppet Help Subcommand Action Details

Source: https://github.com/openvoxproject/puppet/blob/main/references/man/help.md

Details the `help` action itself, explaining how to display help for Puppet subcommands and their actions, including specific options like `--version` and `--ronn`.

```APIDOC
help - Display help about Puppet subcommands and their actions.

  SYNOPSIS
    puppet help [--version VERSION] [--ronn] [subcommand] [action]

  DESCRIPTION
    Display help about Puppet subcommands and their actions.

  OPTIONS
    --ronn - Whether to render the help text in ronn format.

    --version VERSION - The version of the subcommand for which to show help.

  RETURNS
    Short help text for the specified subcommand or action.
```

--------------------------------

### Hiera Configuration for Array Merge Lookup (YAML)

Source: https://github.com/openvoxproject/puppet/blob/main/references/function.md

Example Hiera YAML configuration and data files demonstrating how data is structured for an array merge lookup using `hiera_array`. This setup shows how values for the same key are merged from different hierarchy levels.

```YAML
# Assuming hiera.yaml
# :hierarchy:
#   - web01.example.com
#   - common

# Assuming common.yaml:
# users:
#   - 'cdouglas = regular'
#   - 'efranklin = regular'

# Assuming web01.example.com.yaml:
# users: 'abarry = admin'
```

--------------------------------

### Puppet Package Provider: portage

Source: https://github.com/openvoxproject/puppet/blob/main/references/types/package.md

Provides packaging support for Gentoo's portage system. This provider supports the `install_options` and `uninstall_options` attributes, which allows command-line flags to be passed to emerge. These options should be specified as an array where each element is either a string or a hash.

```APIDOC
Attributes:
  - Confined to: `os.family == gentoo`
  - Default for: `["os.family", "gentoo"] == `
  - Supported features: `install_options`, `purgeable`, `reinstallable`, `uninstall_options`, `versionable`, `virtual_packages`
```

--------------------------------

### Puppet: Check hash values and keys with two-argument lambda

Source: https://github.com/openvoxproject/puppet/blob/main/references/function.md

Illustrates using the `all` function with a hash and a two-argument lambda. The first argument receives the key, and the second receives the value, allowing checks on both. This example verifies if all values are multiples of 10 and keys start with 'abc'.

```Puppet
$data = {abc_123 => 10, abc_42 => 20, abc_blue => 30}
notice $data.all |$key, $value| { $value % 10 == 0  and $key =~ /^abc/ }
```

--------------------------------

### Example Custom Beaker Hosts File (hosts.yaml)

Source: https://github.com/openvoxproject/puppet/blob/main/acceptance/README.md

This YAML snippet shows the structure of a generated `hosts.yaml` file. It defines two hosts, `redhat7-64-1` and `windows2012r2-64-1`, specifying their platforms, packaging details, hypervisor, and roles (master/agent). It also includes a `CONFIG` section for global settings like `nfs_server`, `consoleport`, and the custom `pooling_api`.

```yaml
---
HOSTS:
  redhat7-64-1:
    platform: el-7-x86_64
    packaging_platform: el-7-x86_64
    template: redhat-7-x86_64
    hypervisor: vmpooler
    roles:
    - master
    - agent
  windows2012r2-64-1:
    platform: windows-2012r2-64
    packaging_platform: windows-2012-x64
    ruby_arch: x64
    template: win-2012r2-x86_64
    hypervisor: vmpooler
    roles:
    - agent
CONFIG:
  nfs_server: none
  consoleport: 443
  pooling_api: http://customvmpooler/
```

--------------------------------

### Example: Retrieve Certificate Information

Source: https://github.com/openvoxproject/puppet/blob/main/api/docs/http_certificate_status.md

Demonstrates an HTTP GET request to retrieve certificate details for 'mycertname' in the 'env' environment, followed by a sample HTTP 200 OK response with the certificate's name, state, various fingerprints, and DNS alternative names in PSON/JSON format.

```HTTP
GET /puppet-ca/v1/certificate_status/mycertname?environment=env
```

```JSON
HTTP/1.1 200 OK
Content-Type: text/pson

{
  "name":"mycertname",
  "state":"signed",
  "fingerprint":"A6:44:08:A6:38:62:88:5B:32:97:20:49:8A:4A:4A:AD:65:C3:3E:A2:4C:30:72:73:02:C5:F3:D4:0E:B7:FC:2F",
  "fingerprints":{
    "default":"A6:44:08:A6:38:62:88:5B:32:97:20:49:8A:4A:4A:AD:65:C3:3E:A2:4C:30:72:73:02:C5:F3:D4:0E:B7:FC:2F",
    "SHA1":"77:E6:5A:7E:DD:83:78:DC:F8:51:E3:8B:12:71:F4:57:F1:C2:34:AE",
    "SHA256":"A6:44:08:A6:38:62:88:5B:32:97:20:49:8A:4A:4A:AD:65:C3:3E:A2:4C:30:72:73:02:C5:F3:D4:0E:B7:FC:2F",
    "SHA512":"CA:A0:8C:B9:FE:9D:C2:72:18:57:08:E9:4B:11:B7:BC:4E:F7:52:C8:9C:76:03:45:B4:B6:C5:D2:DC:E8:79:43:D7:71:1F:5C:97:FA:B2:F3:ED:AE:19:BD:A9:3B:DB:9F:A5:B4:8D:57:3F:40:34:29:50:AA:AA:0A:93:D8:D7:54"
  },
  "dns_alt_names":["DNS:puppet","DNS:mycertname"]
}
```

--------------------------------

### Hiera Configuration for Hash Merge Lookup (YAML)

Source: https://github.com/openvoxproject/puppet/blob/main/references/function.md

Example Hiera YAML configuration and data files demonstrating how data is structured for a hash merge lookup using `hiera_hash`. This setup shows how values for the same key are merged from different hierarchy levels, with higher priority values overriding lower ones.

```YAML
# Assuming hiera.yaml
# :hierarchy:
#   - web01.example.com
#   - common

# Assuming common.yaml:
# users:
#   regular:
#     'cdouglas': 'Carrie Douglas'
```

--------------------------------

### Example `hosts.yaml` for Docker Environment

Source: https://github.com/openvoxproject/puppet/blob/main/acceptance/README.md

This YAML snippet illustrates the structure of a `hosts.yaml` file generated for Docker, defining two CentOS 7 nodes (master and agent). It specifies Docker-specific configurations like `image`, `docker_cmd`, and `docker_image_commands` for provisioning.

```YAML
---
HOSTS:
  centos7-64-1:
    docker_cmd:
    - "/sbin/init"
    image: centos:7
    platform: centos-7-x86_64
    packaging_platform: el-7-x86_64
    docker_image_commands:
    - cp /bin/true /sbin/agetty
    - yum install -y crontabs initscripts iproute openssl sysvinit-tools tar wget
      which ss
    hypervisor: docker
    roles:
    - master
  centos7-64-2:
    docker_cmd:
    - "/sbin/init"
    image: centos:7
    platform: centos-7-x86_64
    packaging_platform: el-7-x86_64
    docker_image_commands:
    - cp /bin/true /sbin/agetty
    - yum install -y crontabs initscripts iproute openssl sysvinit-tools tar wget
      which ss
    hypervisor: docker
    roles:
    - agent
CONFIG:
  nfs_server: none
  consoleport: 443

```

--------------------------------

### Pacman Package Provider for Puppet (Archlinux)

Source: https://github.com/openvoxproject/puppet/blob/main/references/type.md

Support for the Package Manager Utility (pacman) used in Archlinux. This provider supports the `install_options` attribute, which allows command-line flags to be passed to pacman. These options should be specified as an array where each element is either a string or a hash.

```APIDOC
Pacman Package Provider:
  Description: Support for the Package Manager Utility (pacman) used in Archlinux.
  Required Binaries: /usr/bin/pacman
  Default for: os.name == archlinux, manjarolinux, artix
  Supported Features: install_options, installable, purgeable, uninstall_options, uninstallable, upgradeable, virtual_packages
  Notes:
    - Supports `install_options` attribute.
    - Options should be an array where each element is a string or a hash.
```