diff options
Diffstat (limited to 'cloudinit/config/cc_rsyslog.py')
| -rw-r--r-- | cloudinit/config/cc_rsyslog.py | 249 |
1 files changed, 167 insertions, 82 deletions
diff --git a/cloudinit/config/cc_rsyslog.py b/cloudinit/config/cc_rsyslog.py index b8642d65..48f18620 100644 --- a/cloudinit/config/cc_rsyslog.py +++ b/cloudinit/config/cc_rsyslog.py @@ -18,90 +18,175 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see <http://www.gnu.org/licenses/>. """ -rsyslog module allows configuration of syslog logging via rsyslog -Configuration is done under the cloud-config top level 'rsyslog'. - -Under 'rsyslog' you can define: - - configs: [default=[]] - this is a list. entries in it are a string or a dictionary. - each entry has 2 parts: - * content - * filename - if the entry is a string, then it is assigned to 'content'. - for each entry, content is written to the provided filename. - if filename is not provided, its default is read from 'config_filename' - - Content here can be any valid rsyslog configuration. No format - specific format is enforced. - - For simply logging to an existing remote syslog server, via udp: - configs: ["*.* @192.168.1.1"] - - - remotes: [default={}] - This is a dictionary of name / value pairs. - In comparison to 'config's, it is more focused in that it only supports - remote syslog configuration. It is not rsyslog specific, and could - convert to other syslog implementations. - - Each entry in remotes is a 'name' and a 'value'. - * name: an string identifying the entry. good practice would indicate - using a consistent and identifiable string for the producer. - For example, the MAAS service could use 'maas' as the key. - * value consists of the following parts: - * optional filter for log messages - default if not present: *.* - * optional leading '@' or '@@' (indicates udp or tcp respectively). - default if not present (udp): @ - This is rsyslog format for that. if not present, is '@'. - * ipv4 or ipv6 or hostname - ipv6 addresses must be in [::1] format. (@[fd00::1]:514) - * optional port - port defaults to 514 - - - config_filename: [default=20-cloud-config.conf] - this is the file name to use if none is provided in a config entry. - - - config_dir: [default=/etc/rsyslog.d] - this directory is used for filenames that are not absolute paths. - - - service_reload_command: [default="auto"] - this command is executed if files have been written and thus the syslog - daemon needs to be told. - -Note, since cloud-init 0.5 a legacy version of rsyslog config has been -present and is still supported. See below for the mappings between old -value and new value: - old value -> new value - 'rsyslog' -> rsyslog/configs - 'rsyslog_filename' -> rsyslog/config_filename - 'rsyslog_dir' -> rsyslog/config_dir - -the legacy config does not support 'service_reload_command'. - -Example config: - #cloud-config - rsyslog: - configs: - - "*.* @@192.158.1.1" - - content: "*.* @@192.0.2.1:10514" - filename: 01-example.conf - - content: | - *.* @@syslogd.example.com - remotes: - maas: "192.168.1.1" - juju: "10.0.4.1" - config_dir: config_dir - config_filename: config_filename - service_reload_command: [your, syslog, restart, command] - -Example Legacy config: - #cloud-config - rsyslog: - - "*.* @@192.158.1.1" - rsyslog_dir: /etc/rsyslog-config.d/ - rsyslog_filename: 99-local.conf +Rsyslog +------- +**Summary:** configure system loggig via rsyslog + +This module configures remote system logging using rsyslog. + +The rsyslog config file to write to can be specified in ``config_filename``, +which defaults to ``20-cloud-config.conf``. The rsyslog config directory to +write config files to may be specified in ``config_dir``, which defaults to +``/etc/rsyslog.d``. + +A list of configurations for for rsyslog can be specified under the ``configs`` +key in the ``rsyslog`` config. Each entry in ``configs`` is either a string or +a dictionary. Each config entry contains a configuration string and a file to +write it to. For config entries that are a dictionary, ``filename`` sets the +target filename and ``content`` specifies the config string to write. For +config entries that are only a string, the string is used as the config string +to write. If the filename to write the config to is not specified, the value of +the ``config_filename`` key is used. A file with the selected filename will +be written inside the directory specified by ``config_dir``. + +The command to use to reload the rsyslog service after the config has been +updated can be specified in ``service_reload_command``. If this is set to +``auto``, then an appropriate command for the distro will be used. This is the +default behavior. To manually set the command, use a list of command args (e.g. +``[systemctl, restart, rsyslog]``). + +Configuration for remote servers can be specified in ``configs``, but for +convenience it can be specified as key value pairs in ``remotes``. Each key +is the name for an rsyslog remote entry. Each value holds the contents of the +remote config for rsyslog. The config consists of the following parts: + + - filter for log messages (defaults to ``*.*``) + - optional leading ``@`` or ``@@``, indicating udp and tcp respectively + (defaults to ``@``, for udp) + - ipv4 or ipv6 hostname or address. ipv6 addresses must be in ``[::1]`` + format, (e.g. ``@[fd00::1]:514``) + - optional port number (defaults to ``514``) + +This module will provide sane defaults for any part of the remote entry that is +not specified, so in most cases remote hosts can be specified just using +``<name>: <address>``. + +For backwards compatibility, this module still supports legacy names for the +config entries. Legacy to new mappings are as follows: + + - ``rsyslog`` -> ``rsyslog/configs`` + - ``rsyslog_filename`` -> ``rsyslog/config_filename`` + - ``rsyslog_dir`` -> ``rsyslog/config_dir`` + +.. note:: + The legacy config format does not support specifying + ``service_reload_command``. + +**Internal name:** ``cc_rsyslog`` + +**Module frequency:** per instance + +**Supported distros:** all + +**Config keys**:: + + rsyslog: + config_dir: config_dir + config_filename: config_filename + configs: + - "*.* @@192.158.1.1" + - content: "*.* @@192.0.2.1:10514" + filename: 01-example.conf + - content: | + *.* @@syslogd.example.com + remotes: + maas: "192.168.1.1" + juju: "10.0.4.1" + service_reload_command: [your, syslog, restart, command] + +**Legacy config keys**:: + + rsyslog: + - "*.* @@192.158.1.1" + rsyslog_dir: /etc/rsyslog-config.d/ + rsyslog_filename: 99-local.conf """ +# Old rsyslog documentation, kept for reference: +# +# rsyslog module allows configuration of syslog logging via rsyslog +# Configuration is done under the cloud-config top level 'rsyslog'. +# +# Under 'rsyslog' you can define: +# - configs: [default=[]] +# this is a list. entries in it are a string or a dictionary. +# each entry has 2 parts: +# * content +# * filename +# if the entry is a string, then it is assigned to 'content'. +# for each entry, content is written to the provided filename. +# if filename is not provided, its default is read from 'config_filename' +# +# Content here can be any valid rsyslog configuration. No format +# specific format is enforced. +# +# For simply logging to an existing remote syslog server, via udp: +# configs: ["*.* @192.168.1.1"] +# +# - remotes: [default={}] +# This is a dictionary of name / value pairs. +# In comparison to 'config's, it is more focused in that it only supports +# remote syslog configuration. It is not rsyslog specific, and could +# convert to other syslog implementations. +# +# Each entry in remotes is a 'name' and a 'value'. +# * name: an string identifying the entry. good practice would indicate +# using a consistent and identifiable string for the producer. +# For example, the MAAS service could use 'maas' as the key. +# * value consists of the following parts: +# * optional filter for log messages +# default if not present: *.* +# * optional leading '@' or '@@' (indicates udp or tcp respectively). +# default if not present (udp): @ +# This is rsyslog format for that. if not present, is '@'. +# * ipv4 or ipv6 or hostname +# ipv6 addresses must be in [::1] format. (@[fd00::1]:514) +# * optional port +# port defaults to 514 +# +# - config_filename: [default=20-cloud-config.conf] +# this is the file name to use if none is provided in a config entry. +# +# - config_dir: [default=/etc/rsyslog.d] +# this directory is used for filenames that are not absolute paths. +# +# - service_reload_command: [default="auto"] +# this command is executed if files have been written and thus the syslog +# daemon needs to be told. +# +# Note, since cloud-init 0.5 a legacy version of rsyslog config has been +# present and is still supported. See below for the mappings between old +# value and new value: +# old value -> new value +# 'rsyslog' -> rsyslog/configs +# 'rsyslog_filename' -> rsyslog/config_filename +# 'rsyslog_dir' -> rsyslog/config_dir +# +# the legacy config does not support 'service_reload_command'. +# +# Example config: +# #cloud-config +# rsyslog: +# configs: +# - "*.* @@192.158.1.1" +# - content: "*.* @@192.0.2.1:10514" +# filename: 01-example.conf +# - content: | +# *.* @@syslogd.example.com +# remotes: +# maas: "192.168.1.1" +# juju: "10.0.4.1" +# config_dir: config_dir +# config_filename: config_filename +# service_reload_command: [your, syslog, restart, command] +# +# Example Legacy config: +# #cloud-config +# rsyslog: +# - "*.* @@192.158.1.1" +# rsyslog_dir: /etc/rsyslog-config.d/ +# rsyslog_filename: 99-local.conf + import os import re import six |