Skip to content

Latest commit

 

History

History
302 lines (233 loc) · 9.87 KB

README.md

File metadata and controls

302 lines (233 loc) · 9.87 KB
Raw

#pupmod-simp-rsyslog

License CII Best Practices Puppet Forge Puppet Forge Downloads Build Status

Table of Contents

Overview

pupmod-simp-rsyslog configures and manages RSyslog version 8 as built into either RHEL or CentOS versions 7 and 8.

This is a SIMP module

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.

If you find any issues, they can be submitted to our JIRA.

Module Description

This module follows the standard PuppetLabs module style guide with some SIMP-specific configuration items included for managing auditing, firewall rules, logging, SELinux, and TCPWrappers. All of these items are configurable and can be turned on or off as needed for each user environment.

pupmod-simp-rsyslog was designed to be as compatible with RSyslog v8-stable as possible, though the version that comes stock with RHEL or CentOS is slightly dated.

It is possible to use pupmod-simp-rsyslog on its own and configure all rules and settings as you like, but it is recommended that the SIMP Rsyslog Profile be used if possible. By default, this profile will setup security relevant logging rules and manage server/client configurations.

Setup

What pupmod-simp-rsyslog affects

Files managed by pupmod-simp-rsyslog:

  • /etc/rsyslog.conf
  • /etc/rsyslog.simp.d

In addition to these, the rsyslog::rule::<all> definitions will create numbered directories in the $rsyslog_rule_dir, by default /etc/rsyslog.simp.d. These directories are included in alphanumeric order and using the rsyslog::rule definition, the user can specify any directory name they want to impact order.

Services and operations managed or affected by pupmod-simp-rsyslog:

  • rsyslogd
  • auditd (configurable)
  • firewall (configurable)
    • NOTE: If firewall management is enabled, and you are using iptables (not firewalld), then you MUST set iptables::precise_match: true in Hiera.
  • TCPWrappers (configurable)
  • SELinux (configurable)
  • Logrotate (configurable)

Packages installed by pupmod-simp-rsyslog:

  • rsyslog
  • rsyslog-gnutls

Setup Requirements

It is strongly recommended that the logging infrastructure be set up in a resilient manner. Failover in RSyslog is tricky and choosing the wrong kind of queuing with failover could mean losing logs. This module attempts to protect you from that, but will allow you to change the queuing mechanism to meet your local requirements.

Beginning with pupmod-simp-rsyslog

Including rsyslog will install, configure, and start the rsyslog daemon on a client:

Puppet Code:

include rsyslog

Including rsyslog::server will additionally configure the system as an Rsyslog server.

Puppet Code:

include rsyslog::server

Usage

WARNING: The version of rsyslog that is included with EL7 and EL8 systems is not the final stable upstream release. In particular, TLS may only be enabled or disabled globally, not per ruleset or action!

pupmod-simp-rsyslog is meant to be extremely customizable, and as such there is no single best way to use it. For the SIMP specific recommendations on how to use RSyslog (and other modules as well), check out the SIMP profile.

I want standard remote logging on a client

An example of an RSyslog client configuration may look like the following, including possible file names and a simple remote rule to forward all logs on the system.

Hiera Config:

# Send to *all* of these servers!
log_servers:
  - 'first.log.server'
  - 'second.log.server'
failover_log_servers:
  - 'first-failover.log.server'
  - 'second-failover.log.server'

Puppet Code:

include rsyslog

I want to send everything to rsyslog from a client

NOTE: Everything must be in the form that would be in the middle of an if/then Rainerscript Expression.

For example, if you wanted to filter on the standard priority kern.err, you would put prifilt('kern.err') in your rule parameter.

This does not hold for a call to rsyslog::rule since that is the generic processor for all rules.

Hiera Config:

rsyslog::log_servers:
  - 'first.log.server'
  - 'second.log.server'

rsyslog::failover_log_servers:
  - 'first.log.server'
  - 'second.log.server'

Puppet Code:

class my_rsyslog_client {
  rsyslog::rule::remote { 'send_the_logs':
    rule => 'prifilt(\'*.*\')'
  }
}

I want to disable TLS/PKI/Logrotate

Hiera Config:

rsyslog::log_servers:
  - 'first.log.server'
  - 'second.log.server'

rsyslog::failover_log_servers:
  - 'first.log.server'
  - 'second.log.server'

rsyslog::enable_tls_logging: false
rsyslog::logrotate: false
rsyslog::pki: false

I want to set up an RSyslog Server

Hiera Config:

rsyslog::log_servers:
  - 'first.log.server'
  - 'second.log.server'

rsyslog::failover_log_servers:
  - 'first.log.server'
  - 'second.log.server'

Puppet Code:

class my_rsyslog_server {
  include rsyslog::server

  rsyslog::template::string { 'store_the_logs':
    string => '/var/log/hosts/%HOSTNAME%/everything.log'
  }
}

Using the above, all possible logs sent from the client will be stored on the server in a single log file. Obviously, this is not always an effective strategy, but it is at least enough to get started. Further customizations can be built to help manage more logs appropriately. To learn more about how to use the templates and rules, feel free to browse through the code.

While this setup does cover all of the basics, using the SIMP suggested RSyslog profile will setup templates and a large set of default rules to help organize and send logs where possible. Included would also be a comprehensive set of security relevant logs to help filter important information.

I want to set up an Rsyslog Server without logrotate/pki/firewall/tcpwrappers

Hiera Config:

  rsyslog::logrotate: false
  rsyslog::server::enable_firewall: false
  rsyslog::server::enable_selinux: false
  rsyslog::server::enable_tcpwrappers: false

Central Log Forwarding

Following on from the first example, you may have an upstream server to which you want to send all logs from your collected hosts.

To do this, you would use a manifest similar to the following on your local log server to forward everything upstream. Note, the use of a custom template. Upstream systems may have their own requirements and this allows you to manipulate the log appropriately prior to forwarding the message along.

Puppet Code:

rsyslog::template::string { 'upstream':
  string => 'I Love Logs! %msg%\n'
}

rsyslog::rule::remote { 'upstream':
  # Send Everything
  rule     => 'prifilt(\'*.*\')',
  # Use the 'upstream' template defined above
  template => 'upstream',
  # The Upstream Destination Server
  dest     => ['upstream.fq.dn'],
  require  => Rsyslog::Template::String['upstream']
}

Reference

Please refer to the REFERENCE.md.

Limitations

SIMP Puppet modules are generally intended for use on Red Hat Enterprise Linux and compatible distributions, such as CentOS. Please see the metadata.json file for the most up-to-date list of supported operating systems, Puppet versions, and module dependencies.

By default, pupmod-simp-rsyslog tries to do the right thing during a failover scenario and make sure that logs are always stored no matter what the state of the remote log server(s) is. Be careful if you opt out of the default queuing strategy for failover as it may cause undesirable results such as lost logs.

Development

Please read our Contribution Guide.

If you find any issues, they can be submitted to our JIRA.

System Integrity Management Platform