Puppet module for Squid

Description

Puppet module for configuring the squid caching service.

Usage

The set up a simple squid server with a cache to forward http port 80 requests.

class { 'squid': }
squid::acl { 'Safe_ports':
  type    => port,
  entries => ['80'],
}
squid::http_access { 'Safe_ports':
  action => allow,
}
squid::http_access{ '!Safe_ports':
  action => deny,
}

This module will set the SELINUX-context for the cache_dir and/or port, requires puppet-selinux

Parameters for squid Class

Parameters to the squid class almost map 1 to 1 to squid.conf parameters themselves.

• ensure_service The ensure value of the squid service, defaults to running.

• enable_service The enable value of the squid service, defaults to true.

• config Location of squid.conf file, defaults to /etc/squid/squid.conf.

• config_user user which owns the config file, default depends on $operatingsystem

• config_group group which owns the config file, default depends on $operatingsystem

• daemon_user user which runs the squid daemon, this is used for ownership of the cache directory, default depends on $operatingsystem

• daemon_group group which runs the squid daemon, this is used for ownership of the cache directory, default depends on $operatingsystem

• cache_mem defaults to 256 MB. cache_mem docs.

• cache_replacement_policy defaults to undef. cache_replacement_policy docs.

• memory_replacement_policy defaults to undef. memory_replacement_policy docs.

• memory_cache_shared defaults to undef. memory_cache_shared docs.

• maximum_object_size_in_memory defaults to 512 KB. maximum_object_size_in_memory docs

• url_rewrite_program defaults to undef url_rewrite_program_docs

• url_rewrite_children defaults to undef url_rewrite_children_docs

• url_rewrite_child_options defaults to undef url_rewrite_child_options_docs

• access_log defaults to daemon:/var/logs/squid/access.log squid. access_log docs

• coredump_dir defaults to undef. coredump_dir docs.

• error_directory defaults to undef. error_directory.

• err_page_stylesheet defaults to undef. err_page_stylesheet.

• package_name name of the squid package to manage, default depends on $operatingsystem

• package_ensure package status and/or version, default to present

• service_name name of the squid service to manage, default depends on $operatingsystem

• max_filedescriptors defaults to undef. max_filedescriptors docs.

• workers defaults to undef. workers docs.

• snmp_incoming_address defaults to undef. Can be set to an IP address to only listen for snmp requests on an individual interface. snmp_incoming_address.

• buffered_logs defaults to undef. buffered_logs docs.

• acls defaults to undef. If you pass in a hash of acl entries, they will be defined automatically. acl entries.

• visible_hostname defaults to undef. visible_hostname docs

• via defaults to undef. via docs

• httpd_suppress_version_string defaults to undef. httpd_suppress_version_string docs

• forwarded_for defaults to undef. supported values are "on", "off", "transparent", "delete", "truncate". forwarded_for docs

• http_access defaults to undef. If you pass in a hash of http_access entries, they will be defined automatically. http_access entries.

• http_ports defaults to undef. If you pass in a hash of http_port entries, they will be defined automatically. http_port entries.

• https_ports defaults to undef. If you pass in a hash of https_port entries, they will be defined automatically. https_port entries.

• icp_access defaults to undef. If you pass in a hash of icp_access entries, they will be defined automatically. icp_access entries.

• refresh_patterns defaults to undef. If you pass a hash of refresh_pattern entires, they will be defined automatically. refresh_pattern entries.

• snmp_ports defaults to undef. If you pass in a hash of snmp_port entries, they will be defined automatically. snmp_port entries.

• send_hit defaults to undef. If you pass in a hash of send_hit entries, they will be defined automatically. send_hit entries.

• cache_dirs defaults to undef. If you pass in a hash of cache_dir entries, they will be defined automatically. cache_dir entries.

• ssl_bump defaults to undef. If you pass in a hash of ssl_bump entries, they will be defined automatically. ssl_bump entries.

• sslproxy_cert_error defaults to undef. If you pass in a hash of sslproxy_cert_error entries, they will be defined automatically. sslproxy_cert_error entries.

• extra_config_sections defaults to empty hash. If you pass in a hash of extra_config_section resources, they will be defined automatically.

• service_restart defaults to undef. Overrides service resource restart command to be executed. It can be used to perform a soft reload of the squid service.

• squid_bin_path path to the squid binary, default depends on $operatingsystem

class { 'squid':
  cache_mem    => '512 MB',
  workers      => 3,
  coredump_dir => '/var/spool/squid',
}

class { 'squid':
  cache_mem                 => '512 MB',
  workers                   => 3,
  coredump_dir              => '/var/spool/squid',
  acls                      => { 'remote_urls' => {
                                   type    => 'url_regex',
                                   entries => ['http://example.org/path',
                                               'http://example.com/anotherpath'],
                                 },
                               },
  http_access               => { 'our_networks hosts' => { action => 'allow', }},
  http_ports                => { '10000' => { options => 'accel vhost', }},
  snmp_ports                => { '1000' => { process_number => 3, }},
  cache_dirs                => { '/data/' => { type => 'ufs', options => '15000 32 256 min-size=32769', process_number => 2 }},
  url_rewrite_program       => '/usr/bin/squidguard -c /etc/squidguard/squidguard.conf',
  url_rewrite_children      => 12,
  url_rewrite_child_options => startup=1,
}

The acls, http_access, http_ports, snmp_port, cache_dirs lines above are equivalent to their examples below.

Defined Type squid::acl

Defines acl entries for a squid server.

squid::acl { 'remote_urls':
   type    => 'url_regex',
   entries => ['http://example.org/path',
               'http://example.com/anotherpath'],
}

would result in a multi entry squid acl

acl remote_urls url_regex http://example.org/path
acl remote_urls url_regex http://example.com/anotherpath

These may be defined as a hash passed to ::squid

Parameters for Type squid::acl

• type The acltype of the acl, must be defined, e.g url_regex, urlpath_regex, port, ..
• aclname The name of acl, defaults to the title.
• entries An array of acl entries, multiple members results in multiple lines in squid.conf.
• order Each ACL has an order 05 by default this can be specified if order of ACL definition matters.

Defined Type squid::cache_dir

Defines cache_dir entries for a squid server.

squid::cache_dir { '/data':
  type           => 'ufs',
  options        => '15000 32 256 min-size=32769',
  process_number => 2,
}

Results in the squid configuration of

if ${processor} = 2
cache_dir ufs 15000 32 256 min-size=32769
endif

Parameters for Type squid::cache_dir

• type the type of cache, e.g ufs. defaults to ufs.
• path defaults to the namevar, file path to cache.
• options String of options for the cache. Defaults to empty string.
• process_number if specfied as an integer the cache will be wrapped in a if $proceess_number statement so the cache will be used by only one process. Default is undef.
• manage_dir Boolean value, if true puppet will attempt to create the directory, if false you will have to create it yourself. Make sure the directory has the correct owner, group and mode. Defaults to true.

Defined Type squid::cache

Defines cache entries for a squid server.

squid::cache { 'our_network_hosts_acl':
  action    => 'deny',
  comment   => 'Our networks hosts are denied for caching',
}

Adds a squid.conf line

# Our networks hosts denied for caching
cache deny our_network_hosts_acl

Defined Type squid::http_access

Defines http_access entries for a squid server.

squid::http_access { 'our_networks hosts':
  action => 'allow',
}

Adds a squid.conf line

# http_access fragment for out_networks hosts
http_access allow our_networks hosts

squid::http_access { 'our_networks hosts':
  action    => 'allow',
  comment   => 'Our networks hosts are allowed',
}

Adds a squid.conf line

# Our networks hosts are allowed
http_access allow our_networks hosts

Define Type squid::send_hit

Defines send_hit for a squid server.

squid:::send_hit{'PragmaNoCache':
  action => 'deny',
}

Adds a squid.conf line

send_hit deny PragmaNoCache

Parameters for Type squid::send\hit

value defaults to the namevar. The rule to allow or deny. action must one of deny or allow order by default is 05. comment A comment to add to the configuration file.

Defined Type squid::snmp_access

Defines snmp_access entries for a squid server.

squid::snmp_access { 'monitoring hosts':
  action => 'allow',
}

Adds a squid.conf line

# snmp_access fragment for monitoring hosts
snmp_access allow monitoring hosts

squid::snmp_access { 'monitoring hosts':
  action    => 'allow',
  comment   => 'Our monitoring hosts are allowed',
}

Adds a squid.conf line

# Our monitoring hosts are allowed
snmp_access allow monitoring hosts

These may be defined as a hash passed to ::squid

Defined Type squid::icp_access

Defines icp_access entries for a squid server.

squid::icp_access { 'our_networks hosts':
  action => 'allow',
}

Adds a squid.conf line

icp_access allow our_networks hosts

These may be defined as a hash passed to ::squid

Parameters for Type squid::http_allow

• value defaults to the namevar the rule to allow or deny.
• action must be deny or allow. By default it is allow. The squid.conf file is ordered so by default all allows appear before all denys. This can be overidden with the order parameter.
• order by default is 05

Defined Type Squid::Http_port

Defines http_port entries for a squid server. By setting optional ssl parameter to true will create https_port entries instead.

squid::http_port { '10000':
  options => 'accel vhost'
}
squid::http_port { '10001':
  ssl     => true,
  options => 'cert=/etc/squid/ssl_cert/server.cert key=/etc/squid/ssl_cert/server.key'
}
squid::http_port { '127.0.0.1:3128':
}

Results in a squid configuration of

http_port 10000 accel vhost
https_port 10001 cert=/etc/squid/ssl_cert/server.cert key=/etc/squid/ssl_cert/server.key
http_port 127.0.0.1:3128

Parameters for Type squid::http_port

• The title/namevar may be in the form port or host:port to provide the below values. Otherwise, specify port explicitly, and host if desired.
• port defaults to the port of the namevar and is the port number to listen on.
• host defaults to the host part of the namevar and is the interface to listen on. If not specified, Squid listens on all interfaces.
• options A string to specify any options for the default. By default and empty string.
• ssl A boolean. When set to true creates https_port entries. Defaults to false.

Defined Type Squid::Https_port

Defines https_port entries for a squid server. As an alternative to using the Squid::Http_port defined type with ssl set to true, you can use this type instead. The result is the same. Internally this type uses Squid::Http_port to create the configuration entries.

Parameters for Type squid::https_port

• port defaults to the namevar and is the port number.
• options A string to specify any options to add to the https_port line. Defaults to an empty string.

Defined Type squid::url_rewrite_program

Defines url_rewrite_program for a squid server.

squid::url_rewrite_program { '/usr/bin/squidGuard -c /etc/squidguard/squidGuard.conf':
  children      => 8,
  child_options => 'startup=0 idle=1 concurrency=0',
}

would result in the following squid url rewrite program

url_rewrite_program /usr/bin/squidGuard -c /etc/squidguard/squidGuard.conf
url_rewrite_children 8 startup=0 idle=1 concurrency=0

Defined Type squid::refresh_pattern

Defines refresh_pattern entries for a squid server.

squid::refresh_pattern { '^ftp:':
  min     => 1440,
  max     => 10080,
  percent => 20,
  order   => 60,
}

squid::refresh_pattern { '(/cgi-bin/|\?)':
  case_sensitive => false,
  min            => 0,
  max            => 0,
  percent        => 0,
  order          => 61,
}

would result in the following squid refresh patterns

# refresh_pattern fragment for ^ftp
refresh_pattern ^ftp: 1440 20% 10080
# refresh_pattern fragment for (/cgi-bin/|\?)
refresh_pattern (/cgi-bin/|\?) -i 0 0% 0

These may be defined as a hash passed to ::squid

YAML example:

squid::refresh_patterns:
  '^ftp':
    max:     10080
    min:     1440
    percent: 20
    order:   '60'
  '^gopher':
    max:     1440
    min:     1440
    percent: 0
    order:   '61'
  '(/cgi-bin/|\?)':
    case_sensitive: false
    max:            0
    min:            0
    percent:        0
    order:          '62'
  '.':
    max:     4320
    min:     0
    percent: 20
    order:   '63'

Parameters for Type squid::refresh_pattern

• case_sensitive Boolean value, if true (default) the regex is case sensitive, when false the case insensitive flag '-i' is added to the pattern
• comment Comment added before refresh rule, defaults to refresh_pattern fragment for title
• min Must be defined, the time (in minutes) an object without an explicit expiry time should be considered fresh.
• max Must be defined, the upper limit (in minutes) on how long objects without an explicit expiry time will be considered fresh.
• percent Must be defined, is a percentage of the objects age (time since last modification age)
• options See squid documentation for available options.
• order Each refresh_pattern has an order 05 by default this can be specified if order of refresh_pattern definition matters.

Defined Type Squid::Snmp_port

Defines snmp_port entries for a squid server.

squid::snmp_port { '1000':
  process_number => 3
}

Results in a squid configuration of

if ${process_number} = 3
snmp_port 1000
endif

Parameters for Type squid::http_port

• port defaults to the namevar and is the port number.
• options A string to specify any options for the default. By default and empty string.
• process_number If set to and integer the snmp_port is enabled only for a particular squid thread. Defaults to undef.

Defined Type squid::auth_param

Defines auth_param entries for a squid server.

squid::auth_param { 'basic auth_param':
  scheme  => 'basic',
  entries => [
    'program /usr/lib64/squid/basic_ncsa_auth /etc/squid/.htpasswd',
    'children 5',
    'realm Squid Basic Authentication',
    'credentialsttl 5 hours',
  ],
}

would result in multi entry squid auth_param

auth_param basic program /usr/lib64/squid/basic_ncsa_auth /etc/squid/.htpasswd
auth_param basic children 5
auth_param basic realm Squid Basic Authentication
auth_param basic credentialsttl 5 hours

These may be defined as a hash passed to ::squid

Parameters for Type squid::auth_param

• scheme the scheme used for authentication must be defined
• entries An array of entries, multiple members results in multiple lines in squid.conf
• order by default is '40'

Defined Type squid::ssl_bump

Defines ssl_bump entries for a squid server.

squid::ssl_bump { 'all':
  action => 'bump',
}

Adds a squid.conf line

ssl_bump bump all

These may be defined as a hash passed to ::squid

Parameters for Type squid::ssl_bump

• value The type of the ssl_bump, must be defined, e.g bump, peek, ..
• action The name of acl, defaults to bump.
• order by default is 05

Defined Type squid::sslproxy_cert_error

Defines sslproxy_cert_error entries for a squid server.

squid::sslproxy_cert_error { 'all':
  action => 'allow',
}

Adds a squid.conf line

sslproxy_cert_error allow all

These may be defined as a hash passed to ::squid

Parameters for Type squid::sslproxy_cert_error

• value defaults to the namevar the rule to allow or deny.
• action must be deny or allow. By default it is allow. The squid.conf file is ordered so by default all allows appear before all denys. This can be overidden with the order parameter.
• order by default is 05

Defined Type squid::extra_config_section

Squid has a large number of configuration directives. Not all of these have been exposed individually in this module. For those that haven't, the extra_config_section defined type can be used.

Using a hash of config_entries:

squid::extra_config_section { 'mail settings':
  order          => '60',
  config_entries => {
    'mail_from'    => 'squid@example.com',
    'mail_program' => 'mail',
  },
}

Results in a squid configuration of

# mail settings
mail_from squid@example.com
mail_program mail

Using an array of config_entries:

squid::extra_config_section { 'ssl_bump settings':
  order          => '60',
  config_entries => {
    'ssl_bump'         => ['server-first', 'all'],
    'sslcrtd_program'  => ['/usr/lib64/squid/ssl_crtd', '-s', '/var/lib/ssl_db', '-M', '4MB'],
    'sslcrtd_children' => ['8', 'startup=1', 'idle=1'],
  }
}

Results in a squid configuration of

# ssl_bump settings
ssl_bump server-first all
sslcrtd_program /usr/lib64/squid/ssl_crtd -s /var/lib/ssl_db -M 4MB
sslcrtd_children 8 startup=1 idle=1

Using an array of hashes of config_entries:

squid::extra_config_section { 'always_directs':
  order          => '60',
  config_entries => [{
    'always_direct' => ['deny    www.reallyreallybadplace.com',
                        'allow   my-good-dst',
                        'allow   my-other-good-dst'],
  }],
}

Results in a squid configuration of

# always_directs
always_direct deny    www.reallyreallybadplace.com
always_direct allow   my-good-dst
always_direct allow   my-other-good-dst

Parameters for Type squid::extra_config_section

• comment defaults to the namevar and is used as a section comment in squid.conf.
• config_entries A hash of configuration entries to create in this section. The hash key is the name of the configuration directive. The value is either a string, or an array of strings to use as the configuration directive options.
• order by default is '60'. It can be used to configure where in squid.conf this configuration section should occur.

Changelog

All notable changes to this project will be documented in this file. Each new release typically also includes the latest modulesync defaults. These should not affect the functionality of the module.

v3.0.0 (2020-09-29)

Full Changelog

Breaking changes:

• Drop EOL Debian 8 #155 (bastelfreak)
• drop Ubuntu 14.04 support #139 (bastelfreak)

Implemented enhancements:

• Add support Debian 10, Ubuntu 18.04 and EL8 #145 (ekohl)
• support forwarded for #137 (ssanden)
• Change the way SELinux is applied for portnumbers #135 (ralfbosz)

Fixed bugs:

• Add missing package state values #142 (ph1ll)

Closed issues:

• Duplicate HTTP Port Declarations For Different Bind IPs Produces SELinux Duplicate Resource Declaration Error #120

Merged pull requests:

• Puppet-lint fixes #153 (alexjfisher)
• Allow multiple access_log directives in squid.conf #151 (gcoxmoz)
• add typedef and class documentation #148 (TillHein)
• Use voxpupuli-acceptance #147 (ekohl)
• delete legacy travis directory #143 (bastelfreak)
• Remove duplicate CONTRIBUTING.md file #140 (dhoppe)
• Clean up acceptance spec helper #138 (ekohl)

v2.2.2 (2019-06-17)

Full Changelog

Merged pull requests:

• Allow puppet-selinux 3.x #133 (ekohl)

v2.2.1 (2019-05-31)

Full Changelog

Merged pull requests:

• allow puppetlabs-concat 6.x #131 (mmoll)

v2.2.0 (2019-05-21)

Full Changelog

Implemented enhancements:

• Override service restart command #127 (Wiston999)
• Control package status and version #126 (Wiston999)

Merged pull requests:

• Allow puppet-selinux 2.x #128 (ekohl)
• Allow puppetlabs/stdlib 6.x #125 (alexjfisher)

v2.1.0 (2019-05-03)

Full Changelog

Implemented enhancements:

• Validate squid config before applying changes #123 (alexjfisher)

v2.0.0 (2019-02-06)

Full Changelog

Breaking changes:

• modulesync 2.5.1 and drop Puppet4 #118 (bastelfreak)
• support listening on specific interfaces; changed params in squid::http_port{} #103 (tequeter)
• Fix url_rewrite_program #101 (SourceDoctor)

Implemented enhancements:

• Added 'manage_dir' parameter to cache_dir #116 (GeorgeCox)
• Add a Squid::Size type #112 (ekohl)
• modulesync 2.2.0 and allow puppet 6.x #109 (bastelfreak)
• Allow puppetlabs/stdlib 5.x and puppetlabs/concat 5.x #106 (bastelfreak)

Closed issues:

• ssl::server_name syntax error #117
• cache_dir on mounted filesystem #108

Merged pull requests:

• Use strings not symbols with beaker-puppet fact() #111 (alexjfisher)
• Update README.md #110 (AndreasPfaffeneder)
• drop EOL OSs; fix puppet version range #100 (bastelfreak)
• use gitrepos in .fixtures.yml #99 (bastelfreak)

v1.1.0 (2018-05-16)

Full Changelog

Implemented enhancements:

• Add visible_hostname, via, httpd_suppress_version_string and forwarded_for parameters #81 (SourceDoctor)
• add url_rewrite feature #78 (SourceDoctor)

Closed issues:

• puppet/selinux missing as requirement #95

Merged pull requests:

• Fixes #95 adds declare puppet-selinux dep #97 (traylenator)
• Rely on beaker-hostgenerator for docker nodesets #96 (ekohl)
• increase max concat module version #94 (TomRitserveldt)

v1.0.0 (2018-03-28)

Full Changelog

Breaking changes:

• Remove spurious ':' from refresh_pattern template #87 (ralfbosz)

Implemented enhancements:

• Syntax check when restarting. #76
• This commit applies a restorecon when using SELINUX #91 (ralfbosz)
• New defined type squid::send_hit #90 (traylenator)
• Fixes #8 Set selinux context of cache_dir and ports. #89 (ralfbosz)
• Allow Cache Replacement Policy to be configured #84 (SourceDoctor)
• Define Stylesheet and language for Squid Errorpage #83 (SourceDoctor)
• enable buffered logs #82 (SourceDoctor)
• add caching store control #80 (SourceDoctor)
• Snmp access #79 (SourceDoctor)

Closed issues:

• Support extra_config_section to take random configuration #31
• Set selinux file context on cache directory #8

Merged pull requests:

• Add snmp_incoming_address parameter #86 (alexjfisher)
• Remove EOL operatingsystems #75 (ekohl)
• Sanitise type #73 (ekohl)
• Run acceptance tests on Debian 9 #69 (ekohl)
• enable all auth_param types #66 (quielb)

v0.6.1 (2017-11-15)

Full Changelog

Merged pull requests:

• release 0.6.1 #72 (bastelfreak)
• add missing secret to travis config #71 (bastelfreak)

v0.6.0 (2017-11-15)

Full Changelog

Breaking changes:

• Convert to puppet 4/5 data types #58 (matonb)

Implemented enhancements:

• added debian 9 param defaults #60 (ssanden)
• When specifying the extra_config_sections as an array #45 (ralfbosz)

Merged pull requests:

• release 0.6.0 #70 (bastelfreak)
• Fix the tests #67 (ekohl)
• Clean up docs #62 (alexharv074)
• Add refresh_pattern defined type #57 (matonb)
• Use ruby 2.4.1 for beaker tests #56 (traylenator)
• Modulesync 0.21.3 #55 (traylenator)

v0.5.0 (2017-03-30)

• Add beaker acceptance tests
• An optional $comment param for http_access and acl (#47)
• Add support for freebsd

2017-01-12 - Release 0.4.0

Last release with Puppet 3 support!

• Fix minor syntax issue in README example code
• rubocop: fix RSpec/ImplicitExpect
• adds logformat directive to squid.conf header
• adds test for ::logformat parameter
• Added ssl_bump and sslproxy_cert_error support
• Added support for icp_access Squid conf setting
• Fix ordering issue with missing squid user for cache_dir

2016-09-19 - Release 0.3.0

• Add https_port defined type.
• Add extra_config_section permits extra random configuration.
• The auth_params defintions now appear before ACLs as it should.
• New parameters to specify owner of configuration, daemon name and executer to control cache directory.
• Addition of debian and ubuntu support.

2016-06-01 - Release 0.2.2

• Correct documentation examples.

2016-06-01 - Release 0.2.1

• All defined types can now be loaded as a hash to init and so can be loaded easily from hiera. e.g

class{'squid:
   http_ports => {'10000' =>  { options => 'accel vhost'},
                  '3000'  => {},
                 }

2016-04-18 - Release 0.1.1

• Add tags to module metadata.

2016-04-13 - Release 0.1.0

* This Changelog was automatically generated by github_changelog_generator