Skip to content

Latest commit

 

History

History
1770 lines (990 loc) · 42.3 KB

REFERENCE.md

File metadata and controls

1770 lines (990 loc) · 42.3 KB
Raw

Reference

Table of Contents

Classes

Public Classes

Private Classes

  • varnish::service: Manages the Varnish service

Defined types

Public Defined types

Private Defined types

  • varnish::vcl::includefile: Used by vcl.pp to create the config files with header sections

Data types

Classes

varnish

Installs and configures Varnish.

Examples

Installs Varnish
# enables Varnish service
# uses default VCL '/etc/varnish/default.vcl'
include varnish
Installs Varnish with custom options
# sets Varnish to listen on port 80
# storage size is set to 2 GB
# vcl file is '/etc/varnish/my-vcl.vcl'
class { 'varnish':
  varnish_listen_port  => 80,
  varnish_storage_size => '2G',
  varnish_vcl_conf     => '/etc/varnish/my-vcl.vcl',
}

Parameters

The following parameters are available in the varnish class:

service_ensure

Data type: Stdlib::Ensure::Service

Ensure for varnishservice

Default value: 'running'

service_enable

Data type: Boolean

If Service should be enabled

Default value: true

reload_vcl

Data type: Boolean

V4 paramter if Varnish will be reloaded - deprecated Will be removed when support for RHEL7 is dropped

Default value: true

nfiles

Data type: String

passed to varnish conf-file

Default value: '131072'

memlock

Data type: String

passed to varnish conf-file

Default value: '100M'

storage_type

Data type: String

which storage will be used for varnish - default malloc

Default value: 'malloc'

varnish_vcl_conf

Data type: Stdlib::Absolutepath

path to main vcl file

Default value: '/etc/varnish/default.vcl'

varnish_user

Data type: String

passed to varnish-conf

Default value: 'varnish'

varnish_jail_user

Data type: Optional[String]

passed to varnish-conf

Default value: undef

varnish_group

Data type: String

passed to varnish-conf

Default value: 'varnish'

varnish_listen_address

Data type: Optional[String[1]]

Address varnish will bind to - default ''

Default value: undef

varnish_listen_port

Data type: Stdlib::Port

port varnish wil bind to

Default value: 6081

varnish_proxy_listen_address

Data type: String

address varnish binds to in proxy mode

Default value: '127.0.0.1'

varnish_proxy_listen_port

Data type: Optional[Stdlib::Port]

port varnish binds to in proxy mode

Default value: undef

varnish_proxy_listen_socket

Data type: Optional[Stdlib::Absolutepath]

socket varnish binds to in proxy mode

Default value: undef

varnish_proxy_listen_socket_mode

Data type: Stdlib::Filemode

Filemode for socket varnish binds to in proxy mode

Default value: '666'

varnish_admin_listen_address

Data type: String

address varnish binds to in admin mode

Default value: 'localhost'

varnish_admin_listen_port

Data type: Stdlib::Port

port varnish binds to in admin mode

Default value: 6082

varnish_min_threads

Data type: String

minumum no of varnish worker threads

Default value: '5'

varnish_max_threads

Data type: String

maximum no of varnish worker threads

Default value: '500'

varnish_thread_timeout

Data type: String

Default value: '300'

varnish_storage_size

Data type: String

defines the size of storage (depending of storage_type)

Default value: '1G'

varnish_secret_file

Data type: Stdlib::Absolutepath

path to varnish secret file

Default value: '/etc/varnish/secret'

varnish_storage_file

Data type: Stdlib::Absolutepath

defines the filepath of storage (depending of storage_type)

Default value: '/var/lib/varnish-storage/varnish_storage.bin'

mse_config

Data type: Optional[String[1]]

MSE Config, see https://docs.varnish-software.com/varnish-cache-plus/features/mse/

Default value: undef

mse_config_file

Data type: Stdlib::Absolutepath

filepath where mse config file will be stored

Default value: '/etc/varnish/mse.conf'

varnish_ttl

Data type: String

default ttl for items

Default value: '120'

varnish_enterprise

Data type: Boolean

passed to varnish::install

Default value: false

varnish_enterprise_vmods_extra

Data type: Boolean

passed to varnish::install

Default value: false

vcl_dir

Data type: Optional[Stdlib::Absolutepath]

dir where varnish vcl will be stored

Default value: undef

shmlog_dir

Data type: Stdlib::Absolutepath

location for shmlog

Default value: '/var/lib/varnish'

shmlog_tempfs

Data type: Boolean

mounts shmlog directory as tmpfs

Default value: true

version

Data type: String[1]

passed to puppet type 'package', attribute 'ensure'

Default value: present

add_repo

Data type: Boolean

if set to false (defaults to true), the yum/apt repo is not added

Default value: false

manage_firewall

Data type: Boolean

passed to varnish::firewall

Default value: false

varnish_conf_template

Data type: String[1]

Template that will be used for varnish conf

Default value: 'varnish/varnish-conf.erb'

conf_file_path

Data type: Stdlib::Absolutepath

path where varnish conf will be stored

Default value: '/etc/varnish/varnish.params'

additional_parameters

Data type: Hash

additional parameters that will be passed to varnishd with -p

Default value: {}

default_version

Data type: Integer

Default major version of Varnish for that OS release

Default value: 6

add_hitch

Data type: Boolean

Add varnish::hitch class to install hitch

Default value: false

add_ncsa

Data type: Boolean

Add varnish::ncsa class to install varnishncsa Service

Default value: false

varnish::controller::agent

Installs and manages Varnish Controller Agent

Examples

include varnish::controller::agent

Parameters

The following parameters are available in the varnish::controller::agent class:

base_url

Data type: Stdlib::HTTPUrl

see https://docs.varnish-software.com/varnish-controller/installation/agents/#base-url

nats_server

Data type: Stdlib::Host

Server for NATS Connection

nats_server_port

Data type: Stdlib::Port

Port for Nats Connection

Default value: 4222

nats_server_user

Data type: Optional[String]

User for Nats Connection

Default value: undef

nats_server_password

Data type: Optional[Variant[Sensitive[String],String]]

Password for Nats Connection

Default value: undef

agent_name

Data type: Varnish::Controller::Agent_name

see https://docs.varnish-software.com/varnish-controller/installation/agents/#setting-the-agent-name

Default value: $facts['networking']['hostname']

invalidation_host

Data type: String[1]

see https://docs.varnish-software.com/varnish-controller/installation/agents/#varnish-interaction

Default value: '127.0.0.1:80'

package_name

Data type: String[1]

Name of the Package used for installation

Default value: 'varnish-controller-agent'

package_ensure

Data type: String[1]

Ensure of the Package

Default value: 'present'

service_ensure

Data type: Stdlib::Ensure::Service

Ensure of Agent Service

Default value: 'running'

varnish::firewall

Uses puppetlabs/firewall module to open varnish listen port

Parameters

The following parameters are available in the varnish::firewall class:

manage_firewall

Data type: Boolean

Manage firewall

Default value: false

varnish_listen_port

Data type: Stdlib::Port

Port where varnish listens to

Default value: 6081

varnish::hitch

Installs Hitch the SSL Offloading Proxy of Varnish Enterprise

Examples

include varnish::hitch

Parameters

The following parameters are available in the varnish::hitch class:

package_name

Data type: String[1]

Define used package name

Default value: 'varnish-plus-addon-ssl'

package_ensure

Data type: String[1]

Ensure package

Default value: 'present'

service_ensure

Data type: Stdlib::Ensure::Service

Ensure Service status

Default value: 'running'

service_name

Data type: String[1]

Service name for hitch (must match installed)

Default value: 'hitch'

config_path

Data type: Stdlib::Absolutepath

Path for hitch config

Default value: '/etc/hitch/hitch.conf'

config_template

Data type: String[1]

Used EPP Config template

Default value: 'varnish/hitch.conf.epp'

frontends

Data type: Array[Struct[{ host => String[1],port => Stdlib::Port }],1]

Define Frontends for hitch

Default value: [{ 'host'=> '*', 'port'=> 443, }]

backend

Data type: String[1]

Define Backend

Default value: '[127.0.0.1]:8443'

pem_files

Data type: Array[Stdlib::Absolutepath,1]

PEM Files that will be loaded

ssl_engine

Data type: Optional[String[1]]

Set the ssl-engine

Default value: undef

tls_protos

Data type: String[1]

allowed TLS Protos

Default value: 'TLSv1.2 TLSv1.3'

ciphers

Data type: String[1]

allowed ciphers

Default value: 'EECDH+AESGCM:EDH+AESGCM'

ciphersuites

Data type: String[1]

allowd cipersuites for TLS1.3+

Default value: 'TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256'

workers

Data type: Variant[Enum['auto'],Integer[1,1024]]

number of workers

Default value: 'auto'

backlog

Data type: Integer[1]

Listen backlog size

Default value: 200

keepalive

Data type: Integer[1]

Number of seconds a TCP socket is kept alive

Default value: 3600

chroot

Data type: Optional[Stdlib::Absolutepath]

Chroot directory

Default value: undef

user

Data type: String[1]

User to run as. If Hitch is started as root, it will insist on changing to a user with lower rights after binding to sockets.

Default value: 'hitch'

group

Data type: String[1]

If given, Hitch will change to this group after binding to listen sockets.

Default value: 'hitch'

log_level

Data type: Integer[0,2]

Log chattiness. 0=silence, 1=errors, 2=info/debug. This setting can also be changed at run-time by editing the configuration file followed by a reload (SIGHUP).

Default value: 1

syslog

Data type: Boolean

Send messages to syslog.

Default value: true

syslog_facility

Data type: Stdlib::Syslogfacility

Set the syslog facility.

Default value: 'daemon'

daemon

Data type: Boolean

Run as daemon

Default value: true

write_proxy

Data type: Enum['ip','v1','v2','proxy']

Which Proxy mode is used

Default value: 'v2'

sni_nomatch_abort

Data type: Boolean

Abort handshake when the client submits an unrecognized SNI server name.

Default value: false

tcp_fastopen

Data type: Boolean

Enable TCP Fast Open.

Default value: false

alpn_protos

Data type: String[1]

Comma separated list of protocols supported by the backend

Default value: 'h2,http/1.1'

additional_parameters

Data type: Hash[String[1],Variant[String[1],Integer[1]]]

Add parameters additional as needed

Default value: {}

varnish::install

Installs Varnish

Examples

Install Varnish
include 'varnish::install'
Make sure latest version is always installed
class { 'varnish::install':
 version => latest,
}

Parameters

The following parameters are available in the varnish::install class:

add_repo

Data type: Boolean

if repo should be added

Default value: true

manage_firewall

Data type: Boolean

if firewall should be managed

Default value: false

varnish_listen_port

Data type: Stdlib::Port

port that varnish should listen to

Default value: 6081

package_name

Data type: Optional[String]

manually define package name for installation

Default value: undef

varnish_enterprise

Data type: Boolean

If varnish enterprise packages should be installed

Default value: false

varnish_enterprise_vmods_extra

Data type: Boolean

if varnish enterprise extra vmods should also be installed

Default value: false

version

Data type: String

passed to puppet type 'package', attribute 'ensure'

Default value: 'present'

varnish::ncsa

Allows setup of varnishncsa

Parameters

The following parameters are available in the varnish::ncsa class:

enable

Data type: Boolean

enable service

Default value: true

service_ensure

Data type: Stdlib::Ensure::Service

ensure serice

Default value: 'running'

varnishncsa_daemon_opts

Data type: String

Options handed to varnishncsa

Default value: '-a -w /var/log/varnish/varnishncsa.log -D -P /run/varnishncsa/varnishncsa.pid'

varnish::repo

This class installs aditional repos for varnish

Parameters

The following parameters are available in the varnish::repo class:

version

Data type: Optional[String]

Version of varnish for repo

Default value: undef

enable

Data type: Boolean

If repo will be managed

Default value: false

varnish::shmlog

Mounts shmlog as tempfs

Examples

Disable config for mounting shmlog as tmpfs
class { 'varnish::shmlog':
  tempfs => false,
}

Parameters

The following parameters are available in the varnish::shmlog class:

shmlog_dir

Data type: Stdlib::Absolutepath

directory where Varnish logs

Default value: '/var/lib/varnish'

tempfs

Data type: Boolean

mount or not shmlog as tmpfs, boolean

Default value: true

size

Data type: String

size definition of shmlog tmpfs

Default value: '170M'

varnish::vcl

To change name/location of vcl file, use $varnish_vcl_conf in the main varnish class

NOTE: though you can pass config for backends, directors, acls, probes and selectors as parameters to this class, it is recommended to use existing definitions instead: varnish::backend varnish::director varnish::probe varnish::acl varnish::selector See README for details on how to use those

  • Note VCL applies following restictions:
  • if you define an acl it must be used
  • if you define a probe it must be used
  • if you define a backend it must be used
  • if you define a director it must be used You cannot define 2 or more backends/directors and not to have selectors Not following above rules will result in VCL compilation failure

Parameters

The following parameters are available in the varnish::vcl class:

functions

Data type: Hash

Hash of additional function definitions

Default value: {}

probes

Data type: Hash

Hash of probes, defined as varnish::vcl::probe

Default value: {}

backends

Data type: Hash

Hash of backends, defined as varnish::vcl::backend

Default value: { 'default' => { host => '127.0.0.1', port => 8080 } }

directors

Data type: Hash

Hash of directors, defined as varnish::vcl::director

Default value: {}

selectors

Data type: Hash

Hash of selectors, defined as varnish::vcl::selector

Default value: {}

acls

Data type: Hash

Hash of acls, defined as varnish::vcl::acl

Default value: {}

blockedips

Data type: Array

Array of IP's that will be blocked with default VCL

Default value: []

blockedbots

Data type: Array

Array of UserAgent Bots that will be blocked

Default value: []

enable_waf

Data type: Boolean

controls VCL WAF component, can be true or false

Default value: false

pipe_uploads

Data type: Boolean

If the request is a post/put upload (chunked or multipart), pipe the request to the backend.

Default value: false

wafexceptions

Data type: Array[String]

Exclude those rules

Default value: ['57' , '56' , '34']

purgeips

Data type: Array[Stdlib::IP::Address]

source ips which are allowed to send purge requests

Default value: []

includedir

Data type: Stdlib::Absolutepath

Dir for includefiles

Default value: '/etc/varnish/includes'

manage_includes

Data type: Boolean

If Includes (and Subtypes like directors, probes,.. ) should be created

Default value: true

cookiekeeps

Data type: Array[String]

Cookies that should be kept for backend

Default value: ['__ac', '_ZopeId', 'captchasessionid', 'statusmessages', '__cp', 'MoodleSession']

defaultgrace

Data type: Optional[String]

Default Grace time for Iptems

Default value: undef

min_cache_time

Data type: String

Default Cache time

Default value: '60s'

static_cache_time

Data type: String

Cache Time for static Elements like images,..

Default value: '5m'

gziptypes

Data type: Array[String]

Content Types that will be gziped

Default value: ['text/', 'application/xml', 'application/rss', 'application/xhtml', 'application/javascript', 'application/x-javascript']

template

Data type: Optional[String]

Overwrite Template for VCL

Default value: undef

logrealip

Data type: Boolean

Create std.log entry with Real IP of client

Default value: false

honor_backend_ttl

Data type: Boolean

if Backend TTL will be honored

Default value: false

cond_requests

Data type: Boolean

if condtional requests are allowed

Default value: false

x_forwarded_proto

Data type: Boolean

If Header x-forwared-proto should be added to hash

Default value: false

https_redirect

Data type: Boolean

deprecated

Default value: false

drop_stat_cookies

Data type: Boolean

depretaced

Default value: true

cond_unset_cookies

Data type: Optional[String]

If condtion to unset all coockies

Default value: undef

unset_headers

Data type: Array[String]

Unset the named http headers

Default value: ['Via','X-Powered-By','X-Varnish','Server','Age','X-Cache']

unset_headers_debugips

Data type: Array[Stdlib::IP::Address]

Do not unset the named headers for the following IP's

Default value: ['172.0.0.1']

vcl_version

Data type: Varnish::Vclversion

Which version von VCL should be used

Default value: '4'

Defined types

varnish::vcl::acl

Defines an ACL Type of Varnish. Defined ACL's must be used in VCL

Parameters

The following parameters are available in the varnish::vcl::acl defined type:

acl_name

Data type: Varnish::VCL::Ressource

Name of ACL

Default value: $title

hosts

Data type: Array[Stdlib::IP::Address]

Array of defined Hosts

varnish::vcl::acl_member

The varnish::vcl::acl_member class.

Parameters

The following parameters are available in the varnish::vcl::acl_member defined type:

varnish_fqdn

Data type: String[1]

Tag name of the varnish host that is collected

acl

Data type: Varnish::VCL::Ressource

Name of the ACL that should be created

host

Data type: Stdlib::IP::Address

Host ip that will be inserted

varnish::vcl::backend

Defines a Backend for VCL

Parameters

The following parameters are available in the varnish::vcl::backend defined type:

host

Data type: Stdlib::Host

Host that will be defined as backend

port

Data type: Stdlib::Port

Port of the backend host

backend_name

Data type: Varnish::VCL::Ressource

The actual backend name

Default value: $title

probe

Data type: Optional[String]

Name of probe that will be used for healthcheck

Default value: undef

connect_timeout

Data type: Optional[Variant[String[1],Integer]]

define varnish connect connect_timeout

Default value: undef

first_byte_timeout

Data type: Optional[Variant[String[1],Integer]]

define varnish first_byte_timeout

Default value: undef

between_bytes_timeout

Data type: Optional[Variant[String[1],Integer]]

define varnish between_bytes_timeout

Default value: undef

max_connections

Data type: Optional[Integer]

define varnish maximum number of connections to the backend

Default value: undef

ssl

Data type: Optional[Integer[0,1]]

varnish-plus: Set this true (1) to enable SSL/TLS for this backend.

Default value: undef

ssl_sni

Data type: Optional[Integer[0,1]]

varnish-plus: Set this to false (0) to disable the use of the Server Name Indication (SNI) extension for backend TLS connections

Default value: undef

ssl_verify_peer

Data type: Optional[Integer[0,1]]

varnish-plus: Set this to false (0) to disable verification of the peer’s certificate chain.

Default value: undef

ssl_verify_host

Data type: Optional[Integer[0,1]]

varnish-plus: Set this to true (1) to enable verification of the peer’s certificate identity

Default value: undef

host_header

Data type: Optional[String[1]]

varnish-plus: A host header to add to probes and regular backend requests if they have no such header

Default value: undef

certificate

Data type: Optional[String[1]]

varnish-plus: Specifies a client certificate to be used

Default value: undef

varnish::vcl::director

Defines a backend director in varnish vcl

Parameters

The following parameters are available in the varnish::vcl::director defined type:

director_name

Data type: Varnish::VCL::Ressource

Name of the director

Default value: $title

type

Data type: String

Type of varnish backend director

Default value: 'round-robin'

backends

Data type: Array[String]

Array of backends for the director, backends need to be defined as varnish::vcl:backend

Default value: []

vcl_version

Data type: Varnish::Vclversion

Version of vcl Language

Default value: $varnish::vcl::vcl_version

varnish::vcl::probe

Defined probes must be used

Parameters

The following parameters are available in the varnish::vcl::probe defined type:

probe_name

Data type: Varnish::VCL::Ressource

Name of the probe

Default value: $title

interval

Data type: String

Paramter as defined from varnish

Default value: '5s'

timeout

Data type: String

Paramter as defined from varnish

Default value: '5s'

threshold

Data type: String

Paramter as defined from varnish

Default value: '3'

window

Data type: String

Paramter as defined from varnish

Default value: '8'

expected_response

Data type: String

The expected HTTP status, defaults to '200'

Default value: '200'

includedir

Data type: String

Directory where includefiles will be created

Default value: $varnish::vcl::includedir

url

Data type: Optional[String]

Paramter as defined from varnish

Default value: undef

request

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

Paramter as defined from varnish

Default value: undef

varnish::vcl::selector

Depending on the condition, requests will be sent to the correct backend

Parameters

The following parameters are available in the varnish::vcl::selector defined type:

condition

Data type: String

Condtion under that varnish will redirect to the defined backend Must be valid VCL if conditon

director

Data type: String

Director that will be used for the requests

Default value: $name

rewrite

Data type: Optional[String]

Rewrite Header X-Host to this value

Default value: undef

newurl

Data type: Optional[String]

rewrite URL to this URL

Default value: undef

movedto

Data type: Optional[String]

Instead of backend, sent redirect to this Baseurl

Default value: undef

order

Data type: Variant[String, Integer]

Order value for selector statements

Default value: '03'

includedir

Data type: Stdlib::Absolutepath

Directory for include files

Default value: $varnish::vcl::includedir

vcl_version

Data type: Varnish::Vclversion

Version of VCL Language

Default value: $varnish::vcl::vcl_version

Data types

Varnish::Controller::Agent_name

Type for supported Agent Name of Controller Agent

Alias of Pattern[/\A(?i:([-a-z0-9]+))\z/]

Varnish::Vcl::Ressource

Type for supported VCL Versions

Alias of Pattern[/^[A-Za-z0-9_]+$/]

Varnish::Vclversion

Type for supported VCL Versions

Alias of Pattern[/\A(?i:(4))\z/]