From 6f8af33b018122eeb9b7502888b9dbcdc379c954 Mon Sep 17 00:00:00 2001 From: Steffen Zieger Date: Wed, 13 Nov 2024 08:17:43 +0100 Subject: [PATCH] improve documentation, add REFERENCE.md --- README.md | 34 +- REFERENCE.md | 532 +++++++++++++++++++ lib/puppet/functions/memcached/max_memory.rb | 5 + manifests/init.pp | 148 +++++- 4 files changed, 677 insertions(+), 42 deletions(-) create mode 100644 REFERENCE.md diff --git a/README.md b/README.md index a707d12..3c66d59 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# memached module for Puppet +# memcached module for Puppet [![Build Status](https://github.com/saz/puppet-memcached/workflows/CI/badge.svg)](https://github.com/saz/puppet-memcached/actions?query=workflow%3ACI) @@ -103,35 +103,3 @@ memcached::instance{'11222': override_source => "${module_name}/memcached_11222_override.conf\n", } ``` - -### Other class parameters - -* $package_ensure = 'present' -* $logfile = '/var/log/memcached.log' -* $logstdout = false (Set this to true to disable logging to a file/syslog entirely, useful when memcached runs in containers) -* $pidfile = '/var/run/memcached.pid' (Debian family only, set to false to disable pidfile) -* $max_memory = false -* $max_item_size = false -* $min_item_size = false -* $factor = false -* $lock_memory = false (WARNING: good if used intelligently, google for -k key) -* $listen = '127.0.0.1' (if TLS/SSL is enabled, 'notls' prefix can be used to disable for specific listeners "notls::") -* $listen_ip = '127.0.0.1' (deprecated, listen will take precedence over this) -* $tcp_port = 11211 -* $udp_port = 0 -* $manage_firewall = false -* $user = '' (OS specific setting, see params.pp) -* $max_connections = 8192 -* $verbosity = undef -* $unix_socket = undef -* $install_dev = false (TRUE if 'libmemcached-dev' package should be installed) -* $processorcount = $::processorcount -* $service_restart = true (restart service after configuration changes, false to prevent restarts) -* $service_flags = '-l 127.0.0.1 -u _memcached -P /var/run/memcached.pid' (only relevant for OpenBSD, to configure the service) -* $use_sasl = false (start memcached with SASL support) -* $use_tls = false (start memcached with TLS support) -* $tls_cert_chain = undef -* $tls_key = undef -* $tls_ca_cert = undef -* $tls_verify_mode = 1 (0: None, 1: Request, 2: Require, 3: Once) -* $large_mem_pages = false (try to use large memory pages) diff --git a/REFERENCE.md b/REFERENCE.md new file mode 100644 index 0000000..c085b0c --- /dev/null +++ b/REFERENCE.md @@ -0,0 +1,532 @@ +# Reference + + + +## Table of Contents + +### Classes + +#### Public Classes + +* [`memcached`](#memcached): This class manages memcached +* [`memcached::params`](#memcached--params): == Class: memcached::params + +#### Private Classes + +* `memcached::instance::servicefile`: helper class to configure the memcache multiinstance unit file *once* + +### Defined types + +* [`memcached::instance`](#memcached--instance): Manage multiple memcached instances + +### Functions + +* [`memcached::max_memory`](#memcached--max_memory): Calculate max_memory size from fact 'memsize' and passed argument. + +## Classes + +### `memcached` + +This class manages memcached + +#### Examples + +##### Use default settings + +```puppet +include memcached +``` + +#### Parameters + +The following parameters are available in the `memcached` class: + +* [`package_ensure`](#-memcached--package_ensure) +* [`service_manage`](#-memcached--service_manage) +* [`service_flags`](#-memcached--service_flags) +* [`logfile`](#-memcached--logfile) +* [`logstdout`](#-memcached--logstdout) +* [`syslog`](#-memcached--syslog) +* [`pidfile`](#-memcached--pidfile) +* [`manage_firewall`](#-memcached--manage_firewall) +* [`max_memory`](#-memcached--max_memory) +* [`max_item_size`](#-memcached--max_item_size) +* [`min_item_size`](#-memcached--min_item_size) +* [`factor`](#-memcached--factor) +* [`lock_memory`](#-memcached--lock_memory) +* [`listen`](#-memcached--listen) +* [`listen_ip`](#-memcached--listen_ip) +* [`tcp_port`](#-memcached--tcp_port) +* [`udp_port`](#-memcached--udp_port) +* [`user`](#-memcached--user) +* [`max_connections`](#-memcached--max_connections) +* [`verbosity`](#-memcached--verbosity) +* [`unix_socket`](#-memcached--unix_socket) +* [`unix_socket_mask`](#-memcached--unix_socket_mask) +* [`install_dev`](#-memcached--install_dev) +* [`processorcount`](#-memcached--processorcount) +* [`service_restart`](#-memcached--service_restart) +* [`auto_removal`](#-memcached--auto_removal) +* [`use_sasl`](#-memcached--use_sasl) +* [`use_tls`](#-memcached--use_tls) +* [`tls_cert_chain`](#-memcached--tls_cert_chain) +* [`tls_key`](#-memcached--tls_key) +* [`tls_ca_cert`](#-memcached--tls_ca_cert) +* [`tls_verify_mode`](#-memcached--tls_verify_mode) +* [`use_registry`](#-memcached--use_registry) +* [`registry_key`](#-memcached--registry_key) +* [`large_mem_pages`](#-memcached--large_mem_pages) +* [`use_svcprop`](#-memcached--use_svcprop) +* [`svcprop_fmri`](#-memcached--svcprop_fmri) +* [`svcprop_key`](#-memcached--svcprop_key) +* [`extended_opts`](#-memcached--extended_opts) +* [`config_tmpl`](#-memcached--config_tmpl) +* [`disable_cachedump`](#-memcached--disable_cachedump) +* [`max_reqs_per_event`](#-memcached--max_reqs_per_event) +* [`disable_flush_all`](#-memcached--disable_flush_all) +* [`disable_watch`](#-memcached--disable_watch) +* [`memory_file`](#-memcached--memory_file) + +##### `package_ensure` + +Data type: `Enum['present', 'latest', 'absent']` + +Set ensure of the memcached package + +Default value: `'present'` + +##### `service_manage` + +Data type: `Boolean` + +Manage the memcached service + +Default value: `true` + +##### `service_flags` + +Data type: `Optional[String]` + +Pass flags to the service managed by Puppet + +Default value: `$memcached::params::service_flags` + +##### `logfile` + +Data type: `Optional[Stdlib::Absolutepath]` + +Specify file to log to. Not supported on OS using systemd + +Default value: `$memcached::params::logfile` + +##### `logstdout` + +Data type: `Boolean` + +Disable logging to a file or syslog entirely. Only supported on RedHat-based OS and Suse + +Default value: `false` + +##### `syslog` + +Data type: `Boolean` + +Log to syslog. Only supported on RedHat-based OS and Suse + +Default value: `false` + +##### `pidfile` + +Data type: `Variant[Stdlib::Absolutepath, Boolean[false], Undef]` + +Save pid in file + +Default value: `$memcached::params::pidfile` + +##### `manage_firewall` + +Data type: `Boolean` + +Create simple firewall rules. Only supported on Linux + +Default value: `false` + +##### `max_memory` + +Data type: `String[1]` + +Max memory memcached should use to store items. Either in percent or mb + +Default value: `'95%'` + +##### `max_item_size` + +Data type: `Optional[Variant[Integer, String]]` + +Adjusts max item size + +Default value: `undef` + +##### `min_item_size` + +Data type: `Optional[Variant[Integer, String]]` + +Min space used for key+value+flags + +Default value: `undef` + +##### `factor` + +Data type: `Optional[Variant[Integer, String]]` + +Chunk size growth factor + +Default value: `undef` + +##### `lock_memory` + +Data type: `Boolean` + +Lock down all paged memory + +Default value: `false` + +##### `listen` + +Data type: `Optional[Variant[String,Array[String]]]` + +Interface to listen on + +Default value: `undef` + +##### `listen_ip` + +Data type: `Optional[Variant[Stdlib::IP::Address,Array[Stdlib::IP::Address]]]` + +Deprecated. Use `listen` instead + +Default value: `undef` + +##### `tcp_port` + +Data type: `Integer` + +TCP port to listen on + +Default value: `11211` + +##### `udp_port` + +Data type: `Integer` + +UDP port to listen on + +Default value: `0` + +##### `user` + +Data type: `String` + +User to run memcached service as + +Default value: `$memcached::params::user` + +##### `max_connections` + +Data type: `Integer` + +Max simultaneous connections + +Default value: `8192` + +##### `verbosity` + +Data type: `Optional[Enum['v', 'vv', 'vvv']]` + +v: verbose (print errors/warnings while in event loop) +vv: very verbose (also print client commands/responses) +vvv: extremely verbose (internal state transitions) + +Default value: `undef` + +##### `unix_socket` + +Data type: `Optional[String]` + +UNIX socket to listen on (disables network support) + +Default value: `undef` + +##### `unix_socket_mask` + +Data type: `String` + +access mask for UNIX socket, in octal + +Default value: `'0755'` + +##### `install_dev` + +Data type: `Boolean` + +Manage installation of the memcached dev package + +Default value: `false` + +##### `processorcount` + +Data type: `Variant[String,Integer]` + +Number of threads to use + +Default value: `$facts['processors']['count']` + +##### `service_restart` + +Data type: `Boolean` + +Whether or not to restart the memcached service on changes + +Default value: `true` + +##### `auto_removal` + +Data type: `Boolean` + +Return error on memory exhausted instead of evicting + +Default value: `false` + +##### `use_sasl` + +Data type: `Boolean` + +Turn on SASL authentication + +Default value: `false` + +##### `use_tls` + +Data type: `Boolean` + +Enable TLS/SSL + +Default value: `false` + +##### `tls_cert_chain` + +Data type: `Optional[Stdlib::Absolutepath]` + +Path to certificate chain file + +Default value: `undef` + +##### `tls_key` + +Data type: `Optional[Stdlib::Absolutepath]` + +Path to certificate key file + +Default value: `undef` + +##### `tls_ca_cert` + +Data type: `Optional[Stdlib::Absolutepath]` + +Path to CA certificate file + +Default value: `undef` + +##### `tls_verify_mode` + +Data type: `Integer[0,3]` + +Peer certificate verify mode + +Default value: `1` + +##### `use_registry` + +Data type: `Boolean` + + + +Default value: `$memcached::params::use_registry` + +##### `registry_key` + +Data type: `String` + + + +Default value: `'HKLM\System\CurrentControlSet\services\memcached\ImagePath'` + +##### `large_mem_pages` + +Data type: `Boolean` + +Try to use large memory pages (if available) + +Default value: `false` + +##### `use_svcprop` + +Data type: `Boolean` + + + +Default value: `$memcached::params::use_svcprop` + +##### `svcprop_fmri` + +Data type: `String` + + + +Default value: `'memcached:default'` + +##### `svcprop_key` + +Data type: `String` + + + +Default value: `'memcached/options'` + +##### `extended_opts` + +Data type: `Optional[Array[String]]` + +Array of extended options + +Default value: `undef` + +##### `config_tmpl` + +Data type: `String` + +Use a different config template + +Default value: `$memcached::params::config_tmpl` + +##### `disable_cachedump` + +Data type: `Boolean` + +Disable stats cachedump and lru_crawler metadump + +Default value: `false` + +##### `max_reqs_per_event` + +Data type: `Optional[Integer]` + +Maximum number of requests per event, limits the +requests processed per connection to prevent starvation + +Default value: `undef` + +##### `disable_flush_all` + +Data type: `Boolean` + +Disable flush_all command + +Default value: `false` + +##### `disable_watch` + +Data type: `Boolean` + +Disable watch commands (live logging) + +Default value: `false` + +##### `memory_file` + +Data type: `Optional[Stdlib::Absolutepath]` + +mmap a file for item memory. + +Default value: `undef` + +### `memcached::params` + +== Class: memcached::params + +## Defined types + +### `memcached::instance` + +Manage multiple memcached instances + +#### Parameters + +The following parameters are available in the `memcached::instance` defined type: + +* [`manage_firewall`](#-memcached--instance--manage_firewall) +* [`port`](#-memcached--instance--port) +* [`limits`](#-memcached--instance--limits) +* [`override_content`](#-memcached--instance--override_content) +* [`override_source`](#-memcached--instance--override_source) + +##### `manage_firewall` + +Data type: `Boolean` + +enable/disable fireall management via puppetlabs/firewall + +Default value: `false` + +##### `port` + +Data type: `Stdlib::Port::Unprivileged` + +the udp and tcp port to listen on. By default, the instance name is used + +Default value: `Integer($name)` + +##### `limits` + +Data type: `Optional[Systemd::ServiceLimits]` + +systemd limits for the service + +Default value: `undef` + +##### `override_content` + +Data type: `Optional[String[1]]` + +overrides for the unit, as string + +Default value: `undef` + +##### `override_source` + +Data type: `Optional[Stdlib::Filesource]` + +overrides for the unit, as file resource + +Default value: `undef` + +## Functions + +### `memcached::max_memory` + +Type: Ruby 4.x API + +Calculate max_memory size from fact 'memsize' and passed argument. + +#### `memcached::max_memory(Any $arg)` + +Calculate max_memory size from fact 'memsize' and passed argument. + +Returns: `Integer` + +##### `arg` + +Data type: `Any` + + + diff --git a/lib/puppet/functions/memcached/max_memory.rb b/lib/puppet/functions/memcached/max_memory.rb index 7a456ec..fffa56a 100644 --- a/lib/puppet/functions/memcached/max_memory.rb +++ b/lib/puppet/functions/memcached/max_memory.rb @@ -1,9 +1,14 @@ # frozen_string_literal: true +# @summary Returns memory in mb based on fact `memsize` and passed argument + # Calculate max_memory size from fact 'memsize' and passed argument. Puppet::Functions.create_function(:'memcached::max_memory') do dispatch :max_memory do + # @param arg Amount of memory to use in percent or MB required_param 'Any', :arg + # @return memory size in MB + return_type 'Integer' end def max_memory(arg) diff --git a/manifests/init.pp b/manifests/init.pp index d9fabbe..e4a2964 100644 --- a/manifests/init.pp +++ b/manifests/init.pp @@ -1,11 +1,141 @@ -# == Class: memcached +# @summary +# This class manages memcached # -# Manage memcached +# @example Use default settings +# include memcached # -# == Parameters -# [* syslog *] -# Boolean. -# If true will pipe output to /bin/logger, sends to syslog. +# @param package_ensure +# Set ensure of the memcached package +# +# @param service_manage +# Manage the memcached service +# +# @param service_flags +# Pass flags to the service managed by Puppet +# +# @param logfile +# Specify file to log to. Not supported on OS using systemd +# +# @param logstdout +# Disable logging to a file or syslog entirely. Only supported on RedHat-based OS and Suse +# +# @param syslog +# Log to syslog. Only supported on RedHat-based OS and Suse +# +# @param pidfile +# Save pid in file +# +# @param manage_firewall +# Create simple firewall rules. Only supported on Linux +# +# @param max_memory +# Max memory memcached should use to store items. Either in percent or mb +# +# @param max_item_size +# Adjusts max item size +# +# @param min_item_size +# Min space used for key+value+flags +# +# @param factor +# Chunk size growth factor +# +# @param lock_memory +# Lock down all paged memory +# +# @param listen +# Interface to listen on +# +# @param listen_ip +# Deprecated. Use `listen` instead +# +# @param tcp_port +# TCP port to listen on +# +# @param udp_port +# UDP port to listen on +# +# @param user +# User to run memcached service as +# +# @param max_connections +# Max simultaneous connections +# +# @param verbosity +# v: verbose (print errors/warnings while in event loop) +# vv: very verbose (also print client commands/responses) +# vvv: extremely verbose (internal state transitions) +# +# @param unix_socket +# UNIX socket to listen on (disables network support) +# +# @param unix_socket_mask +# access mask for UNIX socket, in octal +# +# @param install_dev +# Manage installation of the memcached dev package +# +# @param processorcount +# Number of threads to use +# +# @param service_restart +# Whether or not to restart the memcached service on changes +# +# @param auto_removal +# Return error on memory exhausted instead of evicting +# +# @param use_sasl +# Turn on SASL authentication +# +# @param use_tls +# Enable TLS/SSL +# +# @param tls_cert_chain +# Path to certificate chain file +# +# @param tls_key +# Path to certificate key file +# +# @param tls_ca_cert +# Path to CA certificate file +# +# @param tls_verify_mode +# Peer certificate verify mode +# +# @param use_registry +# +# @param registry_key +# +# @param large_mem_pages +# Try to use large memory pages (if available) +# +# @param use_svcprop +# +# @param svcprop_fmri +# +# @param svcprop_key +# +# @param extended_opts +# Array of extended options +# +# @param config_tmpl +# Use a different config template +# +# @param disable_cachedump +# Disable stats cachedump and lru_crawler metadump +# +# @param max_reqs_per_event +# Maximum number of requests per event, limits the +# requests processed per connection to prevent starvation +# +# @param disable_flush_all +# Disable flush_all command +# +# @param disable_watch +# Disable watch commands (live logging) +# +# @param memory_file +# mmap a file for item memory. # class memcached ( Enum['present', 'latest', 'absent'] $package_ensure = 'present', @@ -16,7 +146,7 @@ Boolean $syslog = false, Variant[Stdlib::Absolutepath, Boolean[false], Undef] $pidfile = $memcached::params::pidfile, Boolean $manage_firewall = false, - $max_memory = '95%', + String[1] $max_memory = '95%', Optional[Variant[Integer, String]] $max_item_size = undef, Optional[Variant[Integer, String]] $min_item_size = undef, Optional[Variant[Integer, String]] $factor = undef, @@ -27,7 +157,7 @@ Integer $udp_port = 0, String $user = $memcached::params::user, Integer $max_connections = 8192, - Optional[String] $verbosity = undef, + Optional[Enum['v', 'vv', 'vvv']] $verbosity = undef, Optional[String] $unix_socket = undef, String $unix_socket_mask = '0755', Boolean $install_dev = false, @@ -39,7 +169,7 @@ Optional[Stdlib::Absolutepath] $tls_cert_chain = undef, Optional[Stdlib::Absolutepath] $tls_key = undef, Optional[Stdlib::Absolutepath] $tls_ca_cert = undef, - Integer $tls_verify_mode = 1, + Integer[0,3] $tls_verify_mode = 1, Boolean $use_registry = $memcached::params::use_registry, String $registry_key = 'HKLM\System\CurrentControlSet\services\memcached\ImagePath', Boolean $large_mem_pages = false,