summaryrefslogtreecommitdiff
path: root/cloudinit/config/cc_rsyslog.py
diff options
context:
space:
mode:
authorWesley Wiedenmeier <wesley.wiedenmeier@gmail.com>2016-08-28 17:56:17 -0500
committerScott Moser <smoser@brickies.net>2016-09-30 13:21:00 -0400
commit1071b9940b4e114cd2eabf290b739f92fbab33de (patch)
treea8fbef15c5be9510df93b4544e3bca1f74e2f29a /cloudinit/config/cc_rsyslog.py
parent02f6c4bb8cef17b3fe04ef4dc1ef199e20aeb4d9 (diff)
downloadvyos-cloud-init-1071b9940b4e114cd2eabf290b739f92fbab33de.tar.gz
vyos-cloud-init-1071b9940b4e114cd2eabf290b739f92fbab33de.zip
Improve module documentation and doc cleanup.
This adds lots of config module documentation in a standard format. It will greatly improve the content at readthedocs. Additionally: * Add a 'doc' env to tox.ini * Changed default highlight language for sphinx conf from python to yaml most examples in documentation are yaml configs * Updated datasource examples to highlight sh code properly
Diffstat (limited to 'cloudinit/config/cc_rsyslog.py')
-rw-r--r--cloudinit/config/cc_rsyslog.py249
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