### Slow Start Configuration Example

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-upstream-member.md

Gradually increase the weight of a server over a specified duration after it becomes available. Requires Nginx 1.7.10+.

```puppet
# Gradually increase weight over 60 seconds
slow_start => '60s',
```

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

### Install and Bootstrap Nginx Instance

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/README.md

Use this snippet to install and bootstrap a basic Nginx instance on your system using the Puppet module.

```puppet
include nginx
```

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

### Install NGINX with Default Repository

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/docs/quickstart.md

Call the 'nginx' class to install NGINX using the distribution's default package repository.

```puppet
class{'nginx': }
```

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

### Install NGINX with NGINX Project Repository

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/docs/quickstart.md

Configure the 'nginx' class to manage package repositories and install NGINX from the NGINX project's mainline repository. Ensure EPEL is installed on CentOS/RHEL.

```puppet
class{'nginx':
    manage_repo => true,
    package_source => 'nginx-mainline'
}
```

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

### Configure PHP Files (FastCGI)

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-location.md

This example shows how to configure a location to process PHP files using FastCGI. It specifies the FastCGI backend and parameters.

```puppet
nginx::resource::location {
  'php':
    ensure            => present,
    location          => '~ \.php$',
    server            => 'example.com',
    fastcgi           => '127.0.0.1:9000',
    fastcgi_script    => '$document_root$fastcgi_script_name',
    fastcgi_param     => {
      'SCRIPT_FILENAME' => '$document_root$fastcgi_script_name',
    },
}
```

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

### Failover Configuration Examples

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-upstream-member.md

Configure how many failures trigger a server to be marked down and for how long. Use '0' for immediate marking down.

```puppet
# Mark down after 3 failures for 30 seconds
max_fails => 3,
fail_timeout => '30s',
```

```puppet
# Mark down immediately (0 fails needed)
max_fails => 0,
fail_timeout => '60s',
```

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

### Complex Upstream Configuration with Multiple Options

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-upstream-member.md

Demonstrates a comprehensive upstream configuration including weight, connection limits, failover parameters, slow start, and backup servers. This example showcases advanced load balancing and resilience settings.

```puppet
nginx::resource::upstream {
  'production_backend':
    keepalive => 32,
    members => {
      'main1' => {
        server      => 'main1.example.com',
        port        => 3000,
        weight      => 5,
        max_conns   => 200,
        max_fails   => 5,
        fail_timeout => '60s',
        slow_start  => '30s',
        comment     => 'Primary production server with high capacity',
      },
      'main2' => {
        server      => 'main2.example.com',
        port        => 3000,
        weight      => 5,
        max_conns   => 200,
        max_fails   => 5,
        fail_timeout => '60s',
        slow_start  => '30s',
        comment     => 'Secondary production server',
      },
      'secondary' => {
        server      => 'secondary.example.com',
        port        => 3000,
        weight      => 2,
        max_conns   => 100,
        comment     => 'Secondary capacity, lower weight',
      },
      'standby' => {
        server => 'standby.example.com',
        port   => 3000,
        backup => true,
        comment => 'Emergency standby, only activated if all others down',
      },
    },
}
```

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

### Virtual Host with FastCGI Configuration

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-server.md

This example demonstrates configuring a virtual host to work with FastCGI applications. It specifies the FastCGI parameters and the script to execute.

```puppet
nginx::resource::server {
  'php.example.com':
    fastcgi => 'http://127.0.0.1:9000',
    fastcgi_param => {
      'SCRIPT_FILENAME' => '$document_root$fastcgi_script_name',
    },
    fastcgi_index => 'index.php',
    fastcgi_script => '/index.php',
}
```

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

### Create Simple Server Resource

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/REFERENCE.md

Define a basic Nginx virtual host using `nginx::resource::server`. This example configures SSL, certificate, and key paths.

```puppet
nginx::resource::server {
  'test2.local':
    ensure   => present,
    www_root => '/var/www/nginx-default',
    ssl      => true,
    ssl_cert => '/tmp/server.crt',
    ssl_key  => '/tmp/server.pem',
}
```

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

### expires

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/REFERENCE.md

Setup expires time for locations content.

```APIDOC
## `expires`

### Description
Setup expires time for locations content.

### Data Type
Optional[String]

### Default Value
`undef`
```

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

### Example Usage of nginx::resource::geo

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-geo-map-snippet.md

This example demonstrates how to use the nginx::resource::geo resource to map IP address ranges to location names. The `$client_geo` variable can then be used in NGINX configurations for routing.

```puppet
nginx::resource::geo { 'client_geo':
  ensure          => present,
  default         => 'unknown',
  address         => 'remote_addr',  # Uses $remote_addr
  networks        => {
    'north_america' => ['10.0.0.0/8', '172.16.0.0/12'],
    'europe'        => ['192.168.0.0/16'],
    'asia'          => ['203.0.113.0/24'],
  },
}
```

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

### Configure Nginx with Passenger on OpenBSD

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/README.md

This example shows how to configure Nginx with Passenger on OpenBSD. It specifies the 'package_flavor' and 'service_flags', along with detailed 'passenger_root', 'passenger_ruby', and 'passenger_max_pool_size' settings.

```puppet
class {
  'nginx':
    package_flavor => 'passenger',
    service_flags  => '-u'
    http_cfg_append => {
      passenger_root          => '/usr/local/lib/ruby/gems/2.1/gems/passenger-4.0.44',
      passenger_ruby          =>  '/usr/local/bin/ruby21',
      passenger_max_pool_size => '15',
    }
}

```

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

### Nginx::UpstreamSticky Learn Mode Configuration

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/types.md

Example structure for configuring learn-based session affinity. Includes parameters for route creation, lookup, zone, and timeouts.

```puppet
{
  'learn' => {
    create  => String,
    lookup  => String,
    zone    => Nginx::UpstreamStickyZone,
    timeout => Optional[Nginx::Time],
    header  => Optional[Boolean],
    sync    => Optional[Boolean],
  }
}
```

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

### Configure Upstream Proxy with Caching

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-location.md

This example sets up a location to proxy requests to an upstream server and enables caching for the responses. It includes various caching directives.

```puppet
nginx::resource::location {
  'cached-api':
    ensure                  => present,
    location                => '/api/',
    server                  => 'example.com',
    proxy                   => 'http://api_backend',
    proxy_cache             => 'api_cache',
    proxy_cache_valid       => '200 10m',
    proxy_cache_use_stale   => 'error timeout invalid_header updating',
    proxy_cache_key         => '$scheme$request_method$host$request_uri',
}
```

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

### Check Installed NGINX Version

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/facts.md

Use this command to check the installed NGINX version directly from the command line. If this command returns nothing, the `nginx_version` fact may not be detected correctly.

```puppet
# Check installed NGINX
nginx --version
```

```puppet
# Manually set version in manifest
class {
  'nginx':
    nginx_version => '1.18.0',
}

```

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

### Virtual Host with SSL Enabled

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-server.md

This example shows how to configure a virtual host with SSL/TLS enabled. It specifies the SSL certificate and key paths, and enables SSL redirection to the HTTPS port.

```puppet
nginx::resource::server {
  'secure.example.com':
    ssl => true,
    ssl_cert => '/etc/nginx/ssl/secure.example.com.crt',
    ssl_key => '/etc/nginx/ssl/secure.example.com.key',
    ssl_redirect => true,
    ssl_redirect_port => 443,
}
```

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

### Virtual Host with Multiple Server Names

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-server.md

This example configures a virtual host to respond to multiple server names. This is useful for hosting multiple domains on the same server block.

```puppet
nginx::resource::server {
  'multiname.example.com':
    server_name => ['www.example.net', 'example.net'],
    www_root => '/var/www/multiname',
}
```

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

### Custom Parameters Example

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-upstream-member.md

Append custom Nginx parameters to a member configuration. This allows for directives not explicitly modeled.

```puppet
params_append => 'max_fails=10; fail_timeout=10s;'
```

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

### Virtual Host with HTTP/2 Enabled

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-server.md

This example enables HTTP/2 support for a virtual host. Ensure your NGINX version and SSL configuration support HTTP/2.

```puppet
nginx::resource::server {
  'http2.example.com':
    http2 => 'on',
    ssl => true,
    ssl_cert => '/etc/nginx/ssl/http2.example.com.crt',
    ssl_key => '/etc/nginx/ssl/http2.example.com.key',
}
```

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

### Configure Regex Pattern Matching for Locations

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-location.md

This example demonstrates using a regular expression to match specific URL patterns for a location, useful for serving files based on complex criteria.

```puppet
nginx::resource::location {
  'images':
    ensure   => present,
    location => '~ ^/images/(.*)$',
    server   => 'example.com',
    www_root => '/var/www/media',
}
```

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

### Syslog Forwarding

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-streamhost.md

Configure syslog forwarding using UDP. This example defines an upstream group for syslog servers and a streamhost to forward messages to them.

```puppet
nginx::resource::upstream {
  'syslog_servers':
    ensure  => present,
    context => 'stream',
    members => {
      'syslog1' => {
        server => 'syslog1.example.com',
        port   => 514,
      },
      'syslog2' => {
        server => 'syslog2.example.com',
        port   => 514,
      },
    },
}

nginx::resource::streamhost {
  'syslog_proxy':
    ensure         => present,
    listen_port    => 514,
    listen_options => 'udp',
    proxy          => 'syslog_servers',
}

```

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

### Configure NGINX with Version-Specific Features

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/facts.md

Configure NGINX with version-specific features like HTTP/3, QUIC, and SSL protocols by setting the `nginx_version` fact and related parameters. This example targets NGINX version 1.21.0 and enables modern features.

```puppet
class {
  'nginx':
    nginx_version => '1.21.0',
    # Modern nginx with HTTP/3, QUIC, and advanced features
    http2 => 'on',
    ssl_protocols => 'TLSv1.2 TLSv1.3',
}
```

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

### Configure Nginx with Passenger on Debian/RHEL

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/README.md

Use this configuration for Debian and RHEL/CentOS systems when installing Nginx with Passenger from the Phusion repository. Ensure the 'passenger_root' is correctly set.

```puppet
class {
  'nginx':
    package_source  => 'passenger',
    http_cfg_append => {
      'passenger_root' => '/usr/lib/ruby/vendor_ruby/phusion_passenger/locations.ini',
    }
}

```

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

### Request Method Detection

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-geo-map-snippet.md

Use this example to determine if a request method is allowed or not. It maps HTTP request methods to a binary value (1 for allowed, 0 for not allowed).

```puppet
nginx::resource::map { 'method_allowed':
  ensure   => present,
  string   => '$request_method',
  default  => '0',
  mappings => {
    'GET'     => '1',
    'HEAD'    => '1',
    'POST'    => '1',
    'PUT'     => '0',
    'DELETE'  => '0',
  },
}
```

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

### Slow Start Recovery Upstream

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-upstream-member.md

Configures members with a 'slow_start' parameter, allowing new connections to ramp up gradually over a specified period. This is useful for preventing sudden load spikes on newly added or recovered servers.

```puppet
nginx::resource::upstream {
  'backend':
    members => {
      'app1' => {
        server     => 'app1.example.com',
        port       => 3000,
        slow_start => '60s',
      },
      'app2' => {
        server     => 'app2.example.com',
        port       => 3000,
        slow_start => '60s',
      },
    },
}
```

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

### Nginx Class Declaration with Parameters

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/nginx-class.md

This snippet shows the declaration of the main NGINX class in Puppet, including a comprehensive list of parameters for configuring various aspects of NGINX. Use this class to manage NGINX installation and its core settings.

```puppet
class nginx (
  Optional[Variant[Stdlib::Absolutepath, Tuple[Stdlib::Absolutepath, Integer, 1, 4]]] $client_body_temp_path = undef,
  Boolean $confd_only = false,
  Boolean $confd_purge = false,
  Stdlib::Absolutepath $conf_dir = $nginx::params::conf_dir,
  Optional[Enum['on', 'off']] $daemon = undef,
  String[1] $daemon_user = $nginx::params::daemon_user,
  Optional[String[1]] $daemon_group = undef,
  Array[String] $dynamic_modules = [],
  String[1] $global_owner = 'root',
  String[1] $global_group = $nginx::params::global_group,
  Stdlib::Filemode $global_mode = '0644',
  Optional[Variant[String[1], Array[String[1]]]] $limit_req_zone = undef,
  Stdlib::Absolutepath $log_dir = $nginx::params::log_dir,
  Boolean $manage_log_dir = true,
  String[1] $log_user = $nginx::params::log_user,
  String[1] $log_group = $nginx::params::log_group,
  Stdlib::Filemode $log_mode = $nginx::params::log_mode,
  Variant[String, Array[String]] $http_access_log = "${log_dir}/access.log",
  Optional[String] $http_format_log = undef,
  Variant[String, Array[String]] $stream_access_log = "${log_dir}/stream-access.log",
  Optional[String] $stream_custom_format_log = undef,
  Variant[String, Array[String]] $nginx_error_log = "${log_dir}/error.log",
  Nginx::ErrorLogSeverity $nginx_error_log_severity = 'error',
  Variant[Stdlib::Absolutepath, Boolean] $pid = $nginx::params::pid,
  Optional[Variant[Stdlib::Absolutepath, Tuple[Stdlib::Absolutepath, Integer, 1, 4]]] $proxy_temp_path = undef,
  String[1] $root_group = $nginx::params::root_group,
  String[1] $sites_available_owner = 'root',
  String[1] $sites_available_group = $nginx::params::sites_available_group,
  Stdlib::Filemode $sites_available_mode = '0644',
  Boolean $super_user = true,
  Stdlib::Absolutepath $temp_dir = '/tmp',
  Boolean $server_purge = false,
  Boolean $include_modules_enabled = $nginx::params::include_modules_enabled,
  String[1] $conf_template = 'nginx/conf.d/nginx.conf.erb',
  String[1] $fastcgi_conf_template = 'nginx/server/fastcgi.conf.erb',
  String[1] $uwsgi_params_template = 'nginx/server/uwsgi_params.erb',
  Optional[Enum['on', 'off']] $absolute_redirect = undef,
  Optional[Enum['on', 'off']] $accept_mutex = undef,
  Optional[Nginx::Time] $accept_mutex_delay = undef,
  Optional[Nginx::Size] $client_body_buffer_size = undef,
  Optional[Nginx::Size] $client_max_body_size = undef,
  Optional[Nginx::Time] $client_body_timeout = undef,
  Optional[Nginx::Time] $send_timeout = undef,
  Optional[Nginx::Time] $lingering_timeout = undef,
  Optional[Enum['on', 'off', 'always']] $lingering_close = undef,
  Optional[String[1]] $lingering_time = undef,
  Optional[Enum['on', 'off']] $etag = undef,
  Optional[String] $events_use = undef,
  Array[Nginx::DebugConnection] $debug_connections = [],
  Nginx::Time $fastcgi_cache_inactive = '20m',
  Optional[String] $fastcgi_cache_key = undef,
  String $fastcgi_cache_keys_zone = 'd3:100m',
  String $fastcgi_cache_levels = '1',
  Nginx::Size $fastcgi_cache_max_size = '500m',
  Optional[Variant[Hash,String[1]]] $fastcgi_cache_path = undef,
  Optional[String] $fastcgi_cache_use_stale = undef,
  Optional[Enum['on', 'off']] $gzip = undef,
  Optional[String] $gzip_buffers = undef,
  Optional[Integer] $gzip_comp_level = undef,
  String $gzip_disable = 'msie6',
  Optional[Integer] $gzip_min_length = undef,
  Optional[Enum['1.0', '1.1']] $gzip_http_version = undef,
  Optional[Variant[Nginx::GzipProxied, Array[Nginx::GzipProxied]]] $gzip_proxied = undef,
  Optional[Variant[String[1], Array[String[1]]]] $gzip_types = undef,
  Optional[Enum['on', 'off']] $gzip_vary = undef,
  Optional[Enum['on', 'off', 'always']] $gzip_static = undef,
  Optional[Variant[Hash, Array]] $http_cfg_prepend = undef,
  Optional[Variant[Hash, Array]] $http_cfg_append = undef,
  Optional[Variant[Array[String], String]] $http_raw_prepend = undef,
  Optional[Variant[Array[String], String]] $http_raw_append = undef,
  Optional[Enum['on', 'off']] $http_tcp_nodelay = undef,
  Optional[Enum['on', 'off']] $http_tcp_nopush = undef,
  Optional[Nginx::Time] $keepalive_timeout = undef,
  Optional[Integer] $keepalive_requests = undef,
  Hash[String[1], Nginx::LogFormat] $log_format = {},
  Hash[String[1], Nginx::LogFormat] $stream_log_format = {},
  Boolean $mail = false,
  Optional[Integer] $map_hash_bucket_size = undef,
  Optional[Integer] $map_hash_max_size = undef,
  Variant[String, Boolean] $mime_types_path = 'mime.types',
  Boolean $stream = false,
  Optional[Enum['on', 'off']] $multi_accept = undef,
  Optional[Integer] $names_hash_bucket_size = undef,
  Optional[Integer] $names_hash_max_size = undef,
  Variant[Boolean, Array, Hash] $nginx_cfg_prepend = false,
  Optional[String] $proxy_buffers = undef,
  Optional[Nginx::Size] $proxy_buffer_size = undef,
) -> Class['nginx::params'] {
  # ... class implementation ...
}
```

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

### High-Availability Setup with Upstream

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/README.md

Configures a high-availability setup using Nginx upstream blocks with weighted and backup servers. This ensures resilience by distributing traffic and providing failover.

```puppet
nginx::resource::upstream { 'backend':
  members => {
    'primary1' => { server => 'app1.local', port => 3000, weight => 2 },
    'primary2' => { server => 'app2.local', port => 3000, weight => 2 },
    'backup' => { server => 'backup.local', port => 3000, backup => true },
  },
  keepalive => 32,
}

nginx::resource::server { 'www.example.com':
  proxy => 'http://backend',
}
```

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

### Create a basic streamhost

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/REFERENCE.md

This snippet demonstrates how to create a basic virtual streamhost. Ensure the `ensure` parameter is set to `present` to enable it.

```puppet
nginx::resource::streamhost {
  'test2.local':
    ensure   => present,
}
```

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

### Define Upstream with Slow Start Recovery

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-upstream.md

Implement slow start recovery for upstream servers. This allows new or restarted servers to gradually increase their weight, preventing sudden traffic surges.

```puppet
nginx::resource::upstream { 'slow_start_backend':
  ensure  => present,
  members => {
    'server1' => {
      server     => 'app1.example.com',
      port       => 3000,
      slow_start => '30s',  # Gradually increase weight after restart
    },
    'server2' => {
      server     => 'app2.example.com',
      port       => 3000,
      slow_start => '30s',
    },
  },
}
```

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

### Basic Static Website Configuration

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-server.md

Define a basic server block for serving static files. Ensure the 'ensure' parameter is set to 'present' to create the resource.

```puppet
nginx::resource::server {
  'example.com':
    ensure   => present,
    www_root => '/var/www/example.com',
    index_files => ['index.html', 'index.htm'],
}
```

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

### Full Web Server with SSL Configuration

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/README.md

Configures a full web server with SSL enabled, including specific SSL protocols and gzip compression. Use this for serving static content securely over HTTPS.

```puppet
class { 'nginx':
  gzip => 'on',
  gzip_types => ['text/plain', 'text/css', 'application/json'],
  http2 => 'on',
  ssl_protocols => 'TLSv1.2 TLSv1.3',
}

nginx::resource::server { 'www.example.com':
  listen_port => 80,
  ssl => true,
  ssl_port => 443,
  ssl_cert => '/etc/ssl/certs/example.crt',
  ssl_key => '/etc/ssl/private/example.key',
  www_root => '/var/www/example.com',
  ssl_redirect => true,
}
```

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

### Puppet Usage for nginx::resource::location with uwsgi_param

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/REFERENCE.md

Example of adding custom `uwsgi_param` directives to a location. This is used for configuring uWSGI applications.

```puppet
nginx::resource::location {
  'test2.local-bob':
    ensure       => present,
    www_root     => '/var/www/bob',
    location     => '/bob',
    server       => 'test2.local',
    uwsgi_param  => {
       'APP_ENV' => 'local',
    }
}
```

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

### Basic Virtual Host Configuration

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-server.md

This snippet demonstrates the basic configuration of a virtual host using the `nginx::resource::server` definition. It sets the server name and the root directory for web content.

```puppet
nginx::resource::server {
  'example.com':
    www_root => '/var/www/example.com/public',
}
```

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

### Puppet Usage for nginx::resource::location with fastcgi_param

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/REFERENCE.md

Example of adding custom `fastcgi_param` directives to a location. This is used for configuring FastCGI applications.

```puppet
nginx::resource::location {
  'test2.local-bob':
    ensure        => present,
    www_root      => '/var/www/bob',
    location      => '/bob',
    server        => 'test2.local',
    fastcgi_param => {
       'APP_ENV'  => 'local',
    }
}
```

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

### Basic Website Hosting with nginx::resource::server

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/README.md

Use this snippet to create a basic server block for hosting a website. It defines the document root for the site.

```puppet
include nginx

nginx::resource::server {
  'example.com':
    www_root => '/var/www/example.com',
}

```

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

### Nginx::UpstreamSticky Route Mode Configuration

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/types.md

Example structure for configuring route-based session affinity. Uses a string variable containing the route identifier.

```puppet
{
  'route' => '$route_id'
}
```

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

### Define a Virtual Host for Static Content

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/docs/quickstart.md

Define a virtual host for 'www.myhost.com' to serve static HTML files from '/opt/html/'. This sets up a basic web server on port 80.

```puppet
nginx::resource::server{'www.myhost.com':
    www_root => '/opt/html/',
  }
```

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

### Nginx::UpstreamSticky Cookie Mode Configuration

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/types.md

Example structure for configuring cookie-based session affinity. Specifies cookie name, expiration, domain, and other attributes.

```puppet
{
  'cookie' => {
    name     => String,
    expires  => Optional[Nginx::Time or 'max'],
    domain   => Optional[String],
    httponly => Optional[Boolean],
    secure   => Optional[Boolean],
    path     => Optional[String],
  }
}
```

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

### Configure Additional IPv6 Listen Options

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/REFERENCE.md

Add extra options to the listen directive for IPv6, such as 'default' for catchall. If 'listen_options' is already set, 'ipv6only=on' will be appended.

```puppet
ipv6_listen_options => 'ipv6only=on',
```

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

### Enable SPDY and HTTP/2

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/nginx-class.md

Enables SPDY and HTTP/2 protocols and sets SSL protocols for Nginx.

```puppet
class {
  'nginx':
    spdy  => 'on',
    http2 => 'on',
    ssl_protocols => 'TLSv1.2 TLSv1.3',
  }
}
```

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

### Configure Mandatory STARTTLS and Proxy Protocol

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-mailhost.md

Configure an SMTP proxy requiring mandatory STARTTLS and supporting the proxy protocol for load balancers.

```puppet
nginx::resource::mailhost {
  'secure-smtp.example.com':
    ensure          => present,
    listen_port     => 25,
    protocol        => 'smtp',
    auth_http       => 'auth.example.com/auth',
    starttls        => 'only',  # Require STARTTLS (mandatory)
    smtp_auth       => 'plain login',
    proxy_protocol  => 'on',    # Support proxy protocol from load balancers
}

```

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

### Virtual Host with Caching Enabled

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-server.md

This example configures NGINX to cache responses from a backend server. It specifies cache settings like validity and bypass conditions.

```puppet
nginx::resource::server {
  'cache.example.com':
    proxy => 'http://127.0.0.1:8080',
    proxy_cache => 'TRUE',
    proxy_cache_key => '$scheme$request_method$host$request_uri',
    proxy_cache_valid => '60m',
    proxy_cache_use_stale => 'error timeout updating http_500',
}
```

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

### Configure SSL with Redirect

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/README.md

Call the `web::nginx_ssl_with_redirect` class to set up an Nginx server with SSL enabled and automatic redirection from HTTP to HTTPS. Specify the backend port for your application.

```puppet
web::nginx_ssl_with_redirect {
    backend_port => 9001,
  }
```

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

### Hiera Usage for Map Configuration

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/REFERENCE.md

Configure `nginx::resource::map` using Hiera data. This example shows a basic map configuration with hostnames and a default value.

```puppet
nginx::string_mappings:
  client_network:
    ensure: present
    hostnames: true
    default: 'ny-pool-1'
    string: $http_host
    mappings:
      '*.nyc.example.com': 'ny-pool-1'
      '*.sf.example.com': 'sf-pool-1'
```

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

### Primary and Backup Upstream Configuration

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-upstream-member.md

Sets up an upstream with a primary server and a backup server. The backup is only used if the primary becomes unavailable.

```puppet
nginx::resource::upstream {
  'backend':
    members => {
      'primary' => {
        server => 'primary.example.com',
        port   => 3000,
        max_fails => 3,
        fail_timeout => '30s',
      },
      'backup' => {
        server => 'backup.example.com',
        port   => 3000,
        backup => true,
      },
    },
}
```

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

### Puppet Usage for nginx::resource::location across multiple servers

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/REFERENCE.md

Example showing how to apply a single location definition to multiple servers. This is useful for shared configurations.

```puppet
nginx::resource::location {
  'test2.local-bob':
    ensure   => present,
    www_root => '/var/www/bob',
    location => '/bob',
    server   => ['test1.local','test2.local'],
}
```

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

### FastCGI Backend (PHP) Configuration

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-server.md

Set up a server to handle FastCGI requests, typically for PHP applications. This involves configuring both the server and a specific location block for FastCGI processing.

```puppet
nginx::resource::server {
  'php.example.com':
    ensure    => present,
    www_root  => '/var/www/php',
    index_files => ['index.php', 'index.html'],
}

nginx::resource::location {
  'php-location':
    ensure            => present,
    server            => 'php.example.com',
    location          => '~ \.php$',
    fastcgi           => '127.0.0.1:9000',
    fastcgi_index     => 'index.php',
}
```

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

### UDP DNS Forwarding

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-streamhost.md

Set up UDP DNS forwarding. This example defines an upstream group for DNS servers and configures a streamhost to listen on UDP port 53.

```puppet
nginx::resource::upstream {
  'dns_servers':
    ensure  => present,
    context => 'stream',
    members => {
      'ns1' => {
        server => '8.8.8.8',
        port   => 53,
      },
      'ns2' => {
        server => '8.8.4.4',
        port   => 53,
      },
    },
}

nginx::resource::streamhost {
  'dns_proxy':
    ensure         => present,
    listen_port    => 53,
    listen_options => 'udp',  # UDP protocol
    proxy          => 'dns_servers',
}

```

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

### Configure Virtual Host with Static Content

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/README.md

Configure a virtual host to serve static content from a specified web root directory.

```puppet
nginx::resource::server {
  'voxpupuli.org':
    www_root => '/var/www/voxpupuli.org',
  }
}
```

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

### Puppet Usage for nginx::resource::location with custom config

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/REFERENCE.md

Example demonstrating how to append custom configuration directives to a location block. This allows for fine-grained control over location behavior.

```puppet
$my_config = {
  'access_log' => 'off',
  'allow'      => '127.0.0.1',
  'deny'       => 'all'
}
nginx::resource::location {
  'test2.local-bob':
    ensure              => present,
    www_root            => '/var/www/bob',
    location            => '/bob',
    server              => 'test2.local',
    location_cfg_append => $my_config,
}
```

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

### Configure Multi-Host with IPv6

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-mailhost.md

Set up a mailhost resource for multiple server names, listening on both IPv4 and IPv6, with specific port configurations.

```puppet
nginx::resource::mailhost {
  'mail.example.com':
    ensure             => present,
    listen_port        => 587,
    listen_ip          => ['0.0.0.0', '::'],
    ipv6_enable        => true,
    ipv6_listen_port   => 587,
    protocol           => 'smtp',
    auth_http          => 'auth.example.com/auth',
    server_name        => ['mail.example.com', 'mail1.example.com'],
    starttls           => 'on',
    smtp_auth          => 'plain login',
}

```

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

### Hiera Usage for nginx::resource::geo

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/REFERENCE.md

Example of defining geo mappings using Hiera, demonstrating the reuse of network definitions. This is an alternative to direct Puppet DSL usage.

```yaml
# Define network lists that can be reused
my_internal_networks: &internal_nets
  - '10.0.0.0/8'
  - '172.16.0.0/12'
  - '192.168.0.0/16'

nginx::geo_mappings:
  client_network:
    ensure: present
    ranges: false
    default: 'extra'
    proxy_recursive: false
    proxies:
      - 192.168.99.99
    networks:
      intra: *internal_nets
```

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

### Configure Simple Reverse Proxy

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/README.md

Set up a simple reverse proxy for an application like Kibana. Ensure the target application is running and accessible.

```puppet
nginx::resource::server {
  'kibana.myhost.com':
    listen_port => 80,
    proxy       => 'http://localhost:5601',
  }
}
```

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

### Define Upstream with Custom Hash Function

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-upstream.md

Configure an upstream block using a custom hash function for routing requests. This example uses the request URI for consistent hashing.

```puppet
nginx::resource::upstream { 'hash_backend':
  ensure  => present,
  hash    => '$request_uri consistent',
  members => {
    'server1' => {
      server => 'cache1.example.com',
      port   => 6379,
    },
    'server2' => {
      server => 'cache2.example.com',
      port   => 6379,
    },
  },
}
```

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

### Create Map Entry Using External Include File

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/REFERENCE.md

For complex or numerous mappings, use the `include_files` parameter in `nginx::resource::map` to load definitions from external files.

```puppet
nginx::resource::map {
   'redirections':
     include_files => [ '/etc/nginx/conf.d/redirections.map']
}
```

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

### Multiple Server Names Configuration

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-server.md

Define a server block that responds to multiple domain names. Use the 'server_name' parameter with an array of hostnames.

```puppet
nginx::resource::server {
  'example.com':
    ensure       => present,
    server_name  => ['example.com', 'www.example.com', 'api.example.com'],
    www_root     => '/var/www/example.com',
}
```

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

### Redis Load Balancing with Keepalive

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-streamhost.md

Configure TCP load balancing for Redis with keepalive enabled. This example defines an upstream group with a keepalive setting and a streamhost to proxy connections.

```puppet
nginx::resource::upstream {
  'redis_backend':
    ensure  => present,
    context => 'stream',
    keepalive => 32,
    members => {
      'redis1' => {
        server => 'redis1.example.com',
        port   => 6379,
      },
      'redis2' => {
        server => 'redis2.example.com',
        port   => 6379,
      },
    },
}

nginx::resource::streamhost {
  'redis_proxy':
    ensure          => present,
    listen_port     => 6379,
    proxy           => 'redis_backend',
}

```

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

### raw_prepend

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/REFERENCE.md

Allows prepending raw Nginx configuration directives to the location block. Can be a single string or an array of strings. Ensure semicolons are added where necessary.

```APIDOC
## `raw_prepend`

### Description
Allows prepending raw Nginx configuration directives to the location block. Can be a single string or an array of strings. Ensure semicolons are added where necessary.

### Data Type
`Optional[Variant[String, Array]]`

### Default Value
`undef`
```

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

### Puppet Usage for nginx::resource::geo

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/REFERENCE.md

Example of how to define a geo mapping entry using the `nginx::resource::geo` defined type in Puppet. This configures network ranges for geo-based routing.

```puppet
nginx::resource::geo {
  'client_network':
    ensure          => present,
    ranges          => false,
    default         => extra,
    proxy_recursive => false,
    proxies         => [ '192.168.99.99' ],
    networks        => {
      'intra' => ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'],
    }
}
```

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

### Check Detected OS Facts

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/facts.md

Inspect the detected OS family facts using `facter`. This is useful if the module is incorrectly identifying the operating system. Manual override is rarely needed.

```puppet
# Check detected facts
facter os
facter os.family
```

```puppet
# Manually override if needed (rare)
class {
  'nginx':
    daemon_user => 'www',
    daemon_group => 'www',
    conf_dir => '/usr/local/etc/nginx',
}

```

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

### Define Upstream with Random Load Balancing

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/resource-upstream.md

Set up an upstream block for random load balancing, selecting from a specified number of random servers. This example uses 'two' to select from two random servers.

```puppet
nginx::resource::upstream { 'random_backend':
  ensure  => present,
  random  => 'two',  # Select from two random servers, use least connections
  members => {
    'server1' => {
      server => 'app1.example.com',
      port   => 3000,
    },
    'server2' => {
      server => 'app2.example.com',
      port   => 3000,
    },
    'server3' => {
      server => 'app3.example.com',
      port   => 3000,
    },
  },
}
```

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

### Check IPv6 Capability and Force Enable

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/_autodocs/facts.md

Verify if IPv6 is supported by checking the `networking.ip6` fact. If detection fails, you can explicitly enable IPv6 for an Nginx server resource.

```puppet
# Check IPv6 capability
facter networking.ip6
```

```puppet
# Force IPv6 if detection fails
nginx::resource::server {
  'example.com':
    ipv6_enable => true,
    ipv6_listen_ip => '::',
}

```

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

### Create Basic Map Entry with Two Mappings

Source: https://github.com/voxpupuli/puppet-nginx/blob/master/REFERENCE.md

Use `nginx::resource::map` to define a mapping with hostnames enabled and a default pool. This is useful for routing traffic based on hostnames.

```puppet
nginx::resource::map {
  'backend_pool':
    ensure    => present,
    hostnames => true,
    default   => 'ny-pool-1',
    string    => '$http_host',
    mappings  => {
      '*.nyc.example.com' => 'ny-pool-1',
      '*.sf.example.com'  => 'sf-pool-1',
    }
}
```