.\" Process this file with
.\" groff -man -Tascii
.\"
.\" Copyright (C) 2016 Red Hat
.\"
.\" This file is part of tlog.
.\"
.\" Tlog 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; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" Tlog 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 tlog; if not, write to the Free Software
.\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
.\"
.TH tlog-rec-session.conf "5" "February 2016" "Tlog"
.SH NAME
tlog-rec-session.conf \- tlog-rec-session configuration file

.SH DESCRIPTION
.B tlog-rec-session.conf
is a JSON-format configuration file for
.B tlog-rec-session
program.
Contrary to the strict JSON specification, both C and C++ style comments are
allowed in the file.

The file must contain a single JSON object with the objects and fields
described below.
Almost all of them are optional and assume a default value.
However, those that do require a value can still be omitted and specified to
.B tlog-rec-session
in other ways: through environment variables or command line.

.SH OBJECTS AND FIELDS
.SS Root object
.TP
shell (string)
The path to the shell executable which should be spawned.

Default: "/bin/bash"
.TP
notice (string)
A message which will be printed before starting
recording and the user shell. Can be used to warn
the user that the session is recorded.

Default: "\\nATTENTION! Your session is being recorded!\\n\\n"
.TP
latency (integer)
The number of seconds to cache captured data for before logging.
The encoded data which does not reach payload size
stays in memory and is not logged until this number of
seconds elapses.

Minimum: 1
.br
Default: 10
.TP
payload (integer)
The maximum encoded data (payload) size per message, bytes.
As soon as payload exceeds this number of bytes,
it is formatted into a message and logged.

Minimum: 32
.br
Default: 2048
.TP
log (object)
Logged data set object, see below.
.br
.TP
limit (object)
Logging limit object, see below.
.br
.TP
file (object)
File writer object, see below.
.br
.TP
syslog (object)
Syslog writer object, see below.
.br
.TP
journal (object)
Journal writer object, see below.
.br
.TP
writer (string)
The type of "log writer" to use for logging. The writer needs
to be configured using its dedicated parameters.

One of: "journal", "syslog", "file"
.br
Default: "journal"
.SS log - Logged data set object
.TP
input (boolean)
If true, user input is logged.

Default: false
.TP
output (boolean)
If true, terminal output is logged.

Default: true
.TP
window (boolean)
If true, terminal window size changes are logged.

Default: true
.SS limit - Logging limit object
.TP
rate (integer)
The maximum rate messages could be logged at, bytes/sec.

Minimum: 0
.br
Default: 16384
.TP
burst (integer)
The number of bytes by which logged messages are allowed to exceed
the rate limit momentarily, i.e. "burstiness".

Minimum: 0
.br
Default: 32768
.TP
action (string)
The logging limit action.
If set to "pass" no logging limits will be applied.
If set to "delay", logging will be throttled.
If set to "drop", messages exceeding limits will be dropped.

One of: "pass", "delay", "drop"
.br
Default: "pass"
.SS file - File writer object
.TP
path (string)
The "file" writer log file path.

No default.
.SS syslog - Syslog writer object
.TP
facility (string)
The syslog facility "syslog" writer should use for messages.

One of: "auth", "authpriv", "cron", "daemon", "ftp", "kern", "local0", "local1", "local2", "local3", "local4", "local5", "local6", "local7", "lpr", "mail", "news", "syslog", "user", "uucp"
.br
Default: "authpriv"
.TP
priority (string)
The syslog priority "syslog" writer should use for messages.

One of: "emerg", "alert", "crit", "err", "warning", "notice", "info", "debug"
.br
Default: "info"
.SS journal - Journal writer object
.TP
priority (string)
The syslog-style priority "journal" writer should use for messages.

One of: "emerg", "alert", "crit", "err", "warning", "notice", "info", "debug"
.br
Default: "info"
.TP
augment (boolean)
If true, the "journal" writer copies the following JSON fields
to Journal fields: user -> TLOG_USER, session -> TLOG_SESSION,
rec -> TLOG_REC, and id -> TLOG_ID.

Default: true

.SH EXAMPLES
.TP
A configuration specifying only a shell:
.nf

{
    "shell": "/usr/bin/zsh"
}
.fi

.TP
A configuration enabling logging user input:
.nf

{
    "log": {
        "input": true
    }
}
.fi

.TP
A configuration specifying logging to a file:
.nf

{
    "writer": "file",
    "file" : {
        "path": "/var/log/tlog-rec-session.log"
    }
}
.fi

.SH SEE ALSO
tlog-rec-session(8), http://json.org/

.SH AUTHOR
Nikolai Kondrashov <spbnick@gmail.com>