update readme & docs
authorAndrew Lorimer <andrew@lorimer.id.au>
Sun, 8 Sep 2019 00:55:24 +0000 (10:55 +1000)
committerAndrew Lorimer <andrew@lorimer.id.au>
Sun, 8 Sep 2019 00:55:24 +0000 (10:55 +1000)
README.md
doc/Makefile
doc/source/conf.py
doc/source/index.rst
logparse.conf [new file with mode: 0644]
logparse/formatting.py
logparse/interface.py
logparse/load_parsers.py
setup.py
index e5a293bdc005e1a0a58a923c5e90a6ea9b3d27f3..ea1fe17d6c91f7d64fbcc1e714db3d7cb60fe37c 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,30 +1,28 @@
 # logparse
 
 # logparse
 
-([source](https://git.lorimer.id.au/logparse.git/)) // written by [Andrew Lorimer](https://lorimer.id.au)
+Logparse is a simple and extensible log analyser which parses and summaries medium-term server logs (up to around 30 days old). It reports notable events and statistics reported from common server programs, and has a comprehensive API to allow users to write their own parsers for custom services.
 
 
-This is a utility to analyse medium-term logs (up to around 30 days old) on servers. It summarises notable events and statistics reported from several programs. At the moment, logparse can interface with:
+Logparse is also integrated with systemd's `logrotate` to optionally rotate logs only after they have been summarised, and the user may choose to get an email (requires postfix) or a static HTML/plaintext file with the log summary. As an added feature, IP addresses from ssh/samba/apache logs may be resolved to either hostnames or FQDNs.
 
 
-- sshd (number of logins, list users & clients)
-- sudo (number of sessions, users, commands)
-- cron (list commands)
-- [nameget](https://git.lorimer.id.au/scripts.git/tree/nameget.sh) (list successful/failed downloads)
-- apache (list requests, clients, user agents, bytes transferred, errors)
-- smbd (number of logins, list users & clients)
-- postfix (list recipients and bytes sent)
-- zfs (srub data, usage data)
-- lmsensors (system, CPU, per-core, per-disk)
-- du (specify paths to show usage and change since last analysis)
+Configuration is through the file `/etc/logparse.conf`, in INI format. A description of the configuration variables is shown below at :ref:`configuration`.
 
 
-Support for further services and custom scripts is planned.
+Some features require logparse to be run as root (primarily log rotation). It is recommended to set it up on a cron job on a weekly basis.
 
 
-logparse is also integrated with systemd logrotate to optionally rotate logs only after they have been summarised, and the user may choose to get an email (requires postfix) or a static HTML page with the log summary. As an added feature, IP addresses from ssh/samba/apache may be resolved to either hostnames or FQDNs.
+The program is based on a model of independent **parsers** (consisting of Python modules) which analyse logs from a particular service. Logparse comes with a range of these built in, but additional parsers can be written in Python and placed in `/usr/share/logparse/parsers`. At the moment, the built-in parsers are:
 
 
-Configuration is through the file `/etc/logparse.conf`, in yaml format.
+- cron (DEPRECATED) - number of commands, list commands (root user only)
+- cron-journald - number of commands, list commands, list commands per user (requires libsystemd)
+- httpd - list requests, clients, user agents, bytes transferred, no. of errors
+- mem - get installed/usable/free memory
+- postfix - list recipients and bytes sent
+- smbd - number of logins, list users & clients
+- sshd (DEPRECATED) - logins by user/hostname, attempted root logins, invalid users
+- sshd-journald - logins by user/hostname, attempted root logins, invalid users (requires libsystemd)
+- sudo - number of sessions, list users and commands
+- sysinfo - hostname, OS, OS version, platform, processors
+- temperature - instantaneous temperatures of motherboard, CPU, cores, disks
+- zfs - zpool scrub reports, disk usage
 
 
-Note that logparse must be run as root (preferably as a cron job). This is required for temperature reading and for writing to `/var/log/`.
+For more information, see `logparse(8)` by running `man logparse`.
 
 
-### Planned features:
-
-- output to standalone HTML or plaintext file
-- email attached PDF
-- specify user to send mail from
+Website: <https://git.lorimer.id.au/logparse.git>
index ff5817bd28b44818deb33b080abc93dfc268ef0e..cb830894db9345c62e14c6a7bc8e1a3691a69629 100644 (file)
@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+SPHINXBUILD   = python3 -msphinx
 SPHINXPROJ    = logparse
 SOURCEDIR     = source
 BUILDDIR      = build
 SPHINXPROJ    = logparse
 SOURCEDIR     = source
 BUILDDIR      = build
@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-       @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
+       @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
index 3d190cc0ea1482897d27fb196c46e4f4fbd9de1c..9758585d1c06309e0741a33161ee5e07d434f2af 100644 (file)
 # 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.
 # 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.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath("../../"))
+import logparse
 
 
 # -- General configuration ------------------------------------------------
 
 
 # -- General configuration ------------------------------------------------
@@ -32,6 +33,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc',
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc',
+    'sphinxarg.ext',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
@@ -39,8 +41,10 @@ extensions = ['sphinx.ext.autodoc',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode']
 
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode']
 
+programoutput_use_ansi = True
+
 # Add any paths that contain templates here, relative to this directory.
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['.templates']
+templates_path = ['templates/basic']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -53,8 +57,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'logparse'
 
 # General information about the project.
 project = 'logparse'
-copyright = '2019, Andrew Lorimer'
-author = 'Andrew Lorimer'
+author = "Andrew Lorimer https://lorimer.id.au"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -89,7 +92,7 @@ todo_include_todos = True
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'haiku'
 
 # 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
 
 # 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
@@ -100,7 +103,9 @@ html_theme = 'alabaster'
 # 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".
 # 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']
+#html_static_path = ['static']
+#html_style = 'basic.css'
+
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -109,8 +114,6 @@ html_static_path = ['.static']
 # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
 html_sidebars = {
     '**': [
 # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
 html_sidebars = {
     '**': [
-        'relations.html',  # needs 'show_related': True theme option to display
-        'searchbox.html',
     ]
 }
 
     ]
 }
 
@@ -155,8 +158,8 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'logparse', 'logparse Documentation',
-     [author], 1)
+    (master_doc, 'logparse', 'simple log analyser for servers',
+     [author], 8)
 ]
 
 
 ]
 
 
index 07ea15e097699023a21b62ae9a9fb18b2c687b04..a3297d4d886900fbf5b63fbe1634fd7a927f2629 100644 (file)
-.. logparse documentation master file, created by
-   sphinx-quickstart on Sat Aug 31 23:02:08 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-logparse
-====================================
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-Introduction
-############
-
-Logparse is a simple and extensible log analyser which parses and summaries analyse medium-term server logs (up to around 30 days old). It reports notable events and statistics reported from common server programs. The program is based on a model of independent **parsers** (consisting of Python modules) which analyse logs from a particular service. Logparse comes with a range of these built in, but additional parsers can be written in Python and placed in `/usr/share/logparse/parsers`. At the moment, the default parsers are:
-
-+-----------------+-----------------------------------------------------------------------+---------------------------+
-| Parser          | Output                                                                | Dependencies              |
-+=================+=======================================================================+===========================+
-| httpd           | list requests, clients, user agents, bytes transferred, no. of errors | Apache                    |
-+-----------------+-----------------------------------------------------------------------+---------------------------+
-| cron            | number of commands, list commands (root user only)                    |                           |
-+-----------------+-----------------------------------------------------------------------+---------------------------+
-| cron-journald   | number of commands, list commands, list commmands per user            | libsystemd                |
-+-----------------+-----------------------------------------------------------------------+---------------------------+
-| mem             | get installed, usable, and free memory                                |                           |
-+-----------------+-----------------------------------------------------------------------+---------------------------+
-| postfix         | list recipients and bytes sent                                        | postfix                   |
-+-----------------+-----------------------------------------------------------------------+---------------------------+
-| smbd            | number of logins, list users and clients                              + samba                     |
-+-----------------+-----------------------------------------------------------------------+---------------------------+
-| sshd            | logins by user/hostname, attempted root logins, invalid users         |                           |
-+-----------------+                                                                       +---------------------------+
-| sshd-journald   |                                                                       | libsystemd                |
-+-----------------+-----------------------------------------------------------------------+---------------------------+
-| sudo            | number of sudo sessions, list users and commands                      +                           |
-+-----------------+-----------------------------------------------------------------------+---------------------------+
-| sysinfo         | hostname, OS, OS version, platform, processor(s)                      +                           |
-+-----------------+-----------------------------------------------------------------------+---------------------------+
-| temperature     | instantaneous temperatures of motherboard, CPU, cores, disks          + hddtemp daemon, lmsensors |
-+-----------------+-----------------------------------------------------------------------+---------------------------+
-| zfs             | zpool scrub reports, disk usage                                       + zfsonlinux + cron job     |
-+-----------------+-----------------------------------------------------------------------+---------------------------+
-
-Support for further services and custom scripts is planned.
+-----------
+logparse(8)
+-----------
+
+.. _synopsis:
+
+========
+Synopsis
+========
+
+`logparse` [options]
+
+.. _description:
+
+===========
+Description
+===========
+
+Logparse is a simple and extensible log analyser which parses and summaries medium-term server logs (up to around 30 days old). It reports notable events and statistics reported from common server programs, and has a comprehensive API to allow users to write their own parsers for custom services.
 
 Logparse is also integrated with systemd's `logrotate` to optionally rotate logs only after they have been summarised, and the user may choose to get an email (requires postfix) or a static HTML/plaintext file with the log summary. As an added feature, IP addresses from ssh/samba/apache logs may be resolved to either hostnames or FQDNs.
 
 
 Logparse is also integrated with systemd's `logrotate` to optionally rotate logs only after they have been summarised, and the user may choose to get an email (requires postfix) or a static HTML/plaintext file with the log summary. As an added feature, IP addresses from ssh/samba/apache logs may be resolved to either hostnames or FQDNs.
 
-Configuration is through the file `/etc/logparse.conf`, in yaml format.
+Configuration is through the file `/etc/logparse.conf`, in INI format. A description of the configuration variables is shown below at :ref:`configuration`.
 
 Some features require logparse to be run as root (primarily log rotation). It is recommended to set it up on a cron job on a weekly basis.
 
 
 Some features require logparse to be run as root (primarily log rotation). It is recommended to set it up on a cron job on a weekly basis.
 
-Indices and tables
+.. _usage:
+
+======
+Usage
+======
+.. argparse::
+   :module: logparse.interface
+   :func: get_argparser
+   :prog: logparse
+   :nodescription: True
+
+.. _parsers:
+
+=======
+Parsers
+=======
+
+The program is based on a model of independent **parsers** (consisting of Python modules) which analyse logs from a particular service. Logparse comes with a range of these built in, but additional parsers can be written in Python and placed in `/usr/share/logparse/parsers`. At the moment, the built-in parsers are:
+
+- cron (DEPRECATED) - number of commands, list commands (root user only)
+- cron-journald - number of commands, list commands, list commands per user (requires libsystemd)
+- httpd - list requests, clients, user agents, bytes transferred, no. of errors
+- mem - get installed/usable/free memory
+- postfix - list recipients and bytes sent
+- smbd - number of logins, list users & clients
+- sshd (DEPRECATED) - logins by user/hostname, attempted root logins, invalid users
+- sshd-journald - logins by user/hostname, attempted root logins, invalid users (requires libsystemd)
+- sudo - number of sessions, list users and commands
+- sysinfo - hostname, OS, OS version, platform, processors
+- temperature - instantaneous temperatures of motherboard, CPU, cores, disks
+- zfs - zpool scrub reports, disk usage
+
+.. _configuration:
+
+=============
+Configuration
+=============
+
+Logparse can be configured with various options in the file `/etc/logparse/logparse.conf`. Alternatively, the configuration file may be placed elsewhere and referenced with the `-c|--config` command line option.
+
+Configuration files are written in INI format and interpreted using the standard Python :py:mod:`configparser` module. The file is divided into sections denoted by a line with the section name in square brackets, e.g. `[logparse]` for the section called logparse (this is the main section where global options are placed). Other sections are defined for each parser, e.g. `[httpd]` for the section of configuration values for the httpd parser. For more information on configuration syntax, see <https://docs.python.org/3/library/configparser.html#supported-ini-file-structure>.
+
+############################################
+General configuration (`[logparse]` section)
+############################################
+
+output
+  File to which the logparse output (HTML or plaintext) is saved. If empty, no output is written. Analogous to the command line option -d|--destination which overrides this config value. Default: empty
+overwrite
+  Whether to automatically overwrite an existing output file. Default: false
+title
+  Title for HTML and plaintext, shown at the top of the output. This string supports the standard variables which are substituted for various metadata in the program (see :ref:`variables`). Default: logparse
+maxlist
+  Maximum number of regular text items to show in bulleted lists, e.g. user agents for the httpd parser. Default: 10
+maxcmd
+  Maximum number of command items to show in bulleted lists, e.g. recently executed commands in the cron parser. Default: 6
+resolve-domains
+  Global setting for resolution of IP addresses into domains. If set to `ip`, logparse will never resolve IP addresses into domains. If set to `fqdn`, IPs will be resolved to show full the full hostname and domain. If set to `fqdn-implicit`, FQDNs will be shown except for local addresses which just show the hostname. If set to `host-only`, only the first segment of the FQDN is shown (i.e. the hostname). This configuration value is passed to the :py:meth:`logparse.util.resolve` function which can be implemented by parsers. This option can also be set in individual parsers, where it is called `resolve-domains-x` where x is the name of the parser. These parser-specific declerations override the global one. Default: fqdn
+rotate
+  Whether to rotate logs using systemd's logrotate utility. Analogous to the command line option -r|--rotate and -nr|--no-rotate which override this configuration value. Default: false
+verbose
+  High level of debug output. Analogous to the command line option -v|--verbose. Default: false
+quiet
+  No output to stdout except for printing the resulting output (enabled with the `-p|--print` command line option) and critical errors. Analogous to the command line option -q|--quiet. Default: false
+hostname-path
+  Path to file containing the hostname of the current machine (FQDN or not). This is used to identify the machine in the log output. Default: /etc/hostname
+parsers
+  Space-separated list of parsers to enable. If empty, all the included parsers are run except for deprecated ones. Analogous to the command line option -l|--logs. Default: empty
+ignore-parsers
+  Space-separated list of parsers to ignore (i.e. not execute). If empty, no parsers are ignored. Analogous to the command line option -nl|--ignore-logs. Default: empty
+
+##############################################
+HTML specific configuration (`[html]` section)
+##############################################
+
+header
+  Path to a header template which will be prepended to HTMl files and HTML emails. This template includes the entire <head> section and the <body> tag, and by default it outputs a title and some basic metadata at the top of the page. The template file can include variables for substitution, see :ref:`variables`. Default: /etc/logparse/header.html
+css
+  Path to a CSS stylesheet which will be linked or converted to inline tags for all HTML output (files and email). Default: /etc/logparse/main.css
+embed-styles
+  Whether to convert the stylesheet to inline tags. This is enforced for all HTML emails, and this option allows this same conversion for standalone files. This is done using the :py:mod:`premailer` package. Default: false
+css-relpath
+  If embed-styles is set to false, this option will convert the URL of the stylesheet (supplied by the css option) into a path relative to the output directory (if writing to a file) or the current directory (if outputting to stdout). Otherwise, the stylesheet is linked to exactly as supplied in the css option. Default: true
+
+#####################################################
+Plain-text specific configuration (`[plain]` section)
+#####################################################
+plain
+  Enable plaintext output instead of HTML. Analogous to the -p|--print command line option. Default: false
+
+linewidth
+  Limit regular text lines to this number of characters. Note tables do not obey this variable (this is on the todo list). Default: 80
+
+#####################################
+Log file locations (`[logs]` section)
+#####################################
+
+This section defines paths to log files used for each parser. These paths may vary depending on the operating system and service configuration. Any value can be added to this section, so user-supplied parsers can get their logfile locations from here as well. However, there is currently no mechanism of setting default values for user-supplied parsers, so defaults must be set in the parser files themselves.
+
+auth
+  Path to the system's authentication log. Default: /var/log/auth.log
+cron
+  Path to the cron log. Default: /var/log/cron.log
+cpuinfo
+  Path to the system's CPU info file in procfs. Default: /proc/cpuinfo
+meminfo
+  Path to the system's memory info file in procfs. Default: /proc/meminfo
+sys
+  Path to the system's primary syslog. Default: /var/log/syslog
+smbd
+  Path to the directory for Samba logfiles. Default: /var/log/samba
+zfs
+  Path to a file which contains the output of `zpool status`. Default: /var/log/zpool.log
+postfix
+  Path to the postfix log. Default: /var/log/mail.log
+httpd-access
+  Path to Apache's access log. Default: /var/log/apache2/access.log
+httpd-error
+  Path to Apache's error log. Default: /var/log/apache2/error.log
+
+######################################
+Email configuration (`[mail]` section)
+######################################
+
+Email is sent using the default mail transfer agent (usually Postfix).
+
+to
+  Recipient address. If empty, no email is sent. Analogous to the -t|--to command line option. Default: empty
+from
+  Sender address. If empty, default sender address is determined by the MTA. Default: empty
+subject
+  Text to use as the subject of the message. Variables may be substituted with metadata (see :ref:`variables`). Default: logparse from $hostname
+mailbin
+  Path to the MTA binary (usually Postfix). Default: /usr/bin/mail
+
+.. _variables:
+
+=====================
+Variable substitution
+=====================
+
+In some configuration options, variables may be used to substitute values at runtime. Variable syntax is simply a dollar sign ($) followed by the variable name. The following variables are supported:
+
+`$css`
+  Path to the CSS stylesheet as determined by the css configuration option
+`$date`
+  Date when processing was started
+`$time`
+  Time when processing was started
+`$hostname`
+  Hostname as specified by the hostname configuration option
+`$title`
+  Value of the title variable as determined by the title option
+`$version`
+  Version of logparse
+
+
+.. _api:
+
+=============
+API structure
+=============
+
+Due to the extensible nature of logparse, many of the core functions can be used in user-supplied parsers. Each parser is written in Python as a single-file module which defines a derivative of the Parser class (see `logparse.load_parsers.Parser` below). Therefore parser classes which inherit the base class have access to all the normal formatting and I/O functions which are documented below.
+
+If logparse is to be imported as a Python package into another project for some reason, you can control the general operations with the `logparse.interface` module.
+
+##################
+logparse.interface
 ##################
 
 ##################
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. automodule:: logparse.interface
+   :members:
+
+#####################
+logparse.load_parsers
+#####################
+
+.. automodule:: logparse.load_parsers
+   :members:
+
+###################
+logparse.formatting
+###################
+
+.. automodule:: logparse.formatting
+   :members:
+
+================
+More information
+================
+| Readme    https://git.lorimer.id.au/logparse.git/about
+| Source    https://git.lorimer.id.au/logparse.git/tree
+| Contact   mailto:bugs@lorimer.id.au
diff --git a/logparse.conf b/logparse.conf
new file mode 100644 (file)
index 0000000..b771ac1
--- /dev/null
@@ -0,0 +1,18 @@
+output: /mnt/andrew/temp/logparse/summary.html
+hddtemp:
+  drives:
+    - /dev/sda
+    - /dev/sdc
+    - /dev/sdd
+    - /dev/sde
+  port: 7634
+  show-model: yes
+du:
+  force-write: y
+  paths:
+    - /home/andrew
+    - /mnt/andrew
+rotate: y
+httpd:
+  resolve-domains: ip
+resolve-domains: fqdn-implicit
index 7b666d818d50a01a97e465fe2d602af1d54e807b..7e647a91643cef8bbc889a1b1334ca35f30dd2ee 100644 (file)
@@ -1,3 +1,5 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
 #
 #   format.py
 #   
 #
 #   format.py
 #   
index 90b3ea8e70881dafafc4a0737ff736871ae863c6..bb63f50095c9d2a8f69c1221be43e4a37bf0271b 100644 (file)
@@ -1,12 +1,14 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
 """
 """
-This module is the entrypoint of the `logparse shell command and also contains
+This module is the entrypoint of the `logparse` shell command and also contains
 single-use functions which don't fit elsewhere. All user interaction with
 logparse should be through this module.
 
 This module provides the following methods:
 single-use functions which don't fit elsewhere. All user interaction with
 logparse should be through this module.
 
 This module provides the following methods:
-    main        Set up arguments, config, logging, and execute parsers
-    rotate      Rotate logs using systemd logrotate
-    rotate_sim  Simulate log rotation
+    - `main()`:         Set up arguments, config, logging, and execute parsers
+    - `rotate()`:       Rotate logs using systemd logrotate
+    - `rotate_sim()`:   Simulate log rotation
 """
 
 import logging, logging.handlers
 """
 
 import logging, logging.handlers
@@ -28,23 +30,7 @@ def main():
     # Get arguments
 
     global argparser
     # Get arguments
 
     global argparser
-    argparser = argparse.ArgumentParser(description='grab logs of some common services and send them by email')
-    argparser.add_argument('-t','--to', help='mail recipient (\"to\" address)', required=False)
-    argparser.add_argument('-c', '--config', help='path to config file', required=False, default="/etc/logparse/logparse.conf")
-    argparser.add_argument('-p', '--print', help='print HTML to stdout', required=False, dest='printout', action='store_true', default=False)
-    argparser.add_argument('-d', '--destination', help='file to output HTML', required=False)
-    argparser.add_argument('-f', '--overwrite', help='force overwrite an existing output file', required=False, action='store_true', default=False)
-    argparser.add_argument('-v', '--verbose', help='verbose console/syslog output (for debugging)', required=False, default=False, action='store_true')
-    argparser.add_argument('-r', '--rotate', help='force rotate log files using systemd logrotate (overrides --rotate and "rotate" in logparse.conf)', required=False, default=False, action='store_true')
-    argparser.add_argument('-nr', '--no-rotate', help='do not rotate logfiles (overrides --rotate and logparse.conf)', required=False, default=False, action='store_true')
-    argparser.add_argument('-s', '--simulate', help="test run logrotate (do not actually change files)", required=False, default=False, action="store_true")
-    argparser.add_argument('-l', '--logs', help='services to analyse', required=False)
-    argparser.add_argument('-nl', '--ignore-logs', help='skip these services (takes precedence over -l)', required=False)
-    argparser.add_argument('-es', '--embed-styles', help='make CSS rules inline rather than linking the file', required=False, default=False, action='store_true')
-    argparser.add_argument('-nh', '--plain', help='write/send plain text rather than HTML', required=False, default=False, action='store_true')
-    argparser.add_argument('-q', '--quiet', help='no output to stdout', required=False, default=False, action='store_true')
-    argparser.add_argument('-nm', '--no-mail', help="do not send email (overrides config file)", required=False, default=False, action="store_true")
-    argparser.add_argument('-nw', '--no-write', help="do not write output file (overrides config file)", required=False, default=False, action="store_true")
+    argparser = get_argparser()
 
     # Load config
 
 
     # Load config
 
@@ -176,6 +162,31 @@ def main():
 
     return
 
 
     return
 
+def get_argparser():
+    """
+    Initialise arguments (in a separate function for documentation purposes)
+    """
+    argparser = argparse.ArgumentParser(description='grab logs of some common services and send them by email')
+    argparser.add_argument('-t','--to', help='mail recipient (\"to\" address)', required=False)
+    argparser.add_argument('-c', '--config', help='path to config file', required=False, default="/etc/logparse/logparse.conf")
+    argparser.add_argument('-p', '--print', help='print HTML to stdout', required=False, dest='printout', action='store_true', default=False)
+    argparser.add_argument('-d', '--destination', help='file to output HTML', required=False)
+    argparser.add_argument('-f', '--overwrite', help='force overwrite an existing output file', required=False, action='store_true', default=False)
+    argparser.add_argument('-v', '--verbose', help='verbose console/syslog output (for debugging)', required=False, default=False, action='store_true')
+    argparser.add_argument('-r', '--rotate', help='force rotate log files using systemd logrotate (overrides --rotate and "rotate" in logparse.conf)', required=False, default=False, action='store_true')
+    argparser.add_argument('-nr', '--no-rotate', help='do not rotate logfiles (overrides --rotate and logparse.conf)', required=False, default=False, action='store_true')
+    argparser.add_argument('-s', '--simulate', help="test run logrotate (do not actually change files)", required=False, default=False, action="store_true")
+    argparser.add_argument('-l', '--logs', help='services to analyse', required=False)
+    argparser.add_argument('-nl', '--ignore-logs', help='skip these services (takes precedence over -l)', required=False)
+    argparser.add_argument('-es', '--embed-styles', help='make CSS rules inline rather than linking the file', required=False, default=False, action='store_true')
+    argparser.add_argument('-nh', '--plain', help='write/send plain text rather than HTML', required=False, default=False, action='store_true')
+    argparser.add_argument('-q', '--quiet', help='no output to stdout', required=False, default=False, action='store_true')
+    argparser.add_argument('-nm', '--no-mail', help="do not send email (overrides config file)", required=False, default=False, action="store_true")
+    argparser.add_argument('-nw', '--no-write', help="do not write output file (overrides config file)", required=False, default=False, action="store_true")
+    return argparser
+
+
+
 
 def rotate():
     """
 
 def rotate():
     """
index 44651fcff5b118b335760deb635a2a60796f3b02..f752fb47cb9dd56d2e3e7e40e81f25fa44d48f75 100644 (file)
@@ -1,3 +1,5 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
 """
 A basic "plugin loader" implementation which searches for default packaged and
 user-supplied parser modules and verifies them so they can be executed by
 """
 A basic "plugin loader" implementation which searches for default packaged and
 user-supplied parser modules and verifies them so they can be executed by
@@ -5,8 +7,8 @@ logparse.interface. The requirements for parser modules and classes are
 specified in the docstring of the Parser class.
 
 Classes in this module:
 specified in the docstring of the Parser class.
 
 Classes in this module:
-    Parser          Base class that every parser should inherit
-    ParserLoader    Class used internally by logparse.interface to load parsers
+    - `Parser`:         Base class that every parser should inherit
+    - `ParserLoader`:   Class used internally by `interface.py` to load parsers
 """
 
 import importlib
 """
 
 import importlib
index 7dd8d3e8f1a94d2746ee180e889d24a3b028081f..ede2d0067e31c7ba8531a1980bf05e0dc3dca449 100644 (file)
--- a/setup.py
+++ b/setup.py
@@ -30,7 +30,7 @@ setup(
     packages=['logparse', 'logparse.parsers'],
     python_requires='>=3',              # https://packaging.python.org/guides/distributing-packages-using-setuptools/#python-requires
     install_requires=['premailer', 'requests', 'tabulate'],   # https://packaging.python.org/en/latest/requirements.html
     packages=['logparse', 'logparse.parsers'],
     python_requires='>=3',              # https://packaging.python.org/guides/distributing-packages-using-setuptools/#python-requires
     install_requires=['premailer', 'requests', 'tabulate'],   # https://packaging.python.org/en/latest/requirements.html
-    data_files=[('/etc/logparse', ['logparse.conf', 'header.html', 'main.css'])],   # installed to /etc/logparse
+    data_files=[('/etc/logparse', ['logparse.conf', 'header.html', 'main.css']), ('man/man8', ['doc/build/man/logparse.8'])],
     project_urls={
         'Readme': 'https://git.lorimer.id.au/logparse.git/about',
         'Source': 'https://git.lorimer.id.au/logparse.git',
     project_urls={
         'Readme': 'https://git.lorimer.id.au/logparse.git/about',
         'Source': 'https://git.lorimer.id.au/logparse.git',