valitydev/salt
14
0
Fork 0
mirror of https://github.com/valitydev/salt.git synced 2024-11-07 17:09:03 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
d228fb6e02
salt/doc/topics/tutorials/syslog_ng-state-usage.rst
rallytime 6e32267d0c Remove ":doc:" references in salt/* files
2016-12-15 14:03:56 -07:00

455 lines
9.7 KiB
ReStructuredText
Raw Blame History

.. _syslog-ng-sate-usage:
Syslog-ng usage
===============
Overview
--------
Syslog\_ng state module is for generating syslog-ng
configurations. You can do the following things:
- generate syslog-ng configuration from YAML,
- use non-YAML configuration,
- start, stop or reload syslog-ng.
There is also an execution module, which can check the syntax of the
configuration, get the version and other information about syslog-ng.
Configuration
-------------
Users can create syslog-ng configuration statements with the
:py:func:`syslog_ng.config <salt.states.syslog_ng.config>` function. It requires
a `name` and a `config` parameter. The `name` parameter determines the name of
the generated statement and the `config` parameter holds a parsed YAML structure.
A statement can be declared in the following forms (both are equivalent):
.. code-block:: yaml
source.s_localhost:
syslog_ng.config:
- config:
- tcp:
- ip: "127.0.0.1"
- port: 1233
.. code-block:: yaml
s_localhost:
syslog_ng.config:
- config:
source:
- tcp:
- ip: "127.0.0.1"
- port: 1233
The first one is called short form, because it needs less typing. Users can use lists
and dictionaries to specify their configuration. The format is quite self describing and
there are more examples [at the end](#examples) of this document.
Quotation
---------
The quotation can be tricky sometimes but here are some rules to follow:
* when a string meant to be ``"string"`` in the generated configuration, it should be like ``'"string"'`` in the YAML document
* similarly, users should write ``"'string'"`` to get ``'string'`` in the generated configuration
Full example
------------
The following configuration is an example, how a complete syslog-ng configuration looks like:
.. code-block:: yaml
# Set the location of the configuration file
set_location:
module.run:
- name: syslog_ng.set_config_file
- m_name: "/home/tibi/install/syslog-ng/etc/syslog-ng.conf"
# The syslog-ng and syslog-ng-ctl binaries are here. You needn't use
# this method if these binaries can be found in a directory in your PATH.
set_bin_path:
module.run:
- name: syslog_ng.set_binary_path
- m_name: "/home/tibi/install/syslog-ng/sbin"
# Writes the first lines into the config file, also erases its previous
# content
write_version:
module.run:
- name: syslog_ng.write_version
- m_name: "3.6"
# There is a shorter form to set the above variables
set_variables:
module.run:
- name: syslog_ng.set_parameters
- version: "3.6"
- binary_path: "/home/tibi/install/syslog-ng/sbin"
- config_file: "/home/tibi/install/syslog-ng/etc/syslog-ng.conf"
# Some global options
options.global_options:
syslog_ng.config:
- config:
- time_reap: 30
- mark_freq: 10
- keep_hostname: "yes"
source.s_localhost:
syslog_ng.config:
- config:
- tcp:
- ip: "127.0.0.1"
- port: 1233
destination.d_log_server:
syslog_ng.config:
- config:
- tcp:
- "127.0.0.1"
- port: 1234
log.l_log_to_central_server:
syslog_ng.config:
- config:
- source: s_localhost
- destination: d_log_server
some_comment:
module.run:
- name: syslog_ng.write_config
- config: |
# Multi line
# comment
# Another mode to use comments or existing configuration snippets
config.other_comment_form:
syslog_ng.config:
- config: |
# Multi line
# comment
The :py:func:`syslog_ng.reloaded <salt.states.syslog_ng.reloaded>` function can generate syslog-ng configuration from YAML. If the statement (source, destination, parser,
etc.) has a name, this function uses the id as the name, otherwise (log
statement) it's purpose is like a mandatory comment.
After execution this example the syslog\_ng state will generate this
file:
.. code-block:: text
#Generated by Salt on 2014-08-18 00:11:11
@version: 3.6
options {
time_reap(
30
);
mark_freq(
10
);
keep_hostname(
yes
);
};
source s_localhost {
tcp(
ip(
127.0.0.1
),
port(
1233
)
);
};
destination d_log_server {
tcp(
127.0.0.1,
port(
1234
)
);
};
log {
source(
s_localhost
);
destination(
d_log_server
);
};
# Multi line
# comment
# Multi line
# comment
Users can include arbitrary texts in the generated configuration with
using the ``config`` statement (see the example above).
Syslog_ng module functions
--------------------------
You can use :py:func:`syslog_ng.set_binary_path <salt.modules.syslog_ng.set_binary_path>`
to set the directory which contains the
syslog-ng and syslog-ng-ctl binaries. If this directory is in your PATH,
you don't need to use this function. There is also a :py:func:`syslog_ng.set_config_file <salt.modules.syslog_ng.set_config_file>`
function to set the location of the configuration file.
Examples
--------
Simple source
~~~~~~~~~~~~~
.. code-block:: text
source s_tail {
file(
"/var/log/apache/access.log",
follow_freq(1),
flags(no-parse, validate-utf8)
);
};
.. code-block:: yaml
s_tail:
# Salt will call the source function of syslog_ng module
syslog_ng.config:
- config:
source:
- file:
- file: ''"/var/log/apache/access.log"''
- follow_freq : 1
- flags:
- no-parse
- validate-utf8
OR
.. code-block:: yaml
s_tail:
syslog_ng.config:
- config:
source:
- file:
- ''"/var/log/apache/access.log"''
- follow_freq : 1
- flags:
- no-parse
- validate-utf8
OR
.. code-block:: yaml
source.s_tail:
syslog_ng.config:
- config:
- file:
- ''"/var/log/apache/access.log"''
- follow_freq : 1
- flags:
- no-parse
- validate-utf8
Complex source
~~~~~~~~~~~~~~
.. code-block:: text
source s_gsoc2014 {
tcp(
ip("0.0.0.0"),
port(1234),
flags(no-parse)
);
};
.. code-block:: yaml
s_gsoc2014:
syslog_ng.config:
- config:
source:
- tcp:
- ip: 0.0.0.0
- port: 1234
- flags: no-parse
Filter
~~~~~~
.. code-block:: text
filter f_json {
match(
"@json:"
);
};
.. code-block:: yaml
f_json:
syslog_ng.config:
- config:
filter:
- match:
- ''"@json:"''
Template
~~~~~~~~
.. code-block:: text
template t_demo_filetemplate {
template(
"$ISODATE $HOST $MSG "
);
template_escape(
no
);
};
.. code-block:: yaml
t_demo_filetemplate:
syslog_ng.config:
-config:
template:
- template:
- '"$ISODATE $HOST $MSG\n"'
- template_escape:
- "no"
Rewrite
~~~~~~~
.. code-block:: text
rewrite r_set_message_to_MESSAGE {
set(
"${.json.message}",
value("$MESSAGE")
);
};
.. code-block:: yaml
r_set_message_to_MESSAGE:
syslog_ng.config:
- config:
rewrite:
- set:
- '"${.json.message}"'
- value : '"$MESSAGE"'
Global options
~~~~~~~~~~~~~~
.. code-block:: text
options {
time_reap(30);
mark_freq(10);
keep_hostname(yes);
};
.. code-block:: yaml
global_options:
syslog_ng.config:
- config:
options:
- time_reap: 30
- mark_freq: 10
- keep_hostname: "yes"
Log
~~~
.. code-block:: text
log {
source(s_gsoc2014);
junction {
channel {
filter(f_json);
parser(p_json);
rewrite(r_set_json_tag);
rewrite(r_set_message_to_MESSAGE);
destination {
file(
"/tmp/json-input.log",
template(t_gsoc2014)
);
};
flags(final);
};
channel {
filter(f_not_json);
parser {
syslog-parser(
);
};
rewrite(r_set_syslog_tag);
flags(final);
};
};
destination {
file(
"/tmp/all.log",
template(t_gsoc2014)
);
};
};
.. code-block:: yaml
l_gsoc2014:
syslog_ng.config:
- config:
log:
- source: s_gsoc2014
- junction:
- channel:
- filter: f_json
- parser: p_json
- rewrite: r_set_json_tag
- rewrite: r_set_message_to_MESSAGE
- destination:
- file:
- '"/tmp/json-input.log"'
- template: t_gsoc2014
- flags: final
- channel:
- filter: f_not_json
- parser:
- syslog-parser: []
- rewrite: r_set_syslog_tag
- flags: final
- destination:
- file:
- "/tmp/all.log"
- template: t_gsoc2014
Reference in New Issue View Git Blame Copy Permalink