From 9584c81df387adcdcd7b84078eda48092049101d Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Thu, 10 Apr 2008 08:06:48 +0200 Subject: added ommail.html - I forgot to add this file... --- doc/ommail.html | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 doc/ommail.html (limited to 'doc') diff --git a/doc/ommail.html b/doc/ommail.html new file mode 100644 index 00000000..b6b7c2ad --- /dev/null +++ b/doc/ommail.html @@ -0,0 +1,128 @@ + +mail output module - sending syslog messages via mail + + + +

Mail Output Module (ommail)

+

Module Name:    ommail

+

Author: Rainer Gerhards +<rgerhards@adiscon.com>

+

Description:

+

This module supports sending syslog messages via mail. Each +syslog message is sent via its own mail. Obviously, you will want to +apply rigorous filtering, otherwise your mailbox (and mail server) will +be heavily spammed. The ommail plugin is primarily meant for alerting +users. As such, it is assume that mails will only be sent in an +extremely limited number of cases.

+

Please note that ommail is especially well-suited to work in +tandem with imfile to +watch files for the occurence of specific things to be alerted on. So +its scope is far broader than forwarding syslog messages to mail +recipients.

+Ommail uses two templates, one for the mail body and one for the +subject line. If neither is provided, a quite meaningless subject line +is used and the mail body will be a syslog message just as if it were +written to a file. It is expected that the users customizes both +messages. In an effort to support cell phones (including SMS gateways), +there is an option to turn off the body part at all. This is considered +to be useful to send a short alert to a pager-like device.
+
+It is highly recommended to use the  "$ActionExecOnlyOnceEveryInterval +<seconds>" directive to limit the amount of +mails that potentially be generated. With it, mails are sent at most in +a <seconds> interval. This may be your life safer. And +remember that an hour has 3,600 seconds, so if you would like to +receive mails at most once every two hours, include a +"$ActionExecOnlyOnceEveryInterval 7200" immediately before the ommail +action. Messages sent more frequently are simpy discarded. +

Configuration Directives:

+ +Caveats/Known Bugs: +

The current ommail implementation supports SMTP-direct mode +only. In that mode, the plugin talks to the mail server via SMTP +protocol. No other process is involved. This mode offers best +reliability as it is not depending on any external entity except the +mail server. Mail server downtime is acceptable if the action is put +onto its own action queue, so that it may wait for the SMTP server to +come back online. However, the module implements only the bare SMTP +essentials. Most importantly, it does not provide any authentication +capabilities. So your mail server must be configured to accept incoming +mail from ommail without any authentication needs (this may be change +in the future as need arises, but you may also be referred to +sendmail-mode).

+

In theory, ommail should also offer a mode where it uses the +sendmail utility to send its mail (sendmail-mode). +This is somewhat less reliable (because we depend on an entity we do +not have close control over - sendmail). It also requires dramatically +more system ressources, as we need to load the external process (but +that should be no problem given the expected infrequent number of calls +into this plugin). The big advantage of sendmail mode is that it +supports all the bells and whistles of a full-blown SMTP implementation +and may even work for local delivery without a SMTP server being +present. Sendmail mode will be implemented as need arises. So if you +need it, please drop us a line (I nobody does, sendmail mode will +probably never be implemented).

+

Sample:

+

The following sample alerts the operator if the string "hard +disk fatal failure" is present inside a syslog message. The mail server +at mail.example.net is used and the subject shall be "disk problem on +<hostname>". Note how \r\n is included inside the body +text +to create line breaks. A message is sent at most once every 6 hours, +any other messages are silently discarded (or, to be precise, not being +forwarded - they are still being processed by the rest of the +configuration file).
+

+
+
+A more advanced example plus a discussion on using the email feature +inside a reliable system can be found in Rainer's blogpost +"Why +is native email capability an advantage for a syslogd?" +

[rsyslog.conf overview] +[manual index] [rsyslog site]

+

This documentation is part of the +rsyslog +project.
+Copyright © 2008 by Rainer +Gerhards and +Adiscon. +Released under the GNU GPL version 3 or higher.

+ \ No newline at end of file -- cgit From 4339d44b29aea69634abece7026ecf0154cb03c7 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Thu, 10 Apr 2008 08:13:54 +0200 Subject: project status is now a web-exclusive ... and no longer part of the tarball. This solves a couple of update issues when new versions inside the other branches are released. It is still kept in git, so that we have a record of it. To make sure which version the documentation is, the version info has been moved to the main manual page. --- doc/Makefile.am | 1 - doc/manual.html | 7 +++++-- 2 files changed, 5 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am index 57e93a6f..5dba5e89 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -18,7 +18,6 @@ html_files = \ rsyslog_recording_pri.html \ rsyslog_stunnel.html \ professional_support.html \ - status.html \ syslog-protocol.html \ version_naming.html \ contributors.html \ diff --git a/doc/manual.html b/doc/manual.html index d4e00155..2e030ab5 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -31,9 +31,12 @@ relay chains while at the same time being very easy to setup for the novice user. And as we know what enterprise users really need, there is also professional rsyslog support available directly from the source!

-

Visit the rsyslog status page to obtain current +

This documentation is for version 2.0.5 of rsyslog. +Visit the rsyslog status page to obtain current +version information and project status.

-version information and ports. If you like rsyslog, you might want to lend us +version information and ports. +

If you like rsyslog, you might want to lend us a helping hand. It doesn't require a lot of time - even a single mouse click -- cgit From aeed303e2bb63794aea7bf80c733a85e37862fe2 Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Fri, 11 Apr 2008 11:12:05 +0200 Subject: preparing for 3.15.1 --- doc/manual.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/manual.html b/doc/manual.html index 9d4dbefd..2e0c22ac 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -17,7 +17,7 @@ relay chains while at the same time being very easy to setup for the novice user. And as we know what enterprise users really need, there is also professional rsyslog support available directly from the source!

-

This documentation is for version 3.14.2 of rsyslog. +

This documentation is for version 3.15.1 (beta branch) of rsyslog. Visit the rsyslog status page to obtain current version information and project status.

If you like rsyslog, you might -- cgit From 07c0fcdfc8815ce6b82376d9d312b4e86ed29743 Mon Sep 17 00:00:00 2001 From: Peter Vrabec Date: Fri, 11 Apr 2008 16:02:04 +0200 Subject: added gssapi overview/howto thanks to Peter Vrabec Signed-off-by: Rainer Gerhards --- doc/gssapi.html | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/gssapi.png | Bin 0 -> 35638 bytes doc/manual.html | 11 +++--- 3 files changed, 123 insertions(+), 6 deletions(-) create mode 100644 doc/gssapi.html create mode 100644 doc/gssapi.png (limited to 'doc') diff --git a/doc/gssapi.html b/doc/gssapi.html new file mode 100644 index 00000000..400be4a3 --- /dev/null +++ b/doc/gssapi.html @@ -0,0 +1,118 @@ + +GSSAPI module support in rsyslog v3 + + + +

GSSAPI module support in rsyslog v3

+

What is it good for.

+
    +
  • +client-serverauthentication
    • +
  • +Log +messages encryption
    • +
+

+

Requirements. +

+
    +
  • Kerberos infrastructure
    • +
  • rsyslog, rsyslog-gssapi
    • +
+

+

Configuration. +

+

Let's assume there are 3 machines in kerberos Realm:

+
    +
  • the +first is running KDC (Kerberos Authentication Service and Key +Distribution Center),
    • +
  • the second is a client sending its logs to the server,
    • +
  • the third is receiver, gathering all logs.
    • +
+

+

1. +KDC:

+
    +
  • Kerberos +database must be properly set-up on KDC machine first. Use +kadmin/kadmin.local to do that. Two principals need to be add in our +case:
    • +
+
    +
  1. +

    sender@REALM.ORG +

    +
    2. +
+
    +
  • client must have ticket for pricipal sender
    • +
  • REALM.ORG is kerberos Realm
    • +
+
    +
  1. host/receiver.mydomain.com@REALM.ORG - service principal
    2. +
+
    +
  • Use ktadd to export service principal and transfer it to +/etc/krb5.keytab +on receiver
    • +
+

2. CLIENT: +

+
    +
  • set-up rsyslog, in /etc/rsyslog.conf
    • +
  • $ModLoad omgssapi.so - load output gss module
    • +
  • $GSSForwardServiceName +otherThanHost - set the name of service principal, "host" is the +default one
    • +
  • *.* :omgssapi:receiver.mydomain.com - action line, forward +logs to receiver
    • +
  • kinit root - get the TGT ticket
    • +
  • service rsyslog start +

    +
    • +
+

3. SERVER: +

+
    +
  • +

    set-up +rsyslog, in /etc/rsyslog.conf

    +
    • +
  • +

    $ModLoad +imgssapi.so - load input gss module

    +
    • +
  • +

    $InputGSSServerServiceName +otherThanHost - set the name of service principal, "host" is the +default one

    +
    • +
  • +

    $InputGSSServerPermitPlainTCP +on - accept GSS and TCP connections (not authenticated senders), off by +default

    +
    • +
  • +

    $InputGSSServerRun +514 - run server on port

    +
    • +
  • +

    service +rsyslog start

    +
    • +
+The picture demonstrate +how things work. +

+rsyslog gssapi support +

[rsyslog.conf overview] +[manual index] [rsyslog site]

+

This documentation is part of the +rsyslog +project.
+Copyright © 2008 by Rainer +Gerhards and +Adiscon. +Released under the GNU GPL version 3 or higher.

+ \ No newline at end of file diff --git a/doc/gssapi.png b/doc/gssapi.png new file mode 100644 index 00000000..c82baa52 Binary files /dev/null and b/doc/gssapi.png differ diff --git a/doc/manual.html b/doc/manual.html index 9d4dbefd..8bdee8b7 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -1,6 +1,5 @@ -rsyslog documentation - +rsyslog documentation

RSyslog - Documentation

Rsyslog @@ -18,9 +17,9 @@ novice user. And as we know what enterprise users really need, there is also professional rsyslog support available directly from the source!

This documentation is for version 3.14.2 of rsyslog. -Visit the rsyslog status page to obtain current +Visit the rsyslog status page to obtain current version information and project status. -

If you like rsyslog, you might +

If you like rsyslog, you might want to lend us a helping hand. It doesn't require a lot of time - even a single mouse click helps. Learn how to help the rsyslog project. Due to popular demand, there is now a side-by-side comparison @@ -64,7 +63,7 @@ php-syslog-ng with rsyslog

  • recording the syslog priority (severity and facility) to the log file
  • preserving -syslog sender over NAT (online only)
    • +syslog sender over NAT (online only)
  • an overview and howto of rsyslog gssapi support
  • debug support in rsyslog
  • the rsyslog message queue object
    • @@ -100,4 +99,4 @@ may find Rainer's blog an interesting read (filter on syslog and rsyslog tags).

    - + \ No newline at end of file -- cgit From f4b26f77ab03a1bacf2c49a1982fabe2a58ccb9d Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Tue, 15 Apr 2008 10:42:14 +0200 Subject: changed some files to grant LGPLv3 extended persmissions on top of GPLv3 this also is the first sign of something that will evolve into a well-defined "rsyslog runtime library" --- doc/licensing.html | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/manual.html | 11 ++++++--- 2 files changed, 79 insertions(+), 4 deletions(-) create mode 100644 doc/licensing.html (limited to 'doc') diff --git a/doc/licensing.html b/doc/licensing.html new file mode 100644 index 00000000..93a50930 --- /dev/null +++ b/doc/licensing.html @@ -0,0 +1,72 @@ + + +rsyslog licensing + + + +

    rsyslog licensing

    +

    Most important things first: if you intend to use rsyslog inside a GPLv3 compatible project, you are free to do so. You don't even need to continue reading. +If you intend to use rsyslog inside a non-GPLv3 +compatible project, rsyslog offers you some liberties to do that, too. However, you then need +to study the licensing details in depth. +

    The project hopes this is a good compromise, which also gives a boost to fellow free +software developers who release under GPLv3. +

    And now on to the dirty and boring license details, still on a executive summary level. For the +real details, check source files and the files COPYING and COPYING.LESSER inside the distribution. +

    The rsyslog package contains several components: +

      +
    • the rsyslog core programs (like rsyslogd) +
    • plugins (like imklog, omrelp, ...) +
    • the rsyslog runtime library +
    +

    Each of these components can be thought of as individual projects. In fact, some of the +plugins have different main authors than the rest of the rsyslog package. All of these +components are currently put together into a single "rsyslog" package (tarball) for +convinience: this makes it easier to distribute a consistent version where everything +is included (and in the right versions) to build a full system. Platform package +maintainers in general take the overall package and split off the individual components, so that +users can install only what they need. In source installations, this can be done via the +proper ./configure switches. +

    However, while it is convenient to package all parts in a single tarball, it does not +imply all of them are necessarily covered by the same license. Traditionally, GPL licenses +are used for rsyslog, because the project would like to provide free software. GPLv3 has been +used since around 2008 to help fight for our freedom. All rsyslog core programs are +released under GPLv3. But, from the beginning on, plugins were separate projects and we did not +impose and license restrictions on them. So even though all plugins that currently ship with +the rsyslog package are also placed under GPLv3, this can not taken for granted. You need +to check each plugins license terms if in question - this is especially important for +plugins that do NOT ship as part of the rsyslog tarball. +

    In order to make rsyslog technology available to a broader range of applications, +the rsyslog runtime is, at least partly, licensed under LGPL. If in doubt, check the source file +licensing comments. As of now, the following files are licensed under LGPL: +

      +
    • queue.c/.h +
    • wti.c/.h +
    • wtp.c/.h +
    • vm.c/.h +
    • vmop.c/.h +
    • vmprg.c/.h +
    • vmstk.c/.h +
    • expr.c/.h +
    • sysvar.c/.h +
    • ctok.c/.h +
    • ctok_token.c/.h +
    • regexp.c/.h +
    • sync.c/.h +
    • stream.c/.h +
    • var.c/.h +
    +This list will change as time of the runtime modularization. At some point in the future, there will +be a well-designed set of files inside a runtime library branch and all of these will be LGPL. Some +select extras will probably still be covered by GPL. We are following a similar licensing +model in GnuTLS, which makes effort to reserve some functionality exclusively to open source +projects. +

    [manual index] [rsyslog site]

    +

    This documentation is part of the +rsyslog +project.
    +Copyright © 2008 by Rainer +Gerhards and +Adiscon. Last Update: 2008-04-15. +Released under the GNU GPL version 3 or higher.

    + diff --git a/doc/manual.html b/doc/manual.html index 8bdee8b7..9c49cbee 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -65,8 +65,7 @@ the syslog priority (severity and facility) to the log file
  • preserving syslog sender over NAT (online only)
  • an overview and howto of rsyslog gssapi support
  • debug support in rsyslog
    • -
  • the rsyslog message -queue object
    • +
  • the rsyslog message queue object

    • Our rsyslog history page is for you if you would like to learn a little more @@ -98,5 +97,9 @@ mailing list. If you are interested in the "backstage", you may find Rainer's blog an -interesting read (filter on syslog and rsyslog tags).

    - \ No newline at end of file +interesting read (filter on syslog and rsyslog tags). +If you would like to use rsyslog source code inside your open source project, you can do that without +any restriction as long as your license is GPLv3 compatible. If your license is incompatible to GPLv3, +you may even be still permitted to use rsyslog source code. However, then you need to look at the way +rsyslog is licensed.

    + -- cgit