README.md 13.9 KB
Newer Older
Tim Smith's avatar
Tim Smith committed
1
# rsyslog Cookbook
Tim Smith's avatar
Tim Smith committed
2

Tim Smith's avatar
Tim Smith committed
3
[![Build Status](https://travis-ci.org/chef-cookbooks/rsyslog.svg?branch=master)](http://travis-ci.org/chef-cookbooks/rsyslog) [![Cookbook Version](https://img.shields.io/cookbook/v/rsyslog.svg)](https://supermarket.chef.io/cookbooks/rsyslog)
Seth Vargo's avatar
Seth Vargo committed
4

Jennifer Davis's avatar
Jennifer Davis committed
5
Installs and configures rsyslog to replace syslogd for client and/or server use. By default, the service will be configured to log to files on local disk. See the Recipes and Examples sections for other uses.
jtimberman's avatar
jtimberman committed
6

Tim Smith's avatar
Tim Smith committed
7
## Requirements
Tim Smith's avatar
Tim Smith committed
8

Tim Smith's avatar
Tim Smith committed
9
### Platforms
Tim Smith's avatar
Tim Smith committed
10

Tim Smith's avatar
Tim Smith committed
11 12
- Debian/Ubuntu
- RHEL/CentOS/Scientific/Amazon/Oracle
13
- Fedora
Jennifer Davis's avatar
Jennifer Davis committed
14
- OpenSUSE
jtimberman's avatar
jtimberman committed
15

Tim Smith's avatar
Tim Smith committed
16
### Chef
Tim Smith's avatar
Tim Smith committed
17

Tim Smith's avatar
Tim Smith committed
18
- Chef 12.7+
Tim Smith's avatar
Tim Smith committed
19

Tim Smith's avatar
Tim Smith committed
20
### Other
Tim Smith's avatar
Tim Smith committed
21 22

To use the `recipe[rsyslog::client]` recipe, you'll need to set up the `rsyslog.server_search` or `rsyslog.server_ip` attributes. See the **Recipes** and **Examples** sections below.
jtimberman's avatar
jtimberman committed
23

Tim Smith's avatar
Tim Smith committed
24
## Attributes
Tim Smith's avatar
Tim Smith committed
25

26
See `attributes/default.rb` for default values.
Tim Smith's avatar
Tim Smith committed
27

Tim Smith's avatar
Tim Smith committed
28 29 30
- `node['rsyslog']['log_dir']` - If the node is an rsyslog server, this specifies the directory where the logs should be stored.
- `node['rsyslog']['working_dir']` - The temporary working directory where messages are buffered
- `node['rsyslog']['server']` - Determined automatically and set to true on the server.
Tim Smith's avatar
Tim Smith committed
31
- `node['rsyslog']['server_ip']` - If not defined then search will be used to determine rsyslog server. Default is `nil`. This can be a string or an array.
Tim Smith's avatar
Tim Smith committed
32 33 34 35 36 37 38
- `node['rsyslog']['server_search']` - Specify the criteria for the server search operation. Default is `role:loghost`.
- `node['rsyslog']['protocol']` - Specify whether to use `udp` or `tcp` for remote loghost. Default is `tcp`. To use both specify both in a string e.g. 'udptcp'.
- `node['rsyslog']['bind']` - Specify the address to which the server should be listening; only use with `node['rsyslog']['protocol'] = 'udp'` because the feature does not work with the `tcp` protocol ([more info](http://www.rsyslog.com/doc/master/configuration/modules/imtcp.html#caveats-known-bugs)).
- `node['rsyslog']['port']` - Specify the port which rsyslog should connect to a remote loghost.
- `node['rsyslog']['remote_logs']` - Specify whether to send all logs to a remote server (client option). Default is `true`.
- `node['rsyslog']['per_host_dir']` - "PerHost" directories for template statements in `35-server-per-host.conf`. Default value is the previous cookbook version's value, to preserve compatibility. See **server** recipe below.
- `node['rsyslog']['priv_seperation']` - Whether to use privilege separation or not.
Tim Smith's avatar
Tim Smith committed
39 40
- `node['rsyslog']['priv_user']` - User to run as when using privilege separation. Defult is `node['rsyslog']['user']`
- `node['rsyslog']['priv_group']` - Group to run as when using privilege separation. Defult is `node['rsyslog']['group']`
Tim Smith's avatar
Tim Smith committed
41 42 43
- `node['rsyslog']['max_message_size']` - Specify the maximum allowed message size. Default is 2k.
- `node['rsyslog']['user']` - Who should own the configuration files and directories
- `node['rsyslog']['group']` - Who should group-own the configuration files and directories
Richard Mcleod's avatar
Richard Mcleod committed
44 45 46 47 48
- `node['rsyslog']['dir_owner']` - Who should own the log directories
- `node['rsyslog']['dir_group']` - Who should group-own the log directories
- `node['rsyslog']['file_create_mode']` - Mode that should be set when creating log files
- `node['rsyslog']['dir_create_mode']` - Mode that should be set when creating log directories
- `node['rsyslog']['umask']` - Specify the processes umask
Tim Smith's avatar
Tim Smith committed
49
- `node['rsyslog']['defaults_file']` - The full path to the defaults/sysconfig file for the service.
Aivaras Laimikis's avatar
Aivaras Laimikis committed
50
- `node['rsyslog']['package_name']` - Specify rsyslog package name
Tim Smith's avatar
Tim Smith committed
51 52
- `node['rsyslog']['service_name']` - The platform-specific name of the service
- `node['rsyslog']['preserve_fqdn']` - Value of the `$PreserveFQDN` configuration directive in `/etc/rsyslog.conf`. Default is 'off' for compatibility purposes.
Tim Smith's avatar
Tim Smith committed
53 54 55
- `node['rsyslog']['high_precision_timestamps']` - Enable high precision timestamps, instead of the "old style" format. Default is 'false'.
- `node['rsyslog']['repeated_msg_reduction']` - Value of `$RepeatedMsgReduction` configuration directive in `/etc/rsyslog.conf`. Default is 'on'
- `node['rsyslog']['logs_to_forward']` - Specifies what logs should be sent to the remote rsyslog server. Default is all ( _._ ).
Tim Smith's avatar
Tim Smith committed
56 57 58 59
- `node['rsyslog']['default_log_dir']` - log directory used in `50-default.conf` template, defaults to `/var/log`
- `node['rsyslog']['default_facility_logs']` - Hash containing log facilities and destinations used in `50-default.conf` template.
- `node['rsyslog']['default_file_template']` - The name of a pre-defined log format template (ie - RSYSLOG_FileFormat), used for local log files.
- `node['rsyslog']['default_remote_template']` - The name of a pre-defined log format template (ie - RSYSLOG_FileFormat), used for sending to remote servers.
Richard Mcleod's avatar
Richard Mcleod committed
60
- `node['rsyslog']['templates']` - Allows a user to specify a dynamic filename and the format of the logs
Tim Smith's avatar
Tim Smith committed
61 62 63
- `node['rsyslog']['rate_limit_interval']` - Value of the $SystemLogRateLimitInterval configuration directive in `/etc/rsyslog.conf`. Default is nil, leaving it to the platform default.
- `node['rsyslog']['rate_limit_burst']` - Value of the $SystemLogRateLimitBurst configuration directive in `/etc/rsyslog.conf`. Default is nil, leaving it to the platform default.
- `node['rsyslog']['action_queue_max_disk_space']` - Max amount of disk space the disk-assisted queue is allowed to use ([more info](http://www.rsyslog.com/doc/queues.html)).
Tim Smith's avatar
Tim Smith committed
64
- `node['rsyslog']['enable_tls']` - Whether or not to enable TLS encryption. When enabled, forces protocol to `tcp`. Default is `false`.
Tim Smith's avatar
Tim Smith committed
65 66 67 68
- `node['rsyslog']['tls_ca_file']` - Path to TLS CA file. Required for both server and clients.
- `node['rsyslog']['tls_certificate_file']` - Path to TLS certificate file. Required for server, optional for clients.
- `node['rsyslog']['tls_key_file']` - Path to TLS key file. Required for server, optional for clients.
- `node['rsyslog']['tls_auth_mode']` - Value for `$InputTCPServerStreamDriverAuthMode`/`$ActionSendStreamDriverAuthMode`, determines whether client certs are validated. Defaults to `anon` (no validation).
Jennifer Davis's avatar
Jennifer Davis committed
69
- `node['rsyslog']['tls_permitted_peer']` - Value for `ActionSendStreamDriverPermittedPeer`, it narrows the list of the allowed hosts. Works with TLS only. Defaults to `nil`.
Tim Smith's avatar
Tim Smith committed
70 71
- `node['rsyslog']['use_local_ipv4']` - Whether or not to make use the remote local IPv4 address on cloud systems when searching for servers (where available). Default is 'false'.
- `node['rsyslog']['allow_non_local']` - Whether or not to allow non-local messages. If 'false', incoming messages are only allowed from 127.0.0.1\. Default is 'false'.
Tim Smith's avatar
Tim Smith committed
72 73
- `node['rsyslog']['custom_remote']` - Array of hashes for configuring custom remote server targets
- `node['rsyslog']['additional_directives']` - Hash of additional directives and their values to place in the main rsyslog config file
Tim Smith's avatar
Tim Smith committed
74
- `node['rsyslog']['local_host_name']` - permits to overwrite the system hostname with the one specified in the directive
75
- `node['rsyslog']['default_conf_file']` - If false it skips the creation of default configuration file 50-default.conf
Tim Smith's avatar
Tim Smith committed
76 77

## Recipes
Tim Smith's avatar
Tim Smith committed
78

Seth Vargo's avatar
Seth Vargo committed
79
### default
Tim Smith's avatar
Tim Smith committed
80

Seth Vargo's avatar
Seth Vargo committed
81
Installs the rsyslog package, manages the rsyslog service and sets up basic configuration for a standalone machine.
82

Seth Vargo's avatar
Seth Vargo committed
83
### client
Tim Smith's avatar
Tim Smith committed
84

85 86
Includes `recipe[rsyslog]`.

Seth Vargo's avatar
Seth Vargo committed
87
Uses `node['rsyslog']['server_ip']` or Chef search (in that precedence order) to determine the remote syslog server's IP address. If search is used, the search query will look for the first `ipaddress` returned from the criteria specified in `node['rsyslog']['server_search']`.
Jeff Blaine's avatar
Jeff Blaine committed
88

Tim Smith's avatar
Tim Smith committed
89 90
You can use `node['rsyslog']['custom_config']` to define custom entries for sending logs to remote servers. Available attributes:

91 92 93 94 95
```
    'server': Ip/hostname of remote syslog server (Required)
    'port': Port to send logs to
    'logs': Syslog log facilities to send (auth, authpriv, daemon, etc)
    'protocol': Can be tcp or udp
Tim Smith's avatar
Tim Smith committed
96
    'remote_template': Rsyslog template used for the messages
97 98 99 100 101 102 103 104 105 106 107
```

Example:

```ruby
node['rsyslog']['custom_remote'] = [{ 'server' => '10.10.4.4', 'port' => '567', 'logs' => 'auth.*,mail.*', 'protocol' => 'udp', 'remote_template' => 'RSYSLOG_SyslogProtocol23Format'},
                                    { 'server' => '10.0.0.3', 'port' => '555', 'logs' => 'authpriv,daemon.*' } ]
```

The server key is required; if other keys are left out, the default global values will be used (eg `node['rsyslog']['port']` will be used if 'port' is omitted)

Seth Vargo's avatar
Seth Vargo committed
108
If the node itself is a rsyslog server ie it has `rsyslog.server` set to true then the configuration is skipped.
Jeff Blaine's avatar
Jeff Blaine committed
109

Seth Vargo's avatar
Seth Vargo committed
110
If the node had an `/etc/rsyslog.d/35-server-per-host.conf` file previously configured, this file gets removed to prevent duplicate logging.
Jeff Blaine's avatar
Jeff Blaine committed
111 112

Any previous logs are not cleaned up from the `log_dir`.
113

Seth Vargo's avatar
Seth Vargo committed
114
### server
Tim Smith's avatar
Tim Smith committed
115

Seth Vargo's avatar
Seth Vargo committed
116
Configures the node to be a rsyslog server. The chosen rsyslog server node should be defined in the `server_ip` attribute or resolvable by the specified search criteria specified in `node['rsyslog']['server_search]` (so that nodes making use of the `client` recipe can find the server to log to).
Jeff Blaine's avatar
Jeff Blaine committed
117

Jennifer Davis's avatar
Jennifer Davis committed
118
The `server` recipe will create the logs in attribute `node['rsyslog']['log_dir']`, and the configuration in `/etc/rsyslog.d/server.conf`. This recipe also removes any previous configuration to a remote server by removing the file `/etc/rsyslog.d/49-remote.conf`.
jtimberman's avatar
jtimberman committed
119

Seth Vargo's avatar
Seth Vargo committed
120
The cron job used in the previous version of this cookbook is removed, but it does not remove any existing cron job from your system (so it doesn't break anything unexpectedly). We recommend setting up logrotate for the logfiles instead.
jtimberman's avatar
jtimberman committed
121

Seth Vargo's avatar
Seth Vargo committed
122
The `log_dir` will be concatenated with `per_host_dir` to store the logs for each client. Modify the attribute to have a value that is allowed by rsyslogs template matching values, see the rsyslog documentation for this.
123

124
Directory structure:
125

Seth Vargo's avatar
Seth Vargo committed
126 127 128
```erb
<%= @log_dir %>/<%= @per_host_dir %>/"logfile"
```
jtimberman's avatar
jtimberman committed
129 130

For example for the system with hostname `www`:
131

Seth Vargo's avatar
Seth Vargo committed
132 133 134
```text
/srv/rsyslog/2011/11/19/www/messages
```
jtimberman's avatar
jtimberman committed
135

Seth Vargo's avatar
Seth Vargo committed
136
For example, to change this to just the hostname, set the attribute `node['rsyslog']['per_host_dir']` via a role:
jtimberman's avatar
jtimberman committed
137

Seth Vargo's avatar
Seth Vargo committed
138 139 140
```ruby
"rsyslog" => { "per_host_dir" => "%HOSTNAME%" }
```
141

Tim Smith's avatar
Tim Smith committed
142
At this time, the server can only listen on UDP _or_ TCP.
143

Tim Smith's avatar
Tim Smith committed
144
# Resources
Tim Smith's avatar
Tim Smith committed
145

Tim Smith's avatar
Tim Smith committed
146
## file_input
Tim Smith's avatar
Tim Smith committed
147 148

Configures a [text file input monitor](http://www.rsyslog.com/doc/imfile.html) to push a log file into rsyslog. Rsyslog must be installed to use this custom resource either using your own wrapper cookbook or the rsyslog::default recipe
149

150
Properties:
Tim Smith's avatar
Tim Smith committed
151

Tim Smith's avatar
Tim Smith committed
152 153 154 155 156 157 158 159 160 161 162 163 164 165
- `name`: name of the resource, also used for the syslog tag. Required.
- `file`: file path for input file to monitor. Required.
- `priority`: config order priority. Defaults to `99`.
- `severity`: syslog severity. Must be one of `emergency`, `alert`,
- `critical`, `error`, `warning`, `notice`, `info` or `debug`. If
- undefined, rsyslog interprets this as `notice`.
- `facility`: syslog facility. Must be one of `auth`, `authpriv`,
- `daemon`, `cron`, `ftp`, `lpr`, `kern`, `mail`, `news`, `syslog`,
- `user`, `uucp`, `local0`, ... , `local7`. If undefined, rsyslog
- interprets this as `local0`.
- `cookbook_source`: cookbook containing the template. Defaults to `rsyslog`.
- `template_source`: template file source. Defaults to `file-input.conf.erb`

# Usage
Tim Smith's avatar
Tim Smith committed
166

Seth Vargo's avatar
Seth Vargo committed
167
Use `recipe[rsyslog]` to install and start rsyslog as a basic configured service for standalone systems.
jtimberman's avatar
jtimberman committed
168

Tim Smith's avatar
Tim Smith committed
169
Use `recipe[rsyslog::client]` to have nodes log to a remote server (which is found via the `server_ip` attribute or by the recipe's search call -- see **client**)
jtimberman's avatar
jtimberman committed
170

Seth Vargo's avatar
Seth Vargo committed
171
Use `recipe[rsyslog::server]` to set up a rsyslog server. It will listen on `node['rsyslog']['port']` protocol `node['rsyslog']['protocol']`.
jtimberman's avatar
jtimberman committed
172

Tim Smith's avatar
Tim Smith committed
173
If you set up a different kind of centralized loghost (syslog-ng, graylog2, logstash, etc), you can still send log messages to it as long as the port and protocol match up with the server software. See **Examples**
174

Tim Smith's avatar
Tim Smith committed
175
Use `rsyslog_file_input` within your recipes to forward log files to your remote syslog server.
jtimberman's avatar
jtimberman committed
176

Tim Smith's avatar
Tim Smith committed
177
## Examples
Tim Smith's avatar
Tim Smith committed
178

179
A `base` role (e.g., roles/base.rb), applied to all nodes so they are syslog clients:
jtimberman's avatar
jtimberman committed
180

Seth Vargo's avatar
Seth Vargo committed
181 182 183 184 185
```ruby
name "base"
description "Base role applied to all nodes
run_list("recipe[rsyslog::client]")
```
jtimberman's avatar
jtimberman committed
186

187
Then, a role for the loghost (should only be one):
jtimberman's avatar
jtimberman committed
188

Seth Vargo's avatar
Seth Vargo committed
189 190 191 192 193
```ruby
name "loghost"
description "Central syslog server"
run_list("recipe[rsyslog::server]")
```
194

Tim Smith's avatar
Tim Smith committed
195
By default this will set up the clients search for a node with the `loghost` role to talk to the server on TCP port 514\. Change the `protocol` and `port` rsyslog attributes to modify this.
196

Seth Vargo's avatar
Seth Vargo committed
197
If you want to specify another syslog compatible server with a role other than loghost, simply fill free to use the `server_ip` attribute or the `server_search` attribute.
198

jtimberman's avatar
jtimberman committed
199 200
Example role that sets the per host directory:

Seth Vargo's avatar
Seth Vargo committed
201 202 203 204 205 206 207 208 209
```ruby
name "loghost"
description "Central syslog server"
run_list("recipe[rsyslog::server]")
default_attributes(
  "rsyslog" => { "per_host_dir" => "%HOSTNAME%" }
)
```

Tim Smith's avatar
Tim Smith committed
210
Default rsyslog options are rendered for RHEL family platforms, in `/etc/rsyslog.d/50-default.conf` with other platforms using a configuration like Debian family defaults. You can override these log facilities and destinations using the `rsyslog['default_facility_logs']` hash.
211 212 213 214 215 216

```ruby
name "facility_log_example"
run_list("recipe[rsyslog::default]")
default_attributes(
  "rsyslog" => {
217
    "default_facility_logs" => {
218 219 220 221 222 223 224 225
      '*.info;mail.none;authpriv.none;cron.none' => "/var/log/messages",
      'authpriv' => '/var/log/secure',
      'mail.*' => '-/var/log/maillog',
      '*.emerg' => '*'
    }
  }
)
```
226

Tim Smith's avatar
Tim Smith committed
227
## License & Authors
Tim Smith's avatar
Tim Smith committed
228

Tim Smith's avatar
Tim Smith committed
229 230 231
- Author:: Joshua Timberman ([joshua@chef.io](mailto:joshua@chef.io))
- Author:: Denis Barishev ([denz@twiket.com](mailto:denz@twiket.com))
- Author:: Tim Smith ([tsmith@chef.io](mailto:tsmith@chef.io))
Seth Vargo's avatar
Seth Vargo committed
232 233

```text
234
Copyright:: 2009-2017, Chef Software, Inc
jtimberman's avatar
jtimberman committed
235 236 237 238 239 240 241 242 243 244 245 246

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Seth Vargo's avatar
Seth Vargo committed
247
```