README.rst - salt-formulas/rsyslog - Gitiles


 ==================================
 rsyslog
 ==================================

 In computing, syslog is a widely used standard for message logging. It permits separation of the software that generates messages, the system that stores them, and the software that reports and analyzes them.

 Sample pillars
 ==============

 Rsyslog service with default logging template

 .. code-block:: yaml

     rsyslog:
       client:
         enabled: true


 Rsyslog service with precise timestamps, severity, facility.

 .. code-block:: yaml

     rsyslog:
       client:
         enabled: true
         format:
           name: TraditionalFormatWithPRI
           template: '"%syslogpriority% %syslogfacility% %timestamp:::date-rfc3339% %HOSTNAME% %syslogtag%%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%\n"'
         output:
           file:
             -/var/log/syslog:
               filter: *.*;auth,authpriv.none
               owner: syslog
               group: adm
               createmode: 0640
               umask: 0022
             /var/log/auth.log:
               filter: auth,authpriv.*
               owner: syslog
               group: adm
               createmode: 0640
               umask: 0022
             -/var/log/kern.log:
               filter: kern.*
               owner: syslog
               group: adm
               createmode: 0640
               umask: 0022
            -/var/log/mail.log:
               filter: mail.*
               owner: syslog
               group: adm
               createmode: 0640
               umask: 0022
             /var/log/mail.err:
               filter: mail.err
               owner: syslog
               group: adm
               createmode: 0640
               umask: 0022
             ":omusrmsg:*":
               filter: *.emerg
             "|/dev/xconsole":
               filter: "daemon.*;mail.*; news.err; *.=debug;*.=info;*.=notice;*.=warn":
            -/var/log/your-app.log:
               filter: "if $programname startswith 'your-app' then"
               owner: syslog
               group: adm
               createmode: 0640
               umask: 0022
               stop_processing: true

 Rsyslog service with RainerScript (module, ruleset, template, input).

 .. code-block:: yaml

   rsyslog:
     client:
       run_user: syslog
       run_group: adm
       enabled: true
       rainerscript:
         module:
           imfile: {}
         input:
           imfile:
             nginx:
               File: "/var/log/nginx/*.log"
               Tag: "nginx__"
               Severity: "notice"
               Facility: "local0"
               PersistStateInterval: "0"
               Ruleset: "myapp_logs"
             apache2:
               File: "/var/log/apache2/*.log"
               Tag: "apache2__"
               Severity: "notice"
               Facility: "local0"
               Ruleset: "myapp_logs"
               PersistStateInterval: "0"
             rabbitmq:
               File: "/var/log/rabbitmq/*.log"
               Tag: "rabbitmq__"
               Severity: "notice"
               Facility: "local0"
               PersistStateInterval: "0"
               Ruleset: "myapp_logs"
         template:
           ImfileFilePath:
             parameter:
               type: string
               string: "<%PRI%>%TIMESTAMP:::date-rfc3339% %HOSTNAME% %syslogtag:1:32%%$.suffix%%msg:::sp-if-no-1st-sp%%msg%\n"
         ruleset:
           remote_logs:
             description: 'action(type="omfwd" Target="172.16.10.92" Port="10514" Protocol="udp" Template="ImfileFilePath")'
           myapp_logs:
             description: 'set $.suffix=re_extract($!metadata!filename, "(.*)/([^/]*[^/.log])", 0, 2, "all.log"); call remote_logs'

 Rsyslog service with GNU TLS encryption for forwarding the messages (omfwd module with gtls network stream driver).

 .. code-block:: yaml

   rsyslog:
     client:
       pkgs:
         - rsyslog-gnutls
         - rsyslog
       run_user: syslog
       run_group: adm
       enabled: true
       ssl:
         enabled: true
         engine: manual
         key: |
           -----BEGIN RSA PRIVATE KEY-----
           -----END RSA PRIVATE KEY-----
         cert: |
           -----BEGIN CERTIFICATE-----
           -----END CERTIFICATE-----
         cacert_chain: |
           -----BEGIN CERTIFICATE-----
           -----END CERTIFICATE-----
       rainerscript:
         global:
           defaultNetstreamDriverCAFile: "/etc/rsyslog.d/rsyslog_ca.crt"
           defaultNetstreamDriverKeyFile: "/etc/rsyslog.d/rsyslog_client.key"
           defaultNetstreamDriverCertFile: "/etc/rsyslog.d/rsyslog_client.crt"
       output:
         remote:
           somehost.domain:
             action: 'action(type="omfwd" Target="172.16.10.92" Port="20514" Protocol="tcp" streamDriver="gtls" streamDriverauthMode="anon" streamDriverMode="1")'
             filter: "*.*"
             enabled: true

 Rsyslog service with RELP TLS encryption for forwarding the messages (omrelp module).

 .. code-block:: yaml

   rsyslog:
     client:
       pkgs:
         - rsyslog-relp
         - rsyslog
       run_user: syslog
       run_group: adm
       enabled: true
       ssl:
         enabled: true
         engine: manual
         key: |
           -----BEGIN RSA PRIVATE KEY-----
           -----END RSA PRIVATE KEY-----
         cert: |
           -----BEGIN CERTIFICATE-----
           -----END CERTIFICATE-----
         cacert_chain: |
           -----BEGIN CERTIFICATE-----
           -----END CERTIFICATE-----
       rainerscript:
         module:
           omrelp: {}
       output:
         remote:
           somehost.domain:
             action: 'action(type="omrelp" target="172.16.10.92" port="20514" tls="on" tls.caCert="/etc/rsyslog.d/rsyslog_ca.crt" tls.myCert="/etc/rsyslog.d/rsyslog_client.crt" tls.myPrivKey="/etc/rsyslog.d/rsyslog_client.key" tls.authmode="name" tls.permittedpeer=["remote.example.com"])'
             filter: "*.*"
             enabled: true

 Custom templates
 ================

 It is possible to define a specific syslog template per output file instead of
 using the default one.

 .. code-block:: yaml

     rsyslog:
         output:
           file:
            /var/log/your-app.log:
               template: ""%syslogtag:1:32%%msg:::sp-if-no-1st-sp%%msg%\\n""
               filter: "if $programname startswith 'your-app' then"

 Remote rsyslog server
 =====================

 It is possible to have rsyslog act as remote server, collecting, storing or forwarding logs.
 This functionality is provided via rsyslog input/output modules, rulesets and templates.

 .. code-block:: yaml

     rsyslog:
       server:
         enabled: true
         module:
           imudp: {}
         template:
           RemoteFilePath:
             parameter:
               type: string
               string: /var/log/%HOSTNAME%/%programname%.log
         ruleset:
           remote10514:
             description: action(type="omfile" dynaFile="RemoteFilePath")
         input:
           imudp:
             port: 10514
             ruleset: remote10514


 Support metadata
 ================

 If the *heka* support metadata is enabled, all output files are automatically
 parsed by the **log_collector** service.
 To skip the log_collector configuration, set the **skip_log_collector** to true.

 .. code-block:: yaml

     rsyslog:
         output:
           file:
            /var/log/your-app.log:
               filter: "if $programname startswith 'your-app' then"
               skip_log_collector: true

 Read more
 =========

 http://www.rsyslog.com/
 https://wiki.gentoo.org/wiki/Rsyslog
 https://github.com/saz/puppet-rsyslog

 Documentation and Bugs
 ======================

 To learn how to install and update salt-formulas, consult the documentation
 available online at:

     http://salt-formulas.readthedocs.io/

 In the unfortunate event that bugs are discovered, they should be reported to
 the appropriate issue tracker. Use Github issue tracker for specific salt
 formula:

     https://github.com/salt-formulas/salt-formula-rsyslog/issues

 For feature requests, bug reports or blueprints affecting entire ecosystem,
 use Launchpad salt-formulas project:

     https://launchpad.net/salt-formulas

 You can also join salt-formulas-users team and subscribe to mailing list:

     https://launchpad.net/~salt-formulas-users

 Developers wishing to work on the salt-formulas projects should always base
 their work on master branch and submit pull request against specific formula.

     https://github.com/salt-formulas/salt-formula-rsyslog

 Any questions or feedback is always welcome so feel free to join our IRC
 channel:

     #salt-formulas @ irc.freenode.net

	==================================
	rsyslog
	==================================

	In computing, syslog is a widely used standard for message logging. It permits separation of the software that generates messages, the system that stores them, and the software that reports and analyzes them.

	Sample pillars
	==============

	Rsyslog service with default logging template

	.. code-block:: yaml

	rsyslog:
	client:
	enabled: true


	Rsyslog service with precise timestamps, severity, facility.

	.. code-block:: yaml

	rsyslog:
	client:
	enabled: true
	format:
	name: TraditionalFormatWithPRI
	template: '"%syslogpriority% %syslogfacility% %timestamp:::date-rfc3339% %HOSTNAME% %syslogtag%%msg:::sp-if-no-1st-sp%%msg:::drop-last-lf%\n"'
	output:
	file:
	-/var/log/syslog:
	filter: .;auth,authpriv.none
	owner: syslog
	group: adm
	createmode: 0640
	umask: 0022
	/var/log/auth.log:
	filter: auth,authpriv.*
	owner: syslog
	group: adm
	createmode: 0640
	umask: 0022
	-/var/log/kern.log:
	filter: kern.*
	owner: syslog
	group: adm
	createmode: 0640
	umask: 0022
	-/var/log/mail.log:
	filter: mail.*
	owner: syslog
	group: adm
	createmode: 0640
	umask: 0022
	/var/log/mail.err:
	filter: mail.err
	owner: syslog
	group: adm
	createmode: 0640
	umask: 0022
	":omusrmsg:*":
	filter: *.emerg
	"\|/dev/xconsole":
	filter: "daemon.;mail.; news.err; .=debug;.=info;.=notice;.=warn":
	-/var/log/your-app.log:
	filter: "if $programname startswith 'your-app' then"
	owner: syslog
	group: adm
	createmode: 0640
	umask: 0022
	stop_processing: true

	Rsyslog service with RainerScript (module, ruleset, template, input).

	.. code-block:: yaml

	rsyslog:
	client:
	run_user: syslog
	run_group: adm
	enabled: true
	rainerscript:
	module:
	imfile: {}
	input:
	imfile:
	nginx:
	File: "/var/log/nginx/*.log"
	Tag: "nginx__"
	Severity: "notice"
	Facility: "local0"
	PersistStateInterval: "0"
	Ruleset: "myapp_logs"
	apache2:
	File: "/var/log/apache2/*.log"
	Tag: "apache2__"
	Severity: "notice"
	Facility: "local0"
	Ruleset: "myapp_logs"
	PersistStateInterval: "0"
	rabbitmq:
	File: "/var/log/rabbitmq/*.log"
	Tag: "rabbitmq__"
	Severity: "notice"
	Facility: "local0"
	PersistStateInterval: "0"
	Ruleset: "myapp_logs"
	template:
	ImfileFilePath:
	parameter:
	type: string
	string: "<%PRI%>%TIMESTAMP:::date-rfc3339% %HOSTNAME% %syslogtag:1:32%%$.suffix%%msg:::sp-if-no-1st-sp%%msg%\n"
	ruleset:
	remote_logs:
	description: 'action(type="omfwd" Target="172.16.10.92" Port="10514" Protocol="udp" Template="ImfileFilePath")'
	myapp_logs:
	description: 'set $.suffix=re_extract($!metadata!filename, "(.)/([^/][^/.log])", 0, 2, "all.log"); call remote_logs'

	Rsyslog service with GNU TLS encryption for forwarding the messages (omfwd module with gtls network stream driver).

	.. code-block:: yaml

	rsyslog:
	client:
	pkgs:
	- rsyslog-gnutls
	- rsyslog
	run_user: syslog
	run_group: adm
	enabled: true
	ssl:
	enabled: true
	engine: manual
	key: \|
	-----BEGIN RSA PRIVATE KEY-----
	-----END RSA PRIVATE KEY-----
	cert: \|
	-----BEGIN CERTIFICATE-----
	-----END CERTIFICATE-----
	cacert_chain: \|
	-----BEGIN CERTIFICATE-----
	-----END CERTIFICATE-----
	rainerscript:
	global:
	defaultNetstreamDriverCAFile: "/etc/rsyslog.d/rsyslog_ca.crt"
	defaultNetstreamDriverKeyFile: "/etc/rsyslog.d/rsyslog_client.key"
	defaultNetstreamDriverCertFile: "/etc/rsyslog.d/rsyslog_client.crt"
	output:
	remote:
	somehost.domain:
	action: 'action(type="omfwd" Target="172.16.10.92" Port="20514" Protocol="tcp" streamDriver="gtls" streamDriverauthMode="anon" streamDriverMode="1")'
	filter: "."
	enabled: true

	Rsyslog service with RELP TLS encryption for forwarding the messages (omrelp module).

	.. code-block:: yaml

	rsyslog:
	client:
	pkgs:
	- rsyslog-relp
	- rsyslog
	run_user: syslog
	run_group: adm
	enabled: true
	ssl:
	enabled: true
	engine: manual
	key: \|
	-----BEGIN RSA PRIVATE KEY-----
	-----END RSA PRIVATE KEY-----
	cert: \|
	-----BEGIN CERTIFICATE-----
	-----END CERTIFICATE-----
	cacert_chain: \|
	-----BEGIN CERTIFICATE-----
	-----END CERTIFICATE-----
	rainerscript:
	module:
	omrelp: {}
	output:
	remote:
	somehost.domain:
	action: 'action(type="omrelp" target="172.16.10.92" port="20514" tls="on" tls.caCert="/etc/rsyslog.d/rsyslog_ca.crt" tls.myCert="/etc/rsyslog.d/rsyslog_client.crt" tls.myPrivKey="/etc/rsyslog.d/rsyslog_client.key" tls.authmode="name" tls.permittedpeer=["remote.example.com"])'
	filter: "."
	enabled: true

	Custom templates
	================

	It is possible to define a specific syslog template per output file instead of
	using the default one.

	.. code-block:: yaml

	rsyslog:
	output:
	file:
	/var/log/your-app.log:
	template: ""%syslogtag:1:32%%msg:::sp-if-no-1st-sp%%msg%\\n""
	filter: "if $programname startswith 'your-app' then"

	Remote rsyslog server
	=====================

	It is possible to have rsyslog act as remote server, collecting, storing or forwarding logs.
	This functionality is provided via rsyslog input/output modules, rulesets and templates.

	.. code-block:: yaml

	rsyslog:
	server:
	enabled: true
	module:
	imudp: {}
	template:
	RemoteFilePath:
	parameter:
	type: string
	string: /var/log/%HOSTNAME%/%programname%.log
	ruleset:
	remote10514:
	description: action(type="omfile" dynaFile="RemoteFilePath")
	input:
	imudp:
	port: 10514
	ruleset: remote10514



	Support metadata
	================

	If the heka support metadata is enabled, all output files are automatically
	parsed by the log_collector service.
	To skip the log_collector configuration, set the skip_log_collector to true.

	.. code-block:: yaml

	rsyslog:
	output:
	file:
	/var/log/your-app.log:
	filter: "if $programname startswith 'your-app' then"
	skip_log_collector: true

	Read more
	=========

	http://www.rsyslog.com/
	https://wiki.gentoo.org/wiki/Rsyslog
	https://github.com/saz/puppet-rsyslog

	Documentation and Bugs
	======================

	To learn how to install and update salt-formulas, consult the documentation
	available online at:

	http://salt-formulas.readthedocs.io/

	In the unfortunate event that bugs are discovered, they should be reported to
	the appropriate issue tracker. Use Github issue tracker for specific salt
	formula:

	https://github.com/salt-formulas/salt-formula-rsyslog/issues

	For feature requests, bug reports or blueprints affecting entire ecosystem,
	use Launchpad salt-formulas project:

	https://launchpad.net/salt-formulas

	You can also join salt-formulas-users team and subscribe to mailing list:

	https://launchpad.net/~salt-formulas-users

	Developers wishing to work on the salt-formulas projects should always base
	their work on master branch and submit pull request against specific formula.

	https://github.com/salt-formulas/salt-formula-rsyslog

	Any questions or feedback is always welcome so feel free to join our IRC
	channel:

	#salt-formulas @ irc.freenode.net