Skip to content

Latest commit

 

History

History
349 lines (293 loc) · 17.2 KB

README.md

File metadata and controls

349 lines (293 loc) · 17.2 KB

puppet-rsyslog Build Status

Manage rsyslog client and server via Puppet

Donate

If you find this module useful, consider supporting me via Gratipay

Support via Gratipay

or send some bitcoins to 1Na3YFUmdxKxJLiuRXQYJU2kiNqA3KY2j9

REQUIREMENTS

  • Puppet >= 3.0
  • Starting with release 4.0.0 Puppet < 3.0 is not tested anymore

Supported platforms

  • Debian-based distributions
  • RedHat-based distributions
  • Suse-based distributions
  • Gentoo
  • FreeBSD

USAGE

Client

Using default values

  class { 'rsyslog::client': }

Variables and default values

  class { 'rsyslog::client':
    log_remote                => true,
    spool_size                => '1g',
    spool_timeoutenqueue      => false,
    remote_type               => 'tcp',
    remote_forward_format     => 'RSYSLOG_ForwardFormat',
    log_local                 => false,
    disable_xconsole          => false,
    log_local_custom          => undef,
    log_auth_local            => false,
    listen_localhost          => false,
    split_config              => false,
    custom_config             => undef,
    custom_params             => undef,
    server                    => 'log',
    port                      => '514',
    remote_servers            => false,
    ssl                       => false,
    ssl_ca                    => undef,
    ssl_permitted_peer        => undef,
    ssl_auth_mode             => 'anon',
    log_templates             => false,
    log_filters               => false,
    actionfiletemplate_cust   => false,
    actionfiletemplate        => false,
    high_precision_timestamps => false,
    imfiles                   => undef
  }

imfile entries

Gathers log information from a file

  rsyslog::imfile { 'my-imfile':
    file_name     => '/some/file',
    file_tag      => 'mytag',
    file_facility => 'myfacility',
  }

rsyslog.d conf files

e.g. rsyslog.d/10-puppetagent.conf - moves puppet-agent entries to a file and excludes from /var/log/messages

  rsyslog::snippet { '10-puppetagent':
    content => ":programname,contains,\"puppet-agent\" /var/log/puppetlabs/puppet/puppet-agent.log\n& ~",
  }

Defining custom logging templates

The log_templates parameter can be used to set up custom logging templates, which can be used for local and/or remote logging. More detail on template formats can be found in the rsyslog documentation.

The following examples sets up a custom logging template as per RFC3164fmt:

class{'rsyslog::client':
  log_templates => [
    {
      name      => 'RFC3164fmt',
      template  => '<%PRI%>%TIMESTAMP% %HOSTNAME% %syslogtag%%msg%',
    },
  ]
}

Logging to multiple remote servers

The remote_servers parameter can be used to set up logging to multiple remote servers which are supplied as a list of key value pairs for each remote. There is an example configuration provided in ./tests/multiple_hosts.pp

Using the remote_servers parameter over-rides the other remote sever parameters, and they will not be used in the client configuration file:

  • log_remote
  • remote_type
  • server
  • port

The following example sets up three remote logging hosts for the client:

class { 'rsyslog::client':
  remote_servers => [
    {
      host => 'logs.example.org',
    },
    {
      port => '55514',
    },
    {
      host      => 'logs.somewhere.com',
      port      => '555',
      pattern   => '*.log',
      protocol  => 'tcp',
      format    => 'RFC3164fmt',
    },
  ]
}

Each host has the following parameters:

  • host: Sets the address or hostname of the remote logging server. Defaults to localhost
  • port: Sets the port the host is listening on. Defaults to 514
  • pattern: Sets the pattern to match logs. Defaults to *.*
  • protocol: Sets the protocol. Only recognises TCP and UDP. Defaults to UDP
  • format: Sets the log format. Defaults to not specifying log format, which defaults to the format set by ActionFileDefaultTemplate in the client configuration.

Logging to a MySQL or PostgreSQL database

Events can also be logged to a MySQL or PostgreSQL database. The database needs to be deployed separately, either locally or remotely. Schema are available from the rsyslog source:

Declare the following to configure the connection:

  class { 'rsyslog::database':
    backend  => 'mysql',
    server   => 'localhost',
    database => 'Syslog',
    username => 'rsyslog',
    password => 'secret',
  }

Server

Using default values

  class { 'rsyslog::server': }

Log filter example (for Hiera)

rsyslog::client::log_filters:
  - expression: '$programname == "foo"'
    action: /var/log/foo.log

Variables and default values

  class { 'rsyslog::server':
    enable_tcp                => true,
    enable_udp                => true,
    enable_relp               => true,
    remote_ruleset_tcp        => true,
    remote_ruleset_udp        => true,
    remote_ruleset_relp       => true,
    enable_onefile            => false,
    relay_server              => false,
    server_dir                => '/srv/log/',
    custom_config             => undef,
    content                   => undef,
    port                      => '514',
    relp_port                 => '20514',
    address                   => '*',
    high_precision_timestamps => false,
    ssl                       => false,
    ssl_ca                    => undef,
    ssl_cert                  => undef,
    ssl_key                   => undef,
    ssl_permitted_peer        => undef,
    ssl_auth_mode             => 'anon',
    log_templates             => false,
    log_filters               => false,
    actionfiletemplate_cust   => false,
    actionfiletemplate        => false,
    rotate                    => undef,
    rules                     => undef
  }

Both can be installed at the same time.

Defining custom rules

The rules parameter can be used to set up custom rules. There is an example configuration provided in ./tests/rules.pp

Using the rules parameter overrides the default rules. Each rule must have a selector and an action.

The following example sets up a server with three rules:

class { '::rsyslog::server':
  rules => [
    {
      selector => 'auth,authpriv.*',
      action   => '?dynAuthLog',
    },
    {
      selector => 'cron.*',
      action   => '?dynCronLog',
    },
    {
      selector => '*.*;auth,authpriv.none,mail.none,cron.none',
      action   => '-?dynSyslog',
    },
  ],
}

Each rule has the following parameters:

  • selector: Sets the selector field of the rule. Defaults to undef
  • action: Sets the action field of the rule. Defaults to undef

PARAMETERS

The following lists all the class parameters this module accepts.

RSYSLOG CLASS PARAMETERS            VALUES              DESCRIPTION
-------------------------------------------------------------------
msg_reduction                       true,false          Reduce repeated messages. Defaults to false.
non_kernel_facility                 true,false          Permit non-kernel facility messages in the kernel log. Defaults to false.
omit_local_logging                  true,false          Turn off message reception via local log socket. Defaults to true only for RedHat 7+ and false elsewhere.
preserve_fqdn                       true,false          Use full name of host even if sender and receiver are in the same domain. Defaults to false.
local_host_name                     STRING              Use a custom local host name, instead of clients actual host name. Defaults to undef.
package_status                      STRING              Manages rsyslog package installation. Defaults to 'present'.
system_log_rate_limit_interval      INTEGER             Specifies the number of seconds per rate limit interval. Defaults to 1.
system_log_rate_limit_burst         INTEGER             Specifies the number of messages before limiting begins. Defaults to 100.

RSYSLOG::SERVER CLASS PARAMETERS    VALUES              DESCRIPTION
-------------------------------------------------------------------
enable_tcp                          true,false          Enable TCP listener. Defaults to true.
enable_udp                          true,false          Enable UDP listener. Defaults to true.
enable_relp                         true,false          Enable RELP listener. Defaults to true (v6.3.6+).
remote_ruleset_tcp                  true,false          Disables the remote ruleset when the TCP listener is enabled.
remote_ruleset_udp                  true,false          Disables the remote ruleset when the UDP listener is enabled.
remote_ruleset_relp                 true,false          Disables the remote ruleset when the RELP listener is enabled.
enable_onefile                      true,false          Only one logfile per remote host. Defaults to false.
relay_server                        true,false          If the server should be able to relay the received logs to another server. The rsyslog::client must also be set up. Defaults to false.
server_dir                          STRING              Folder where logs will be stored on the server. Defaults to '/srv/log/'
custom_config                       STRING              Specify your own template to use for server config. Defaults to undef. Example usage: custom_config => 'rsyslog/my_config.erb'
content                             STRING              Specify the content of the server config, instead of using a template. Defaults to undef.
port                                STRING/INTEGER      Port to listen on for messages via UDP and TCP. Defaults to 514
relp_port                           STRING/INTEGER      Port to listen on for messages via RELP. Defaults to 20514
address                             STRING              The IP address to bind to. Applies to UDP listener only. Defaults to '*'.
high_precision_timestamps           true,false          Whether or not to use high precision timestamps. Defaults to false.
ssl                                 true,false          Enable SSL support. Defaults to false.
ssl_ca                              STRING              Path to SSL CA certificate. Defaults to undef.
ssl_cert                            STRING              Path to SSL certificate. Defaults to undef.
ssl_key                             STRING              Path to SSL private key. Defaults to undef.
ssl_permitted_peer                  STRING              List of permitted peers. Defaults to undef.
ssl_auth_mode                       STRING              SSL auth mode. Defaults to anon.
log_templates                       HASH                Provides a hash defining custom logging templates using the `$template` configuration parameter. Defaults to false.
log_filters                         HASH                Provides a hash defining custom logging filters using the `if/then` configurations parameter. Defaults to false.
actionfiletemplate_cust             STRING              If set this defines the `ActionFileDefaultTemplate custom formatting` which sets customisations over the default log format for remote and local logging. Must be used with actionfiletemplate to take effect. Defaults to false.
actionfiletemplate                  STRING              If set this defines the `ActionFileDefaultTemplate` which sets the default logging format for remote and local logging. Defaults to false.
rotate                              STRING              Enables rotation of logfiles. Valid values: year, month, day. Defaults to undef.
rules                               Array of hashes     Array of hashes for configuring custom rules for the server. If set, this replaces the default rules. See documentation above. Defaults to undef.

RSYSLOG::CLIENT CLASS PARAMETERS    VALUES              DESCRIPTION
-------------------------------------------------------------------
log_remote                          true,false          Log Remotely. Defaults to true.
spool_size                          STRING              Max size for disk queue if remote server failed. Defaults to '1g'.
remote_type                         'tcp','udp','relp'  Which protocol to use when logging remotely. Defaults to 'tcp'.
remote_forward_format               STRING              Which forward format for remote servers should be used. Only used if remote_servers is false.
log_local                           true,false          Log locally. Defaults to false.
log_auth_local                      true,false          Just log auth facility locally. Defaults to false.
split_config                        true,false          Splits the client config into 00_client_config.conf, 50_client_remote.conf and 99_client_local.conf. Defaults to false.
custom_config                       STRING              Specify your own template to use for client config. Defaults to undef. Example usage: custom_config => 'rsyslog/my_config.erb'
custom_params                       TODO                TODO
server                              STRING              Rsyslog server to log to. Will be used in the client configuration file. Only used, if remote_servers is false.
port                                '514'               Remote server port. Only used if remote_servers is false.
remote_servers                      Array of hashes     Array of hashes with remote servers. See documentation above. Defaults to false.
ssl                                 true,false          Enable SSL support. Defaults to false.
ssl_ca                              STRING              SSL CA file location. Defaults to undef.
ssl_cert                            STRING              Path to SSL certificate. Defaults to undef.
ssl_key                             STRING              Path to SSL private key. Defaults to undef.
ssl_permitted_peer                  STRING              List of permitted peers. Defaults to undef.
ssl_auth_mode                       STRING              SSL auth mode. Defaults to anon.
log_templates                       HASH                Provides a hash defining custom logging templates using the `$template` configuration parameter.
log_filters                         HASH                Provides a hash defining custom logging filters using the `if/then` configurations parameter.
actionfiletemplate_cust             STRING              If set this defines the `ActionFileDefaultTemplate custom formatting` which sets customisations over the default log format for remote and local logging. Must be used with actionfiletemplate to take effect. Defaults to false.
actionfiletemplate                  STRING              If set this defines the `ActionFileDefaultTemplate` which sets the default logging format for remote and local logging.
high_precision_timestamps           true,false          Whether or not to use high precision timestamps.

RSYSLOG::DATABASE CLASS PARAMETERS  VALUES              DESCRIPTION
-------------------------------------------------------------------
backend                             'mysql','pgsql'     Database backend (MySQL or PostgreSQL).
server                              STRING              Database server.
database                            STRING              Database name.
username                            STRING              Database username.
password                            STRING              Database password.

Other notes

By default, rsyslog::server will strip numbers from hostnames. This means the logs of multiple servers with the same non-numerical name will be aggregrated in a single directory. i.e. www01 www02 and www02 would all log to the www directory.

To log each host to a seperate directory, set the custom_config parameter to 'rsyslog/server-hostname.conf.erb'

If any of the following parameters are set to false, then the module will not manage the respective package:

gnutls_package_name
relp_package_name
rsyslog_package_name

This can be used when using the adiscon PPA repository, that has merged rsyslog-gnutls with the main rsyslog package.

Default package_status parameter for rsyslog class used to be 'latest'. However, it was against puppet best practices so it defaults to 'present' now.

Relationships

Be sure to make a relationship to the rsyslog class if you need something to happen before or after Puppet manages rsyslog. Even if you're just using rsyslog::client or rsyslog::server.

For example, if you want to make sure the EPEL YUM repositories are managed by Puppet before trying to setup an rsyslog client, do the following:

include epel                       # This is from the stahnma/epel Forge module
include rsyslog::client

Class['epel'] -> Class['rsyslog']  # Note this forms a relationship to rsyslog, not rsyslog::client