Skip to content

Latest commit

 

History

History
629 lines (393 loc) · 14.5 KB

REFERENCE.md

File metadata and controls

629 lines (393 loc) · 14.5 KB
Raw

Reference

Table of Contents

Classes

  • logstash: This class manages installation, configuration and execution of Logstash 5.x.
  • logstash::config: This class manages configuration directories for Logstash.
  • logstash::package: This class manages the Logstash package. It is usually used only by the top-level logstash class. It's unlikely that you will need to decl
  • logstash::service: This mangages the system service for Logstash. It is usually used only by the top-level logstash class. It's unlikely that you will need t

Defined types

  • logstash::configfile: This type represents a Logstash pipeline configuration file. Parameters are mutually exclusive. Only one should be specified.
  • logstash::patternfile: This type represents a Grok pattern file for Logstash.
  • logstash::plugin: Manage the installation of a Logstash plugin. By default, plugins are downloaded from RubyGems, but it is also possible to install from a lo

Classes

logstash

This class manages installation, configuration and execution of Logstash 5.x.

Examples

Install Logstash, ensure the service is running and enabled.
class { 'logstash': }
Remove Logstash.
class { 'logstash':
  ensure => 'absent',
}
Install everything but disable the service.
class { 'logstash':
  status => 'disabled',
}
Configure Logstash settings.
class { 'logstash':
  settings => {
    'http.port' => '9700',
  }
}
Configure Logstash startup options.
class { 'logstash':
  startup_options => {
    'LS_USER' => 'root',
  }
}
Set JVM memory options.
class { 'logstash':
  jvm_options => [
    '-Xms1g',
    '-Xmx1g',
  ]
}
Configure multiple pipelines.
class { 'logstash':
  pipelines => [
    {
      "pipeline.id" => "my-pipeline_1",
      "path.config" =>  "/etc/path/to/p1.config",
    },
    {
      "pipeline.id" => "my-other-pipeline",
      "path.config" =>  "/etc/different/path/p2.cfg",
    }
  ]
}

Parameters

The following parameters are available in the logstash class:

ensure

Data type: String

Controls if Logstash should be present or absent.

If set to absent, the Logstash package will be uninstalled. Related files will be purged as much as possible. The exact behavior is dependant on the service provider, specifically its support for the 'purgable' property.

Default value: 'present'

auto_upgrade

Data type: Boolean

If set to true, Logstash will be upgraded if the package provider is able to find a newer version. The exact behavior is dependant on the service provider, specifically its support for the 'upgradeable' property.

Default value: false

status

Data type: String

The desired state of the Logstash service. Possible values:

  • enabled: Service running and started at boot time.
  • disabled: Service stopped and not started at boot time.
  • running: Service running but not be started at boot time.
  • unmanaged: Service will not be started at boot time. Puppet will neither stop nor start the service.

Default value: 'enabled'

version

Data type: String

The specific version to install, if desired.

Default value: undef

restart_on_change

Data type: Boolean

Restart the service whenever the configuration changes.

Disabling automatic restarts on config changes may be desired in an environment where you need to ensure restarts occur in a controlled/rolling manner rather than during a Puppet run.

Default value: true

package_url

Data type: String

Explict Logstash package URL to download.

Valid URL types are:

  • http://
  • https://
  • ftp://
  • puppet://
  • file:/

Default value: undef

package_name

Data type: String

The name of the Logstash package in the package manager.

Default value: 'logstash'

download_timeout

Data type: Integer

Timeout, in seconds, for http, https, and ftp downloads.

Default value: 600

home_dir

Data type: Stdlib::Absolutepath

The home directory for logstash.

Default value: '/usr/share/logstash'

logstash_user

Data type: String

The user that Logstash should run as. This also controls file ownership.

Default value: 'logstash'

logstash_group

Data type: String

The group that Logstash should run as. This also controls file group ownership.

Default value: 'logstash'

purge_config

Data type: Boolean

Purge the config directory of any unmanaged files,

Default value: true

service_provider

Data type: Optional[String[1]]

Service provider (init system) to use. By Default, the module will try to choose the 'standard' provider for the current distribution.

Default value: undef

settings

Data type: Hash

A collection of settings to be defined in logstash.yml.

See: https://www.elastic.co/guide/en/logstash/current/logstash-settings-file.html

Default value: {}

startup_options

Data type: Hash

A collection of settings to be defined in startup.options.

See: https://www.elastic.co/guide/en/logstash/current/config-setting-files.html

Default value: {}

jvm_options_defaults

Data type: Hash

Default set of optionname => option mappings from upstream 8.5 version

Default value:

{
    '-Xms' => '-Xms1g',
    '-Xmx' => '-Xmx1g',
    'UseConcMarkSweepGC' => '11-13:-XX:+UseConcMarkSweepGC',
    'CMSInitiatingOccupancyFraction=' => '11-13:-XX:CMSInitiatingOccupancyFraction=75',
    'UseCMSInitiatingOccupancyOnly' => '11-13:-XX:+UseCMSInitiatingOccupancyOnly',
    '-Djava.awt.headless=' => '-Djava.awt.headless=true',
    '-Dfile.encoding=' => '-Dfile.encoding=UTF-8',
    'HeapDumpOnOutOfMemoryError' => '-XX:+HeapDumpOnOutOfMemoryError',
    '-Djava.security.egd' => '-Djava.security.egd=file:/dev/urandom',
  }
jvm_options

Data type: Array

A collection of settings to be defined in jvm.options. Override same settings in jvm_options_defaults

Default value: []

pipelines

Data type: Array

A collection of settings to be defined in pipelines.yml.

Default value: []

manage_repo

Data type: Boolean

Enable repository management. Configure the official repositories.

Default value: true

config_dir

Data type: String

Path containing the Logstash configuration.

Default value: '/etc/logstash'

logstash::config

This class manages configuration directories for Logstash.

Examples

Include this class to ensure its resources are available.
include logstash::config

logstash::package

This class manages the Logstash package.

It is usually used only by the top-level logstash class. It's unlikely that you will need to declare this class yourself.

Examples

Include this class to ensure its resources are available.
include logstash::package

Parameters

The following parameters are available in the logstash::package class:

package_name

Data type: String

The name of the Logstash package in the package manager.

Default value: $logstash::package_name

version

Data type: String

Install precisely this version from the package manager.

Default value: $logstash::version

package_url

Data type: String

Get the package from this URL, not from the package manager.

Default value: $logstash::package_url

logstash::service

This mangages the system service for Logstash.

It is usually used only by the top-level logstash class. It's unlikely that you will need to declare this class yourself.

Examples

Include this class to ensure its resources are available.
include logstash::service

Defined types

logstash::configfile

This type represents a Logstash pipeline configuration file.

Parameters are mutually exclusive. Only one should be specified.

Examples

Create a config file content with literal content.
logstash::configfile { 'heartbeat':
  content => 'input { heartbeat {} }',
}
Render a config file from a template.
logstash::configfile { 'from-template':
  template => 'site-logstash-module/pipeline-config.erb',
}
Copy the config from a file source.
logstash::configfile { 'apache':
  source => 'puppet://path/to/apache.conf',
}
Create a config at specific location. Good for multiple pipelines.
logstash::configfile { 'heartbeat-2':
  content => 'input { heartbeat {} }',
  path    => '/usr/local/etc/logstash/pipeline-2/heartbeat.conf'
}

Parameters

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

content

Data type: String

Literal content to be placed in the file.

Default value: undef

template

Data type: String

A template from which to render the file.

Default value: undef

source

Data type: String

A file resource to be used for the file.

Default value: undef

path

Data type: String

An optional full path at which to create the file.

Default value: undef

logstash::patternfile

This type represents a Grok pattern file for Logstash.

Examples

Define a pattern file.
logstash::patternfile { 'mypattern':
  source => 'puppet:///path/to/my/custom/pattern'
}
Define a pattern file with an explicit destination filename.
logstash::patternfile { 'mypattern':
  source   => 'puppet:///path/to/my/custom/pattern',
  filename => 'custom-pattern-name'
}

Parameters

The following parameters are available in the logstash::patternfile defined type:

source

Data type: Pattern[/^(puppet|file):\/\//]

File source for the pattern file. eg. puppet://[...] or file://[...]

Default value: undef

filename

Data type: Optional[String[1]]

Optionally set the destination filename.

Default value: undef

logstash::plugin

Manage the installation of a Logstash plugin.

By default, plugins are downloaded from RubyGems, but it is also possible to install from a local Gem, or one stored in Puppet.

Examples

Install a plugin.
logstash::plugin { 'logstash-input-stdin': }
Remove a plugin.
logstash::plugin { 'logstash-input-stout':
  ensure => absent,
}
Install a plugin from a local file.
logstash::plugin { 'logstash-input-custom':
  source => 'file:///tmp/logstash-input-custom.gem',
}
Install a plugin from a Puppet module.
logstash::plugin { 'logstash-input-custom':
  source => 'puppet:///modules/logstash-site-plugins/logstash-input-custom.gem',
}
Install X-Pack.
logstash::plugin { 'x-pack':
  source => 'https://artifacts.elastic.co/downloads/packs/x-pack/x-pack-5.3.0.zip',
}
Install a plugin, overriding JVM options via the environment.
logstash::plugin { 'logstash-input-jmx':
  environment => ['LS_JAVA_OPTS=-Xms1g -Xmx1g']
}

Parameters

The following parameters are available in the logstash::plugin defined type:

ensure

Data type: String

Install or remove with present or absent.

Default value: present

source

Data type: String

Install from this file, not from RubyGems.

Default value: undef

user

Data type: String

User to install plugin as.

Default value: 'root'

environment

Data type: String

Environment used when running 'logstash-plugin'

Default value: []