Reference

nginx::config: Manage NGINX bootstrap and configuration
nginx::package: Manage NGINX package installation
nginx::package::debian: Manage NGINX package installation on debian based systems
nginx::package::redhat: Manage NGINX package installation on RedHat based systems
nginx::params: default settings and according to operating system
nginx::service: Manage NGINX service management

Defined types

nginx::resource::geo: Create a new geo mapping entry for NGINX
nginx::resource::location: Create a new location entry within a virtual host
nginx::resource::mailhost: Define a mailhost
nginx::resource::map: Create a new mapping entry for NGINX
nginx::resource::server: Create a virtual host
nginx::resource::snippet: Create a reusable config snippet that can be included by other resources
nginx::resource::streamhost: Create a virtual steamhost
nginx::resource::upstream: Create a new upstream proxy entry for NGINX
nginx::resource::upstream::member: Create an upstream member inside the upstream block.

Data types

Nginx::DebugConnection
Nginx::ErrorLogSeverity
Nginx::Size
Nginx::Time
Nginx::UpstreamCustomParameters
Nginx::UpstreamDefaults
Nginx::UpstreamLeastTime
Nginx::UpstreamLeastTimeHttp
Nginx::UpstreamLeastTimeStream
Nginx::UpstreamMember
Nginx::UpstreamMemberDefaults
Nginx::UpstreamMemberServer
Nginx::UpstreamMembers
Nginx::UpstreamSticky
Nginx::UpstreamStickyZone
Nginx::UpstreamZone

Classes

`nginx`

Packaged NGINX

RHEL: EPEL or custom package
Debian/Ubuntu: Default Install or custom package
SuSE: Default Install or custom package

Examples

Use the sensible defaults

include nginx

Parameters

The following parameters are available in the nginx class.

`include_modules_enabled`

Data type: Boolean

When set, nginx will include module configurations files installed in the /etc/nginx/modules-enabled directory.

Default value: $nginx::params::include_modules_enabled

`passenger_package_name`

Data type: String[1]

The name of the package to install in order for the passenger module of nginx being usable.

Default value: $nginx::params::passenger_package_name

`nginx_version`

Data type: String[1]

The version of nginx installed (or being installed). Unfortunately, different versions of nginx may need configuring differently. The default is derived from the version of nginx already installed. If the fact is unavailable, it defaults to '1.6.0'. You may need to set this manually to get a working and idempotent configuration.

Default value: pick(fact('nginx_version'), '1.6.0')

`debug_connections`

Data type: Array[Nginx::DebugConnection]

Configures nginx debug_connection lines in the events section of the nginx config. See http://nginx.org/en/docs/ngx_core_module.html#debug_connection

Default value: []

`service_config_check`

Data type: Boolean

whether to en- or disable the config check via nginx -t on config changes

Default value: false

`service_config_check_command`

Data type: String

Command to execute to validate the generated configuration.

Default value: 'nginx -t'

`reset_timedout_connection`

`nginx_upstreams`

Data type: Hash

Default value: {}

`nginx_upstreams_defaults`

Data type: Nginx::UpstreamDefaults

Default value: {}

`purge_passenger_repo`

Data type: Boolean

Default value: true

Defined types

`nginx::resource::geo`

Create a new geo mapping entry for NGINX

Examples

Puppet usage

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

Hiera usage

nginx::geo_mappings:
  client_network:
    ensure: present
    ranges: false
    default: 'extra'
    proxy_recursive: false
    proxies:
       - 192.168.99.99
    networks:
      '10.0.0.0/8': 'intra'
      '172.16.0.0/12': 'intra'
      '192.168.0.0/16': 'intra'

Parameters

The following parameters are available in the nginx::resource::geo defined type.

Create a new location entry within a virtual host

Examples

Simple example

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

Use one location in multiple servers

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

Custom config example to limit location on localhost, create a hash with any extra custom config you want.

$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,
}

Add Custom fastcgi_params

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

Add Custom uwsgi_params

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

Enables or disables resetting timed out connections and connections closed with the non-standard code 444.

Default value: undef

`fastcgi_index`

Data type: Optional[String]

Default value: undef

`rewrite_rules`

Data type: Array

Default value: []

`nginx::resource::mailhost`

Define a mailhost

Examples

SMTP server definition

nginx::resource::mailhost { 'domain1.example':
  ensure      => present,
  auth_http   => 'server2.example/cgi-bin/auth',
  protocol    => 'smtp',
  listen_port => 587,
  ssl_port    => 465,
  starttls    => 'only',
  xclient     => 'off',
  ssl         => true,
  ssl_cert    => '/tmp/server.crt',
  ssl_key     => '/tmp/server.pem',
}

Parameters

The following parameters are available in the nginx::resource::mailhost defined type.

`ensure`

Data type: Enum['absent', 'present']

Enables or disables the specified mailhost

Default value: 'present'

`listen_ip`

Data type: Variant[Array[String], String]

Default IP Address for NGINX to listen with this server on. Defaults to all interfaces (*)

Default value: '*'

Data type: Optional[Hash]

It expects a hash with custom directives to put after everything else inside server

Default value: undef

`mailhost_cfg_prepend`

Data type: Optional[Hash]

It expects a hash with custom directives to put before everything else inside server

Default value: undef

`auth_http_header`

Data type: Optional[String]

Default value: undef

`nginx::resource::map`

Create a new mapping entry for NGINX

Examples

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',
  }
}

Preserving input of order of mappings

nginx::resource::map { 'backend_pool':
  ...
  mappings  => [
    { 'key' => '*.sf.example.com', 'value' => 'sf-pool-1' },
    { 'key' => '*.nyc.example.com', 'value' => 'ny-pool-1' },
  ]
}

Using external include

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

Hiera usage

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'

Hiera usage: preserving input of order of mappings:

nginx::string_mappings:
  client_network:
    ...
    mappings:
      - key: '*.sf.example.com'
        value: 'sf-pool-1'
      - key: '*.nyc.example.com'
        value: 'ny-pool-1'

Parameters

The following parameters are available in the nginx::resource::map defined type.

`ensure`

Data type: Enum['absent', 'present']

Enables or disables the specified location

Default value: 'present'

`default`

Data type: Optional[String]

Sets the resulting value if the source values fails to match any of the variants.

Default value: undef

`string`

Data type: String[2]

Source string or variable to provide mapping for

`mappings`

Data type: Variant[Array, Hash]

Hash of map lookup keys and resultant values

`hostnames`

Data type: Boolean

Indicates that source values can be hostnames with a prefix or suffix mask.

Default value: false

`include_files`

Data type: Array[String]

An array of external files to include

Default value: []

`context`

Data type: Enum['http', 'stream']

Specify if mapping is for http or stream context

Default value: 'http'

`nginx::resource::server`

Create a virtual host

Examples

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',
}

`geo_mappings`

Data type: Any

Default value: {}

`nginx::resource::snippet`

Create a reusable config snippet that can be included by other resources

Parameters

The following parameters are available in the nginx::resource::snippet defined type.

`ensure`

Data type: Enum['absent', 'present']

Enables or disables the specified snippet

Default value: 'present'

`owner`

Data type: String

Defines owner of the .conf file

Default value: $nginx::global_owner

`group`

Data type: String

Defines group of the .conf file

Default value: $nginx::global_group

`mode`

Data type: Stdlib::Filemode

Defines mode of the .conf file

Default value: $nginx::global_mode

`raw_content`

Data type: String[1]

Raw content that will be inserted into the snipped as-is

`nginx::resource::streamhost`

Create a virtual steamhost

Examples

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

Parameters

The following parameters are available in the nginx::resource::streamhost defined type.

`ensure`

Data type: Enum['absent', 'present']

Enables or disables the specified streamhost

Default value: 'present'

`listen_ip`

Data type: Variant[Array, String]

Default IP Address for NGINX to listen with this streamhost on. Defaults to all interfaces (*)

Default value: '*'

`listen_port`

Data type: Integer

Default TCP Port for NGINX to listen with this streamhost on.

Default value: 80

`listen_options`

Data type: Optional[String]

Extra options for listen directive like 'default' to catchall.

Default value: undef

`ipv6_enable`

Data type: Boolean

Value to enable/disable IPv6 support Module will check to see if IPv6 support exists on your system before enabling.

Default value: false

`ipv6_listen_ip`

Data type: Variant[Array, String]

Default IPv6 Address for NGINX to listen with this streamhost on. Defaults to all interfaces (::)

Default value: '::'

`ipv6_listen_port`

Data type: Integer

Default IPv6 Port for NGINX to listen with this streamhost on.

Default value: $listen_port

`ipv6_listen_options`

Data type: String

Extra options for listen directive like 'default' to catchall. Template will allways add ipv6only=on. While issue voxpupuli#30 is discussed, default value is 'default'.

Default value: 'default ipv6only=on'

`proxy`

Data type: Any

Proxy server(s) for the root location to connect to. Accepts a single value, can be used in conjunction with nginx::resource::upstream

Default value: undef

`proxy_read_timeout`

Data type: String

Override the default the proxy read timeout value of 90 seconds

Default value: $nginx::proxy_read_timeout

`resolver`

Data type: Array

Configures name servers used to resolve names of upstream servers into addresses.

Default value: []

`raw_prepend`

Data type: Variant[Array[String], String]

A single string, or an array of strings to prepend to the server directive (after cfg prepend directives). NOTE: YOU are responsible for a semicolon on each line that requires one.

Default value: []

`raw_append`

Data type: Variant[Array[String], String]

A single string, or an array of strings to append to the server directive (after cfg append directives). NOTE: YOU are responsible for a semicolon on each line that requires one.

Default value: []

`owner`

Data type: String

Defines owner of the .conf file

Default value: $nginx::global_owner

`group`

Data type: String

Defines group of the .conf file

Default value: $nginx::global_group

`mode`

Data type: String

Defines mode of the .conf file Default to return 503

Default value: $nginx::global_mode

`proxy_connect_timeout`

Data type: Any

Default value: $nginx::proxy_connect_timeout

`nginx::resource::upstream`

Create a new upstream proxy entry for NGINX

Examples

nginx::resource::upstream { 'proxypass':
  ensure  => present,
  members => {
    'localhost:3001' => {
      server => 'localhost',
      port   => 3001,
    },
    'localhost:3002' => {
      server => 'localhost',
      port   => 3002,
    },
    'localhost:3003' => {
      server => 'localhost',
      port   => 3003,
    },
  },
}

Custom config example to use ip_hash, and 20 keepalive connections create a hash with any extra custom config you want.

nginx::resource::upstream { 'proxypass':
  ensure    => present,
  members   => {
    'localhost:3001' => {
      server => 'localhost',
      port   => 3001,
    },
    'localhost:3002' => {
      server => 'localhost',
      port   => 3002,
    },
    'localhost:3003' => {
      server => 'localhost',
      port   => 3003,
    },
  },
  ip_hash   => true,
  keepalive => 20,
}

Examples

Exporting the resource on a upstream member server:

@@nginx::resource::upstream::member { $trusted['certname']:
  ensure   => present,
  upstream => 'proxypass',
  server   => $facts['networking']['ip'],
  port     => 3000,
}

Collecting the resource on the NGINX server:

nginx::resource::upstream { 'proxypass':
  ensure => present,
}

Parameters

The following parameters are available in the nginx::resource::upstream::member defined type.

`Nginx::DebugConnection`

The Nginx::DebugConnection data type.

Alias of Variant[Stdlib::Host, Stdlib::IP::Address, Enum['unix:']]

`Nginx::ErrorLogSeverity`

The Nginx::ErrorLogSeverity data type.

Alias of Enum['debug', 'info', 'notice', 'warn', 'error', 'crit', 'alert', 'emerg']

`Nginx::Size`

The Nginx::Size data type.

Alias of Pattern[/^\d+[k|K|m|M]?$/]

`Nginx::Time`

The Nginx::Time data type.

Alias of Pattern[/^\d+(ms|s|m|h|d|w|M|y)?$/]

`Nginx::UpstreamCustomParameters`

The Nginx::UpstreamCustomParameters data type.

Alias of Hash[String[1], Variant[ String[1], Integer, Array[ Variant[ String[1], Integer ] ], Hash[String[1], Variant[ String[1], Integer, Array[ Variant[ String[1], Integer, ] ] ] ] ]]

`Nginx::UpstreamDefaults`

The Nginx::UpstreamDefaults data type.

Alias of Struct[{ context => Optional[Enum['http', 'stream']], member_defaults => Optional[Nginx::UpstreamMemberDefaults], hash => Optional[String], ip_hash => Optional[Boolean], keepalive => Optional[Integer[1]], kepalive_requests => Optional[Integer[1]], keepalive_timeout => Optional[Nginx::Time], least_conn => Optional[Boolean], least_time => Optional[Nginx::UpstreamLeastTime], ntlm => Optional[Boolean], queue_max => Optional[Integer], queue_timeout => Optional[Nginx::Time], random => Optional[String], statefile => Optional[Stdlib::Unixpath], sticky => Optional[Nginx::UpstreamSticky], zone => Optional[Nginx::UpstreamZone], cfg_append => Optional[Hash], cfg_prepend => Optional[Hash], }]

`Nginx::UpstreamLeastTime`

The Nginx::UpstreamLeastTime data type.

Alias of Variant[Nginx::UpstreamLeastTimeHttp, Nginx::UpstreamLeastTimeStream]

`Nginx::UpstreamLeastTimeHttp`

The Nginx::UpstreamLeastTimeHttp data type.

Alias of Enum['header', 'header inflight', 'last_byte', 'last_byte inflight']

`Nginx::UpstreamLeastTimeStream`

The Nginx::UpstreamLeastTimeStream data type.

Alias of Enum['connect', 'connect inflight', 'first_byte', 'first_byte inflight', 'last_byte', 'last_byte inflight']

`Nginx::UpstreamMember`

The Nginx::UpstreamMember data type.

Alias of Struct[{ server => Optional[Nginx::UpstreamMemberServer], port => Optional[Stdlib::Port], weight => Optional[Integer[1]], max_conns => Optional[Integer[1]], max_fails => Optional[Integer[0]], fail_timeout => Optional[Nginx::Time], backup => Optional[Boolean], resolve => Optional[Boolean], route => Optional[String], service => Optional[String], slow_start => Optional[Nginx::Time], state => Optional[Enum['drain','down']], params_prepend => Optional[String], params_append => Optional[String], comment => Optional[String], }]

`Nginx::UpstreamMemberDefaults`

The Nginx::UpstreamMemberDefaults data type.

Alias of Struct[{ server => Optional[Nginx::UpstreamMemberServer], port => Optional[Stdlib::Port], weight => Optional[Integer[1]], max_conns => Optional[Integer[1]], max_fails => Optional[Integer[0]], fail_timeout => Optional[Nginx::Time], backup => Optional[Boolean], resolve => Optional[Boolean], route => Optional[String], service => Optional[String], slow_start => Optional[Nginx::Time], state => Optional[Enum['drain','down']], params_prepend => Optional[String], params_append => Optional[String], }]

`Nginx::UpstreamMemberServer`

The Nginx::UpstreamMemberServer data type.

Alias of Variant[Stdlib::Host, Pattern[/^unix:\/([^\/\0]+\/*)[^:]*$/]]

`Nginx::UpstreamMembers`

The Nginx::UpstreamMembers data type.

Alias of Hash[String, Nginx::UpstreamMember]

`Nginx::UpstreamSticky`

The Nginx::UpstreamSticky data type.

Alias of Variant[Hash[ Enum['cookie'], Struct[{ name => String, expires => Optional[Variant[Nginx::Time,Enum['max']]], domain => Optional[String], httponly => Optional[Boolean], secure => Optional[Boolean], path => Optional[String], }] ], Hash[ Enum['route'], String ], Hash[ Enum['learn'], Struct[{ create => String, lookup => String, zone => Nginx::UpstreamStickyZone, timeout => Optional[Nginx::Time], header => Optional[Boolean], sync => Optional[Boolean], }] ]]

`Nginx::UpstreamStickyZone`

The Nginx::UpstreamStickyZone data type.

Alias of Pattern[/^[-_\.A-Za-z0-9]*:\d+[k|K|m|M]$/]

`Nginx::UpstreamZone`

The Nginx::UpstreamZone data type.

Alias of Pattern[/^[-_\.A-Za-z0-9]* \d+[k|K|m|M]$/]

Files

REFERENCE.md

Latest commit

History

REFERENCE.md

File metadata and controls

Reference

Table of Contents

Classes

Public Classes

Private Classes

Defined types

Data types

Classes

nginx

Examples

Use the sensible defaults

Parameters

include_modules_enabled

passenger_package_name

nginx_version

debug_connections

service_config_check

service_config_check_command

reset_timedout_connection

client_body_temp_path

confd_only

confd_purge

conf_dir

daemon

daemon_user

daemon_group

dynamic_modules

global_owner

global_group

global_mode

limit_req_zone

log_dir

log_user

log_group

log_mode

http_access_log

http_format_log

nginx_error_log

nginx_error_log_severity

pid

proxy_temp_path

root_group

run_dir

sites_available_owner

sites_available_group

sites_available_mode

super_user

temp_dir

server_purge

conf_template

fastcgi_conf_template

uwsgi_params_template

absolute_redirect

accept_mutex

accept_mutex_delay

client_body_buffer_size

client_max_body_size

client_body_timeout

send_timeout

lingering_timeout

lingering_close

lingering_time

etag

events_use

fastcgi_cache_inactive

fastcgi_cache_key

fastcgi_cache_keys_zone

fastcgi_cache_levels

fastcgi_cache_max_size

fastcgi_cache_path

fastcgi_cache_use_stale

gzip

gzip_buffers

gzip_comp_level

`nginx`

`include_modules_enabled`

`passenger_package_name`

`nginx_version`

`debug_connections`

`service_config_check`

`service_config_check_command`

`reset_timedout_connection`

`client_body_temp_path`

`confd_only`

`confd_purge`

`conf_dir`

`daemon`

`daemon_user`

`daemon_group`

`dynamic_modules`

`global_owner`

`global_group`

`global_mode`

`limit_req_zone`

`log_dir`

`log_user`

`log_group`

`log_mode`

`http_access_log`

`http_format_log`

`nginx_error_log`

`nginx_error_log_severity`

`pid`

`proxy_temp_path`

`root_group`

`run_dir`

`sites_available_owner`

`sites_available_group`

`sites_available_mode`

`super_user`

`temp_dir`

`server_purge`

`conf_template`

`fastcgi_conf_template`

`uwsgi_params_template`

`absolute_redirect`

`accept_mutex`

`accept_mutex_delay`

`client_body_buffer_size`

`client_max_body_size`

`client_body_timeout`

`send_timeout`

`lingering_timeout`

`lingering_close`

`lingering_time`

`etag`

`events_use`

`fastcgi_cache_inactive`

`fastcgi_cache_key`

`fastcgi_cache_keys_zone`

`fastcgi_cache_levels`

`fastcgi_cache_max_size`

`fastcgi_cache_path`

`fastcgi_cache_use_stale`

`gzip`

`gzip_buffers`

`gzip_comp_level`

`gzip_disable`

`gzip_min_length`

`gzip_http_version`

`gzip_proxied`

`gzip_types`

`gzip_vary`

`gzip_static`

`http_cfg_prepend`

`http_cfg_append`

`http_raw_prepend`

`http_raw_append`

`http_tcp_nodelay`

`http_tcp_nopush`

`keepalive_timeout`

`keepalive_requests`

`log_format`

`mail`