REFERENCE.md

Reference

Table of Contents

Classes

Public Classes

• caddy: Main class, includes all other classes.

Private Classes

• caddy::config: This class handles the Caddy config.
• caddy::install: This class handles the Caddy archive.
• caddy::install::repo: This class handles Caddy installation from a package repository
• caddy::service: This class handles the Caddy service.

Defined types

• caddy::configfile: This defined type handles a Caddy config file
• caddy::vhost: This defined type handles a Caddy virtual host

Data types

• Caddy::Config: Caddy config file type
• Caddy::VirtualHost: Caddy virtual host type

Classes

caddy

Main class, includes all other classes.

Examples

Basic usage

include caddy

Install customised version of Caddy

class { 'caddy':
  caddy_features => 'http.git,http.filter,http.ipfilter',
}

Install specific version of Caddy

class { 'caddy':
  version        => '2.0.0',
  install_method => 'github',
}

Parameters

The following parameters are available in the caddy class:

• version
• install_method
• install_path
• manage_user
• caddy_user
• manage_group
• caddy_group
• caddy_shell
• caddy_log_dir
• caddy_home
• caddy_ssl_dir
• caddy_license
• caddy_telemetry
• caddy_features
• caddy_architecture
• caddy_account_id
• caddy_api_key
• manage_systemd_unit
• systemd_limit_processes
• systemd_private_devices
• systemd_capability_bounding_set
• systemd_ambient_capabilities
• systemd_no_new_privileges
• manage_service
• service_name
• service_ensure
• service_enable
• manage_repo
• repo_settings
• package_name
• package_ensure
• manage_caddyfile
• caddyfile_source
• caddyfile_content
• config_file_extension
• config_dir
• purge_config_dir
• config_enable_dir
• purge_config_enable_dir
• config_files
• vhost_dir
• purge_vhost_dir
• vhost_enable_dir
• purge_vhost_enable_dir
• vhosts

version

Data type: String[1]

Which version is used.

Default value: '2.0.0'

install_method

Data type: Optional[Enum['github','repo']]

Which source to use for the Caddy installation. See https://caddyserver.com/docs/install.

• undef (default) - download from the official Caddy site
• github - download from Github releases
• repo - install from an OS repository

Default value: undef

install_path

Data type: Stdlib::Absolutepath

Directory where the Caddy binary is stored. Not used when $install_method is 'repo'.

Default value: '/opt/caddy'

manage_user

Data type: Boolean

Whether or not the module should create the user.

Default value: true

caddy_user

Data type: String[1]

The user used by the Caddy process.

Default value: 'caddy'

manage_group

Data type: Boolean

Whether or not the module should create the group.

Default value: true

caddy_group

Data type: String[1]

The group used by the Caddy process.

Default value: 'caddy'

caddy_shell

Data type: Stdlib::Absolutepath

Which shell is used.

Default value: '/sbin/nologin'

caddy_log_dir

Data type: Stdlib::Absolutepath

Directory where the log files are stored.

Default value: '/var/log/caddy'

caddy_home

Data type: Stdlib::Absolutepath

Directory where the Caddy data is stored.

Default value: '/var/lib/caddy'

caddy_ssl_dir

Data type: Stdlib::Absolutepath

Directory where Let's Encrypt certificates are stored.

Default value: '/etc/ssl/caddy'

caddy_license

Data type: Enum['personal', 'commercial']

Whether a personal or commercial license is used.

Default value: 'personal'

caddy_telemetry

Data type: Enum['on','off']

Whether telemetry data should be collected.

Default value: 'off'

caddy_features

Data type: String[1]

A list of features the Caddy binary should support.

Default value: 'http.git,http.filter,http.ipfilter'

caddy_architecture

Data type: String[1]

A temporary variable, required for the download URL.

Default value: $facts['os']['architecture']

caddy_account_id

Data type: Optional[String[1]]

The account ID, required for the commercial license.

Default value: undef

caddy_api_key

Data type: Optional[String[1]]

The API key, required for the commercial license.

Default value: undef

manage_systemd_unit

Data type: Boolean

Whether or not the module should create the systemd unit file.

Default value: true

systemd_limit_processes

Data type: Integer[0]

The number of processes.

Default value: 64

systemd_private_devices

Data type: Boolean

Whether the process has access to physical devices.

Default value: true

systemd_capability_bounding_set

Data type: Optional[String[1]]

Controls which capabilities to include in the capability bounding set for the executed process.

Default value: undef

systemd_ambient_capabilities

Data type: String[1]

Controls which capabilities to include in the ambient capability set for the executed process.

Default value: 'CAP_NET_BIND_SERVICE'

systemd_no_new_privileges

Data type: Optional[Boolean]

Whether the process and all its children can gain new privileges through execve().

Default value: undef

manage_service

Data type: Boolean

Whether or not the module should manage the service.

Default value: true

service_name

Data type: String[1]

Customise the name of the system service.

Default value: 'caddy'

service_ensure

Data type: Stdlib::Ensure::Service

Whether the service should be running or stopped.

Default value: 'running'

service_enable

Data type: Boolean

Whether the service should be enabled or disabled.

Default value: true

manage_repo

Data type: Boolean

Whether the APT/YUM(COPR) repository should be installed. Only relevant when $install_method is 'repo'.

Default value: true

repo_settings

Data type: Hash[String[1],Any]

Distro-specific repository settings.

Default value: {}

package_name

Data type: String[1]

Name of the caddy package to use. Only relevant when $install_method is 'repo'.

Default value: 'caddy'

package_ensure

Data type: String[1]

Whether to install or remove the caddy package. Only relevant when $install_method is 'repo'.

Default value: $version

manage_caddyfile

Data type: Boolean

Whether to manage Caddyfile.

Default value: true

caddyfile_source

Data type: Optional[Stdlib::Filesource]

Caddyfile source.

Default value: undef

caddyfile_content

Data type: Optional[String[1]]

Caddyfile content.

Default value: undef

config_file_extension

Data type: Variant[Enum[''], Pattern[/^\./]]

Default extension for config and virtual host files (must include leading .)

Default value: '.conf'

config_dir

Data type: Stdlib::Absolutepath

Where to store Caddy configs. Set this to /etc/caddy/conf-available to simulate nginx/apache behavior (see config_enable_dir also).

Default value: '/etc/caddy/config'

purge_config_dir

Data type: Boolean

Whether to purge Caddy config directory.

Default value: true

config_enable_dir

Data type: Optional[Stdlib::Absolutepath]

Where to load Caddy configs from. Set this parameter to /etc/caddy/conf-enabled to simulate nginx/apache behavior.

Default value: undef

purge_config_enable_dir

Data type: Boolean

Whether to purge Caddy enabled config directory.

Default value: $purge_config_dir

config_files

Data type: Hash[String[1], Caddy::Config]

Hash of config files to create.

Default value: {}

vhost_dir

Data type: Stdlib::Absolutepath

Where to store Caddy available virtual host configs. Set this to /etc/caddy/vhost.d if you'd prefer to keep virtual hosts separated from configs. Set this to /etc/caddy/sites-available to simulate nginx/apache behavior (see vhost_enable_dir also).

Default value: '/etc/caddy/config'

purge_vhost_dir

Data type: Boolean

Whether to purge Caddy available virtual host directory.

Default value: $purge_config_dir

vhost_enable_dir

Data type: Optional[Stdlib::Absolutepath]

Where to load Caddy virtual host configs from. Set this parameter to /etc/caddy/sites-enabled to simulate nginx/apache behavior.

Default value: undef

purge_vhost_enable_dir

Data type: Boolean

Whether to purge Caddy enabled virtual host directory.

Default value: $purge_vhost_dir

vhosts

Data type: Hash[String[1], Caddy::VirtualHost]

Hash of virtual hosts to create.

Default value: {}

Defined types

caddy::configfile

This defined type handles a Caddy config file

Examples

Configure Caddy logging

caddy::configfile { 'subdomain-log':
  source => 'puppet:///modules/caddy/etc/caddy/config/logging.conf',
}

Same as above but using content

$log_config = @(SUBDOMAIN_LOG)
  (subdomain-log) {
    log {
      hostnames {args[0]}
      output file /var/log/caddy/{args[0]}.log
    }
  }
  | SUBDOMAIN_LOG

caddy::configfile { 'subdomain-log':
  content => $log_config,
}

Parameters

The following parameters are available in the caddy::configfile defined type:

• ensure
• source
• content
• config_dir
• enable_dir
• file_extension

ensure

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

Make the config file either present (same as disabled), enabled, disabled or absent.

Default value: 'enabled'

source

Data type: Optional[Stdlib::Filesource]

Source (path) for the caddy config file.

Default value: undef

content

Data type: Optional[String]

String with the caddy config file.

Default value: undef

config_dir

Data type: Stdlib::Absolutepath

Where to store the config file.

Default value: $caddy::config_dir

enable_dir

Data type: Optional[Stdlib::Absolutepath]

Directory to symlink the config config file into (conf-enabled e.g.) if any.

Default value: $caddy::config_enable_dir

file_extension

Data type: Variant[Enum[''], Pattern[/^\./]]

Default extension for the config file (must include leading .)

Default value: $caddy::config_file_extension

caddy::vhost

This defined type handles a Caddy virtual host

Examples

Configure virtual host, based on source

caddy::vhost { 'example1':
  source => 'puppet:///modules/caddy/etc/caddy/config/example1.conf',
}

Configure virtual host, based on content

caddy::vhost { 'example2:
  content => 'localhost:2015',
}

Parameters

The following parameters are available in the caddy::vhost defined type:

• ensure
• source
• content
• config_dir
• enable_dir
• file_extension

ensure

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

Make the vhost either present (same as disabled), enabled, disabled or absent.

Default value: 'enabled'

source

Data type: Optional[Stdlib::Filesource]

Source (path) for the caddy vhost configuration.

Default value: undef

content

Data type: Optional[String]

String with the caddy vhost configuration.

Default value: undef

config_dir

Data type: Stdlib::Absolutepath

Where to store the vhost config file.

Default value: $caddy::vhost_dir

enable_dir

Data type: Optional[Stdlib::Absolutepath]

Directory to symlink the vhost config file into (sites-enabled e.g.) if any.

Default value: $caddy::vhost_enable_dir

file_extension

Data type: Variant[Enum[''], Pattern[/^\./]]

Default extension for the vhost config file (must include leading .)

Default value: $caddy::config_file_extension

Data types

Caddy::Config

Caddy config file type

Alias of

Struct[{
    ensure => Optional[Enum['present','enabled','disabled','absent']],
    source => Optional[Stdlib::Filesource],
    content => Optional[String[1]],
}]

Caddy::VirtualHost

Caddy virtual host type

Alias of

Struct[{
    ensure => Optional[Enum['present','enabled','disabled','absent']],
    source => Optional[Stdlib::Filesource],
    content => Optional[String[1]],
}]