LOGRAPTOR(8)

NAME
lograptor - Pattern search tool for syslog files

SYNOPSIS

lograptor [options] PATTERN [FILE ...]
lograptor [options] [-e PATTERN | -f PATTERNS_FILE ] [FILE ...]

DESCRIPTION

lograptor is a search tool for system logs saved with legacy BSD syslog format (RFC 3164) or IETF syslog format (RFC 5424).

It's developed as a compact and configurable GREP-like tool, usable for raw or refined searches and to create customizable reports on system logs. The application mixes regex pattern matching search with scope delimiters and a configurable set of filters. You can configure additional application pattern rules using the classical regexp syntax. lograptor can also produce and publish reports in various formats. Reporting can be automated using cron.

For lograptor's configuration see lograptor-conf(5).

For more information on adding and configuring applications see lograptor-apps(5).

OPTIONS

  Positional Arguments

[FILE ...]
    Input files. Each argument can be a file path or a glob pathname. A "-" stands for standard input. If no arguments are given then processes all the files included within the scope of the selected applications.

  General Options

--conf FILE
    Use a specific configuration file. For default try to find and use a lograptor.conf file located in the current directory, in the ~/.config/lograptor/ directory, in the ~/.local/etc/lograptor/ directory or in the /etc/lograptor/ directory. If none of them exist then uses the default configuration provided within the package into the subdirectory config/. If you call the program from the command line without other options and arguments a summary of configuration settings is dumped to stdout.

-d [0-4]
    Logging level (default is 2, use 4 for debug). A level of 0 suppress also error messages about nonexistent or unreadable files.

-V, --version
    Show program's version number and exit.

--help
    Show an help page about program options and exit.

  Scope Selection

-a APP[,APP...], --apps APP[,APP...]
    Process the log lines related to an application. An app name is valid when a configuration file is defined. For default all apps defined and enabled are processed.

--hosts HOSTNAME/IP[,HOSTNAME/IP...]
    Process the log lines related to a comma separated list of hostnames and/or IP addresses. File path wildcards can be used for hostnames.

-F FIELD=PATTERN[,FIELD=PATTERN...], --filter FIELD=PATTERN[,FIELD=PATTERN...]
    Process the log lines that match all the conditions for pattern rule's field values. The filters within a single option are applied with logical conjunction (AND). Multiple -F options are used with logical disjunction (OR).

--time HH:MM,HH:MM
    Process the log lines related to a time range.

--date [YYYY]MMDD[,[YYYY]MMDD]
    Restrict the search scope to a date or a date interval.

--last [hour|day|week|month|Nh|Nd|Nw|Nm]
    Restrict the search scope to a previous time period.

  Matcher Selection

-G, --ruled
    Use patterns and application rules matching. This is the default.

-X, --unruled
    Use patterns only. Application pattern rules are skipped. This option is incompatible with report and filtering options.

-U, --unparsed
    Match the patterns but select the lines that don't match any application rule. This option is useful for finding anomalies and for application's rules debugging. This option is incompatible with filters (option -F).

  Matching Control

-e PATTERN, --regexp=PATTERN
    The search pattern. Use the option more times to specify multiple search patterns. Empty patterns are skipped.

-f FILE, --file=FILE
    Obtain patterns from FILE, one per line. Blank lines are skipped. If this option is used multiple times or is combined with the -e (--regexp) option, search for all patterns given. An empty file contains zero patterns, and therefore matches nothing.

-i, --ignore-case
    Ignore case distinctions in matching, so that characters that differ only in case match each other.

-v, --invert-match
    Invert the sense of matching, to select non-matching lines.

-w, --word-regexp
    Force PATTERN to match only whole words. The matching substring must either be at the beginning of the line, or preceded by a non-word constituent character. Similarly, it must be either at the end of the line or followed by a non-word constituent character. Word-constituent characters are letters, digits, and the underscore.

  General Output Control

--output CHANNEL[,CHANNEL...]
    Send output to a comma separated list of channels. Channels have to be defined in the configuration file. For default the output is sent to stdout channel.

-c, --count
    Suppress normal output; instead print a count of matching lines for each input file. With the -v/--invert-match option count non-matching lines.

--color [(auto|always|never)]
    Use markers to highlight the matching strings. The colors are defined by the environment variable LOGRAPTOR_COLORS.

-L, --files-without-match
    Print only names of FILEs containing no match.

-l, --files-with-match
    Print only names of FILEs containing matches. The scanning will stop on the first match.

-m NUM, --max-count NUM
    Stop reading a file after NUM matching lines. When -c/--count option is also used, lograptor does not output a count greater than NUM. When using -t/--thread option the limit is related to the number of threads and not to the number of lines matched.

-o, --only-matching
    Print only the matched (non-empty) parts of a matching line, with each such part on a separate output line.

-q, --quiet
    Quiet; do not write anything to standard output. Exit immediately with zero status if any match is found, even if an error was detected.

-s, --no-messages
    Suppress error messages about nonexistent or unreadable files. Equivalent to -d 0.

  Output Data Control

--report [NAME]
    Produce a report at the end of processing. If NAME is omitted that use the default report defined in the lograptor configuration file.

--ip-lookup
    Translate IP addresses to DNS names. Use a DNS local cache to improve the speed of the lookups and reduce the network service's load.

--uid-lookup
    Translate UIDs to usernames. The configured local system authentication is used for lookups, so it must be inherent to the UIDs that have to be resolved.

--anonymize
    Anonymize defined application rule's fields value. Translation tables are built in volatile memory for each run. The anonymous tokens have the format FILTER_NNN. This option overrides --ip-lookup and --uid-lookup options. WARNING: this is an experimental feature.

  Output Line Prefix Control

-n, --line-number
    Prefix each line of output with the line number within its input file.

-H, --with-filename
    Print the file name for each match. This is the default when there is more than one file to search.

-h, --no-filename
    Suppress the prefixing of file names on output. This is the default when there is only one file (or only standard input) to search.

  Context Line Control

-T, --thread
    The context is the log thread of the application. The thread rules defined in application configuration files are used.

-A NUM, --after-context NUM
    Print NUM lines of trailing context after matching lines. Places a line containing a group separator (described under --group-separator option) between contiguous groups of matches. With the -o or --only-matching option, this has no effect and a warning is given.

-B NUM, --before-context NUM
    Print NUM lines of leading context before matching lines. Places a line containing a group separator (described under --group-separator) between contiguous groups of matches. With the -o or --only-matching option, this has no effect and a warning is given.

-C NUM, --context NUM
    Print NUM lines of output context. Places a line containing a group separator (described under --group-separator) between contiguous groups of matches. With the -o or --only-matching option, this has no effect and a warning is given.

--group-separator SEP
    Use SEP as a group separator. By default SEP is double hyphen (--).

--no-group-separator
    Use empty string as a group separator.

  File and Directory Selection

-r, --recursive
    Read all files under each directory, recursively, following symbolic links only if they are on the command line.

-R, --dereference-recursive
    Read all files under each directory, recursively. Follow all symbolic links, unlike -r.

--exclude GLOB
    Skip any file with a name suffix that matches the pattern GLOB, using wildcard matching; a name suffix is either the whole name, or any suffix starting after a / and before a +non-/. When searching recursively, skip any subfile whose base name matches GLOB; the base name is the part after the last /. A pattern can use
    *
    , ?, and [...] as wildcards, and to quote a wildcard or backslash character literally.

--exclude-from FILE
    Skip files whose base name matches any of the file-name globs read from FILE (using wildcard matching as described under --exclude).

--exclude-dir DIR
    Skip any command-line directory with a name suffix that matches the pattern GLOB. When searching recursively, skip any subdirectory whose base name matches GLOB. Ignore any redundant trailing slashes in GLOB.

--include GLOB
    Search only files whose base name matches GLOB (using wildcard matching as described under --exclude).

FILES

/etc/lograptor/lograptor.conf

/etc/lograptor/conf.d/*.conf

/usr/bin/lograptor

AUTHORS

Davide Brunato <brunato@sissa.it>

SEE ALSO

lograptor.conf(5), lograptor-apps(5), lograptor-examples(5),

AUTHOR
Davide Brunato

COPYRIGHT
2012-2017, Scuola Internazionale Superiore di Studi Avanzati, Trieste (Italy)