GitLab upgraded to 14.4.0-ee.0 - changelog: https://gitlab.com/gitlab-org/gitlab/blob/master/CHANGELOG-EE.md

Commit 51317877 authored by Tim Smith's avatar Tim Smith
Browse files

Format markdown


Signed-off-by: default avatarTim Smith <tsmith@chef.io>
parent 16595dfa
# rsyslog Cookbook
[![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)
Installs and configures rsyslog to replace sysklogd 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.
## Requirements
### Platforms
- Debian/Ubuntu
- RHEL/CentOS/Scientific/Amazon/Oracle
- Fedora
......@@ -12,20 +15,25 @@ Installs and configures rsyslog to replace sysklogd for client and/or server use
- OpenSUSE
### Chef
- Chef 12.1+
### Cookbooks
- compat_resource
### Other
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.
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.
## Attributes
See `attributes/default.rb` for default values.
- `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.
- `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.
- `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.
- `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)).
......@@ -33,8 +41,8 @@ See `attributes/default.rb` for default values.
- `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.
- `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']`
- `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']`
- `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
......@@ -46,9 +54,9 @@ See `attributes/default.rb` for default values.
- `node['rsyslog']['defaults_file']` - The full path to the defaults/sysconfig file for the service.
- `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.
- `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 ( *.* ).
- `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 ( _._ ).
- `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.
......@@ -57,23 +65,26 @@ See `attributes/default.rb` for default values.
- `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)).
- `node['rsyslog']['enable_tls']` - Whether or not to enable TLS encryption. When enabled, forces protocol to `tcp`. Default is `false`.
- `node['rsyslog']['enable_tls']` - Whether or not to enable TLS encryption. When enabled, forces protocol to `tcp`. Default is `false`.
- `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).
- `node['rsyslog']['tls_permitted_peer']` - Value for `ActionSendStreamDriverPermittedPeer`, it narrows the list of the allowed hosts. Works with TLS only. Defaults to `nil`.
- `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'.
- `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'.
- `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
- `node['rsyslog']['local_host_name']` - permits to overwrite the system hostname with the one specified in the directive
- `node['rsyslog']['local_host_name']` - permits to overwrite the system hostname with the one specified in the directive
## Recipes
### default
Installs the rsyslog package, manages the rsyslog service and sets up basic configuration for a standalone machine.
### client
Includes `recipe[rsyslog]`.
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']`.
......@@ -104,6 +115,7 @@ If the node had an `/etc/rsyslog.d/35-server-per-host.conf` file previously conf
Any previous logs are not cleaned up from the `log_dir`.
### server
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).
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`.
......@@ -133,10 +145,13 @@ For example, to change this to just the hostname, set the attribute `node['rsysl
At this time, the server can only listen on UDP _or_ TCP.
# Resources
## file_input
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
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
Properties:
- `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`.
......@@ -151,6 +166,7 @@ Properties:
- `template_source`: template file source. Defaults to `file-input.conf.erb`
# Usage
Use `recipe[rsyslog]` to install and start rsyslog as a basic configured service for standalone systems.
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**)
......@@ -162,6 +178,7 @@ If you set up a different kind of centralized loghost (syslog-ng, graylog2, logs
Use `rsyslog_file_input` within your recipes to forward log files to your remote syslog server.
## Examples
A `base` role (e.g., roles/base.rb), applied to all nodes so they are syslog clients:
```ruby
......@@ -178,7 +195,7 @@ description "Central syslog server"
run_list("recipe[rsyslog::server]")
```
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.
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.
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.
......@@ -193,7 +210,7 @@ default_attributes(
)
```
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.
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.
```ruby
name "facility_log_example"
......@@ -211,6 +228,7 @@ default_attributes(
```
## License & Authors
- 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))
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment