diff options
-rw-r--r-- | docs/Makefile | 130 | ||||
-rw-r--r-- | docs/source/conf.py | 256 | ||||
-rw-r--r-- | docs/source/configuration.rst | 396 | ||||
-rw-r--r-- | docs/source/index.rst | 28 | ||||
-rw-r--r-- | docs/source/installing.rst | 30 | ||||
-rw-r--r-- | docs/source/starting.rst | 78 | ||||
-rw-r--r-- | docs/source/writingreporters.rst | 20 |
7 files changed, 938 insertions, 0 deletions
diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..e97cb5f --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,130 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/logactio.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/logactio.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/logactio" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/logactio" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + make -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..1f3e300 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,256 @@ +# -*- coding: utf-8 -*- +# +# logactio documentation build configuration file, created by +# sphinx-quickstart on Mon Sep 17 10:59:56 2012. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'logactio' +copyright = u'2012, David Sommerseth' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.01' +# The full version, including alpha/beta/rc tags. +release = '0.01' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'logactiodoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'logactio.tex', u'logactio Documentation', + u'David Sommerseth', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'logactio', u'logactio Documentation', + [u'David Sommerseth'], 1) +] + + +# -- Options for Epub output --------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = u'logactio' +epub_author = u'David Sommerseth' +epub_publisher = u'David Sommerseth' +epub_copyright = u'2012, David Sommerseth' + +# The language of the text. It defaults to the language option +# or en if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +#epub_exclude_files = [] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst new file mode 100644 index 0000000..9ee3cb3 --- /dev/null +++ b/docs/source/configuration.rst @@ -0,0 +1,396 @@ +.. Copyright 2012 David Sommerseth <dazo@users.sourceforge.net> + + This is free software: you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by + the Free Software Foundation, version 2 of the License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see + <http://www.gnu.org/licenses/>. + +.. For notes on how to document Python in RST form, see e.g.: +.. http://sphinx.pocoo.org/domains.html#the-python-domain + +Configuring logactio +==================== + +Logactio makes use of a single ini-styled configuration file. The default +location for this file is */etc/logactio.cfg*. This file uses a separate +section, identified by *[section-name]*. There are three different groups +of sections which you need to configure, *Reporter*, *Logfile* and *Rule*. +Each of these group names have a *label*, where the group name and the label +are separated by a colon (:) + + +.. index:: + pair: Configuration; Reporters + +Configuring Reporters +********************* + +There are three different reporters available in logactio, and each of them take +different configuration parameters. If no reporter is configured, a built-in +reporter called *Default* will be used. + +* The Default reporter + + This reporter will only write data via the configured logging methods. This + reporter also does not have any configuration settings and does not require + any specific declaration. + +* :ref:`lnk-httpreporter` + + This reporter will send the extracted log data to a web server. Both + HTTP and HTTPS may be used. + +* :ref:`lnk-smtpreporter` + + This reporter will send the extracted log data via SMTP to one or more + e-mail recipients. Support for SSL and STARTTLS in addition to SMTP-AUTH + are availble as well. + +* :ref:`lnk-qpidreporter` + + This reporter will send the extracted log data to an + `Apache Qpid <http://qpid.apache.org>` AMQP message broker. One + or more AMQP consumer clients may then act upon the messages recieved + in the message queue. In the *examples/* directory a simple Qpid + consumer client is available. + + +.. index:: + pair: Configuration; HTTPreporter +.. _lnk-httpreporter: + +HTTPreporter +------------ + +This reporter takes takes two configuration variables + +* method + + This defaults to **GET** if this is not set. But can be set to **POST** + if you want the reports to be sent via HTTP POST instead of HTTP GET. + +* url + + This is a required setting. This is the URL where to submit the reports. + +.. index:: + pair: Examples; HTTPreporter + +HTTPreporter example +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block :: ini + + [Reporter:HTTP-DEMO-1] + module: HTTPreporter + method: POST + url: http://logactio.example.com/alert/ + + [Reporter:HTTP-DEMO-2] + module: HTTPreporter + url: http://logactio.example.com/info/ + +Here two reporters are configured, *HTTP-DEMO-1* and *HTTP-DEMO-2*. That's the +labels which you will need to use later on. The *module* option is to tell +logactio to load the *HTTPreporter* module. + +The first reporter will use HTTP POST when submitting reports to the provided +URL, while the second reporter will use HTTP GET. + +.. index:: + pair: Configuration; SMTPreporter +.. _lnk-smtpreporter: + +SMTPreporter +------------ +This reporter requires the following configuration variables: + +* sender + + The e-mail address which will be used in the "From:" field when sending + mails + +* recipients + + This contains a comma separated list with all e-mail addresses who will + get the logactio reports. + +* smtp_host + + This declares which SMTP server to use when sending the reports. + +In addition the SMTPreporter supports these optional variables: + +* subject_prefix + + The default subject prefix is set to 'LogActio Alert: '. By setting + this variable, the subject prefix will be changed accordingly. + +* smtp_port + + The default value is set to port 25. + +* smtp_username + + If the SMTP server requires authentication to relay messages, this + variable sets the SMTP user name. To use this feature, you must also + set the smtp_password. + +* smtp_password + + This sets the SMTP password to use for the authentication + +* sslmode + + This is not set by default, so everything goes in clear text. If your SMTP + server supports either SSL or STARTTLS, you can set it to SSL or STARTTLS. + In SSL mode the SMTP library expects to the server to do the SSL handshake + before the SMTP commands can be sent. In STARTTLS mode, the SMTP library + will connect to the SMTP server in clear text and if the server supports + STARTTLS, it will send the STARTTLS command and start the SSL handshake. + +.. index:: + pair: Examples; SMTPreporter + +SMTPreporter example +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block :: ini + + [Reporter:SMTP-DEMO-1] + module: SMTPreporter + sender: logactio@example.com + recipients: john.doe@example.com, jane.doe@example.com + smtp_host: localhost + + [Reporter:SMTP-DEMO-2] + module: SMTPreporter + sender: john.doe@example.com + recipients: bob.external@acme.com + smtp_host: smtp.example.com + smtp_port: 587 + sslmode: STARTTLS + smtp_user: logactioSMTP + smtp_password: S3cretP4ssw0rd + subject_prefix: Issues at Example Corp: + +Here two more reporters are configured. SMTP-DEMO-1 will use the SMTP MTA +running locally on the system, and this will not require any authentication +or SSL functionality. When this reporter is triggered, it will send mails +to john.doe and jane.doe with the From field set to logactio@example.com. + +The SMTP-DEMO-2 reporter will send mails using an external SMTP server using +port 587 and which requires STARTTLS and authentication. The subject line +is also prefixed differently. + + +.. index:: + pair: Configuration; QpidReporter +.. _lnk-qpidreporter: + +QpidReporter +------------ +To use this reporter, you must have a running AMQP server available for +logactio. You must also have configured a topic exchange which this reporter +can use. It also requires the python-qpid module to be installed + +The required configuration variables which must be set are: + +* broker + + This is the hostname or IP address of the AMQP broker to connect to. + +* exchange + + This is the AMQP exchange logactio will use when sending reports + +* routing_key + + This contains the "topic queue" where subscribers can receive reports + sent by logactio. + +Optional settings are: + +* port + + If the broker is not running on the default port 5672, this can be changed + with this variable. + +.. index:: + pair: Examples; QpidReporter + +QpidReporter example +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block :: ini + + [Reporter:QPID-DEMO-1] + module: QpidReporter + broker: amqp.example.com + exchange: amq.topic + routing_key: logactio.demo1 + +This configures the reporter labelled QPID-DEMO-1 to use QpidReporter to +send reports via the *amqp.example.com* AMQP server. All messages goes +to all the *logactio.demo1* subscribers in the *amq.topic* exchange. + +If you have an AMQP broker running, you can use the demo script +*examples/qpid-alert-watcher* and run it like this: + +.. code-block :: bash + + [user@host: ~/logactio/example] $ ./qpid-alert-watcher --broker amqp.example.com --exchange amq.topic --bind-key logactio.demo1 + +This will start up a message consumer which will dump all the reports sent by logactio to stdout. + +.. index:: + single: Log files + +Configuring log files +********************* +The configuration sections for the log files are similar to the reporters. You +declare a section for each log file you want logactio to watch and how often +you want logactio to check the file for changes. For each configured logfile +section logactio will start a separate worker thread for the event processing. + +There are three configuration variables logactio supports for logfiles: + +* logfile + + This is mandatory, and declares the log file it should watch + +* reporters + + This is optional, but declares the default reporter module(s) to use if an + event happens to this file. You may list more reporter modules, separated + by comma. + +* polltime + + This is optional. The default is 30 seconds. This declares how often + logactio should check the file for changes, which indirectly defines + how quickly logactio would react to and report events. + +Logfile example +--------------- + +A typical configuration for log file sections would look something like this: + +.. code-block :: ini + + [Logfile:messages] + logfile: /var/log/messages + reporters: SMTP-DEMO-1 + + [Logfile:maillog] + logfile: /var/log/maillog + reporters: HTTP-DEMO-1, QPID-DEMO-1 + polltime: 15 + +In this example we have configured two Logfile groups, *messages* and *maillog*. +Any event happening in /var/log/messages will by default be reported using the +configured SMTP-DEMO-1 reporter setup. The *maillog* will be checked every +15th second and by default both the HTTP-DEMO-1 and QPID-DEMO-1 reporters will +be used when reporting events. + +.. index:: + single: Rules + +Configuring watch rules +*********************** +If you only configure Logfile and Reporter sections, logactio will not trigger +at all. You need to configure some rules what logactio should react to. + +The rules are based on regular expressions. And if there is a match on the +log lines received, each of these lines will be acted upon separately. + +A Rules section consists of two required configuration variables: + +* logfile + + This is the log file this rule is to be used against + +* regex + + This is the regular expression which needs to match to cause the reporter + to be triggered. You can also use regex groups, like (.*), to extract + information from the log line which will be sent to the reporter. If + you use multiple groups, all of them will be sent to reporter. + +* threshold: + + This sets how many times this event should match before triggering the + reporter. + +The optional settings are: + +* reporters + + This overrides the default reporters configured in the log file's Logfile + section. This can be used to add exceptions or report an event differently + in special cases. For example you might want developers to get an automatic + mail if their program causes an exception which is logged. While a system- + administrator might only want reports if someone tries to log into a system + unsuccessfully more than 3 times. Setting up different Rule sections with + different reporters and thresholds brings you this power, even if everything + is logged to the same file. + +* time-frame + + This extends the threshold trigger to also consider a time frame before + trigging an action. If the threshold is set to 3 and time-frame is set + to 10, logaction will not trigger an action unless there are 3 events + within the last 10 seconds. + +* rate-limit + + This will restrict logactio from any flood actions. If this value is set to + 10 and you have log changes which matches this rule once every second, + logactio will only perform the configured action once per 10 second. + +* reset-rule-rate-limits + + This takes a comma separated list of rule names, but only for the same log + file this rule uses. This can be used to "unlock" another rule's rate-limit + restriction. + + This is useful where you might report connection issues only once an hour, + even though the failed reconnection attempts are logged every minute. But + in the moment the connection really is restored you can trigger a logactio + action informing the connection is back again. But if this connection drops + after a few minutes again - it might be the "connection-failed" rule won't + trigger before an hour later. By adding reset-rule-rate-limits on the + "connection-is-back" rule, it can reset the "connection-failed"'s rate-limit + check, so it that rule will trigger instantly. + +Rule examples +------------- +.. code-block :: ini + + [Rule:iptables] + logfile: messages + regex: .* (.*) kernel: .* IN=(\S*) OUT=.* MAC=.* SRC=(\S* )DST=(\S* ).* PROTO=(\S* )SPT=(\d* )DPT=(\d* ).* + threshold: 1 + + [Rule:lost-connection] + logfile: maillog + regex: lost connection after (.*) from (.*) + reporters: HTTP-DEMO-2 + threshold: 5 + +We declare two rules here, one which looks for a certain pattern which matches +iptables and uses the default reporters. Each time log line in /var/log/messages +matches this rule, the reporters are triggered. It will report the hostname of +the server this happened, the input device, source and destination IP addresses +as well as protocol, source and destination ports. + +The second rule looks for connection issues in /var/maillog and will report +these every 5th issue using only the configured HTTP-DEMO-2 reporter. diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..aa3f9d2 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,28 @@ +.. logactio documentation master file, created by + sphinx-quickstart on Mon Sep 17 10:59:56 2012. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Logactio - simple log file watcher framework +============================================ + +Logactio is a simple framework for watching log files and do certain actions +when some predefined events happens. It's modular by design and can make use +of external reporter modules to handle the actions. + +The use case for logactio is on a running server where you want to alert +users and/or sys-admins when something unexpected happens. + +Simple reporter modules using HTTP/HTTPS, SMTP or AMQP/Qpid are bundled with +logactio. + +Contents: + +.. toctree:: + :maxdepth: 2 + + installing + configuration + starting +.. writingreporters + diff --git a/docs/source/installing.rst b/docs/source/installing.rst new file mode 100644 index 0000000..e0fe317 --- /dev/null +++ b/docs/source/installing.rst @@ -0,0 +1,30 @@ +.. Copyright 2012 David Sommerseth <dazo@users.sourceforge.net> + + This is free software: you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by + the Free Software Foundation, version 2 of the License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see + <http://www.gnu.org/licenses/>. + +.. For notes on how to document Python in RST form, see e.g.: +.. http://sphinx.pocoo.org/domains.html#the-python-domain + +Installing logactio +=================== + +Download and unpack the logactio source code. From a shell, use the provided +*setup.py* utility. + +.. code-block:: bash + + [root@host: ~/logactio] # python setup.py install + +This takes care of installing all the needed files in the proper places. + diff --git a/docs/source/starting.rst b/docs/source/starting.rst new file mode 100644 index 0000000..59ff815 --- /dev/null +++ b/docs/source/starting.rst @@ -0,0 +1,78 @@ +.. Copyright 2012 David Sommerseth <dazo@users.sourceforge.net> + + This is free software: you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by + the Free Software Foundation, version 2 of the License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see + <http://www.gnu.org/licenses/>. + +.. For notes on how to document Python in RST form, see e.g.: +.. http://sphinx.pocoo.org/domains.html#the-python-domain + +Starting logactio +================= + +The only requirement logactio have to be able to start, is the configuration +file which declares log files to watch, what to look for and how to report +when it finds a match. The default location for this file is +*/etc/logactio.cfg*, but this can be overridden by the command line. + +For a normal production setup where the configuration file is in the default +location, this would be sufficient + +.. code-block:: bash + + [user@host: ~]$ logaction -d + +Otherwise, you can tweak logactio a bit. + +.. code-block:: bash + + [user@host: ~]$ logactio --help + Usage: logactio [options] + + Options: + -h, --help show this help message and exit + -d, --daemon Run as a daemon + -p PID-FILE, --pid-file=PID-FILE + Put pid file of logactio in this file + --stdout-redir=FILE Redirect all stdout data to this file (only active + when running as daemon) + -c FILE, --config=FILE + Configuration file for logactio (Default: + /etc/logactio.cfg) + -v, --verbose Increase the log verbosity + -L LOGTYPE, --log-type=LOGTYPE + Should logging go to file or syslog? (default: syslog) + -l LOG-FILE, --log-file=LOG-FILE + Filename of the log file to use + -s SYSLOG-NAME, --syslog-id=SYSLOG-NAME + syslog ident to use for syslog events + --trace On errors, show a backtrace + +If you do not have the configuration file in the standard location, you may +override this as well with *--config=/path/to/my/config*. + +The only privileges logactio requires is to be able to read the configured +log files. Logactio will never try to write to these files. If you use +*--pid-file* logactio needs to have write access to the destination directory +for the pid file. + +By default logactio will do all logging via syslog. If you want to log to a +separate file, add the *--log-type=file* and *--log-file=/path/to/my/log.file*. +When logactio writes to syslog, they are tagged with *logactio*. This may be +modified with the *--syslog-id* argument. + +If you want to run logactio as a daemon, add the *--daemon* argument as well. + +For debugging, adding *--trace* and *--stdout-redir=/path/to/logaction-stdout.log* +may be useful to understand what happens. Also adding more *-v* arguments will +gradually increase the log verbosity. + diff --git a/docs/source/writingreporters.rst b/docs/source/writingreporters.rst new file mode 100644 index 0000000..18d9318 --- /dev/null +++ b/docs/source/writingreporters.rst @@ -0,0 +1,20 @@ +.. Copyright 2012 David Sommerseth <dazo@users.sourceforge.net> + + This is free software: you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by + the Free Software Foundation, version 2 of the License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see + <http://www.gnu.org/licenses/>. + +.. For notes on how to document Python in RST form, see e.g.: +.. http://sphinx.pocoo.org/domains.html#the-python-domain + +Writing your own reporter modules +================================= |