.. SPDX-FileCopyrightText: Copyright 2012-  David Sommerseth <dazo@eurephia.org>
   SPDX-License-Identifier: GPL-2.0-only

.. 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: ~]$ logactio -d

Otherwise, you can tweak logactio a bit.

.. code-block:: bash

   [user@host: ~]$ logactio --help
   usage: logactio [-h] [-d] [-p PID-FILE] [--stdout-redir FILE] [-c FILE] [-v]
                   [-L {syslog,file,stdout}] [-l LOG-FILE] [-s SYSLOG-NAME]
                   [--trace]

   Simple framework for executing actions on certain log events

   options:
     -h, --help            show this help message and exit
     -d, --daemon          Run as a daemon
     -p, --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, --config FILE     Configuration file for logactio (Default:
                           /etc/logactio.cfg)
     -v, --verbose         Increase the log verbosity
     -L, --log-type {syslog,file,stdout}
                           Should logging go to file or syslog? (default: syslog)
     -l, --log-file LOG-FILE
                           Filename of the log file to use
     -s, --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.  To log to stdout, use
*--log-type=stdout*

If you want to run logactio as a daemon, add the *--daemon* argument as well.

For debugging, adding *--trace* and *--stdout-redir=/path/to/logactio-stdout.log*
may be useful to understand what happens.  Also adding more *-v* arguments will
gradually increase the log verbosity.