path: root/litterbox.1

.Dd May 21, 2020
.Dt LITTERBOX 1
.Os
.
.Sh NAME
.Nm litterbox
.Nd IRC logger
.
.Sh SYNOPSIS
.Nm
.Op Fl Qqv
.Op Fl N Ar network
.Op Fl c Ar cert
.Op Fl d Ar path
.Op Fl h Ar host
.Op Fl j Ar join
.Op Fl k Ar priv
.Op Fl l Ar limit
.Op Fl n Ar nick
.Op Fl p Ar port
.Op Fl u Ar user
.Op Fl w Ar pass
.Op Ar config ...
.
.Nm
.Op Fl d Ar path
.Fl i | m
.
.Nm
.Op Fl d Ar path
.Fl b Ar path
.
.Sh DESCRIPTION
The
.Nm
daemon logs IRC (over TLS) activity to a database
which may be queried with
.Xr scoop 1 .
Messages, notices, joins, parts, quits, kicks,
nick changes,
topic changes
bans and unbans
are recorded in the database.
The contents of messages are indexed for full-text search.
.
.Pp
The
.Nm
daemon
may be connected to the
.Xr pounce 1
IRC bouncer alongside regular clients
to provide central logging
and a simple search query interface with
.Fl q .
.
.Pp
The database must be initialized with
.Fl i .
If the database format has changed,
it will be migrated automatically when
.Nm
starts,
or can be migrated explicitly with
.Fl m .
Instances of
.Nm
connected to different IRC networks
can share the same database.
.
.Pp
Options can be loaded from
files listed on the command line.
Files are searched for in
.Pa $XDG_CONFIG_DIRS/litterbox
unless the path starts with
.Ql /
or
.Ql \&. .
Each option is placed on a line,
and lines beginning with
.Ql #
are ignored.
The options are listed below
following their corresponding flags.
.
.Pp
The arguments are as follows:
.
.Bl -tag -width "-h host"
.It Fl N Ar name , Cm network = Ar name
Set the network name to be used
if the server does not send
.Sy RPL_ISUPPORT NETWORK .
The default is the server hostname.
.
.It Fl Q , Cm public-query
Enable the public search query interface.
This allows anyone to perform searches
in private messages to
.Nm .
Search results are limited to channels
on the current network.
.
.Pp
Searches use the full-text search index.
The searchable columns are
.Li channel ,
.Li nick ,
.Li user ,
.Li target ,
.Li message .
For search query syntax, see
.Aq Lk https://www.sqlite.org/fts5.html#full_text_query_syntax .
.
.It Fl b Ar path
Perform a live database backup to
.Ar path
and exit.
This operation requires SQLite version 3.27.0 or newer.
.
.It Fl c Ar path , Cm cert = Ar path
Load the TLS client certificate from
.Ar path
and authenticate with SASL EXTERNAL,
also known as CertFP.
If the private key is in a separate file,
it is loaded with
.Fl k .
.
.It Fl d Ar path , Cm database = Ar path
Set the path to the database file.
The default paths are documented in
.Sx FILES .
.
.It Fl h Ar host , Cm host = Ar host
Connect to
.Ar host .
.
.It Fl i
Initialize the database and exit.
.
.It Fl j Ar chan , Cm join = Ar chan
Join the comma-separated list of channels
.Ar chan .
.
.It Fl k Ar path , Cm priv = Ar path
Load the TLS client private key from
.Ar path .
.
.It Fl l Ar limit , Cm limit = Ar limit
Limit the number of results
in the search query interface
enabled by
.Fl Q
or
.Fl q .
The default limit is 10.
.
.It Fl m
Migrate the database to the latest format
and exit.
.
.It Fl n Ar nick , Cm nick = Ar nick
Set the nickname to
.Ar nick .
The default nickname is
.Dq litterbox .
.
.It Fl p Ar port , Cm port = Ar port
Connect to
.Ar port .
The default port is 6697.
.
.It Fl q , Cm private-query
Enable the private search query interface.
When connected to
.Xr pounce 1 ,
this allows the user to
private message their own nickname
with search queries.
Search results are limited to the current network.
.
.Pp
Searches use the full-text search index.
The searchable columns are
.Li channel ,
.Li query ,
.Li nick ,
.Li user ,
.Li target ,
.Li message .
For search query syntax, see
.Aq Lk https://www.sqlite.org/fts5.html#full_text_query_syntax .
.
.It Fl u Ar user , Cm user = Ar user
Set the username to
.Ar user .
The default username is the same as the nickname.
.
.It Fl v , Cm verbose
Write sent and received IRC messages
as well as SQL INSERT statements
to standard error.
.
.It Fl w Ar pass , Cm pass = Ar pass
Log in with the server password
.Ar pass .
.El
.
.Ss Service Configuration
Add the following to
.Pa /etc/rc.conf
to enable the
.Nm
daemon:
.Bd -literal -offset indent
litterbox_enable="YES"
.Ed
.
.Pp
To use the database and configuration files of a user,
add the following:
.Bd -literal -offset indent
litterbox_user="user"
litterbox_env="HOME=/home/user"
.Ed
.
.Pp
The
.Nm
service supports profiles
for running multiple instances.
Set
.Va litterbox_profiles
to a space-separated list of names.
Flags for each profile will be set from
.Va litterbox_${profile}_flags .
For example:
.Bd -literal -offset indent
litterbox_profiles="example1 example2"
litterbox_example1_flags="example1.conf"
litterbox_example2_flags="example2.conf"
.Ed
.
.Pp
The commands
.Cm start , stop ,
etc.\&
will operate on the profile given as an additional argument,
or on all profiles without an additional argument.
.
.Sh FILES
.Bl -tag -width Ds
.It Pa $XDG_CONFIG_DIRS/litterbox
Configuration files are searched for first in
.Ev $XDG_CONFIG_HOME ,
usually
.Pa ~/.config ,
followed by the colon-separated list of paths
.Ev $XDG_CONFIG_DIRS ,
usually
.Pa /etc/xdg .
.
.It Pa $XDG_DATA_DIRS/litterbox/litterbox.sqlite
The database file is searched for first in
.Ev $XDG_DATA_HOME ,
usually
.Pa ~/.local/share ,
followed by the colon-separated list of paths
.Ev $XDG_DATA_DIRS ,
usually
.Pa /usr/local/share:/usr/share .
.It Pa ~/.local/share/litterbox/litterbox.sqlite
The most likely default path to the database file.
.El
.
.Sh EXAMPLES
Configuration on the command line:
.Bd -literal -offset indent
litterbox -Q -h irc.example.org -j '#example'
.Ed
.
.Pp
Configuration in a file:
.Bd -literal -offset indent
host = irc.example.org
join = #example
public-query
.Ed
.
.Sh SEE ALSO
.Xr scoop 1 ,
.Xr unscoop 1
.
.Sh STANDARDS
.Bl -item
.It
.Rs
.%R RFC 2812
.%A C. Kalt
.%T Internet Relay Chat: Client Protocol
.%I IETF
.%D April 2000
.%U https://tools.ietf.org/html/rfc2812
.Re
.
.It
.Rs
.%A Kyle Fuller
.%A St\('ephan Kochen
.%A Alexey Sokolov
.%A James Wheare
.%T IRCv3.2 server-time Extension
.%I IRCv3 Working Group
.%U https://ircv3.net/specs/extensions/server-time-3.2
.Re
.
.It
.Rs
.%A Waldo Bastian
.%A Ryan Lortie
.%A Lennart Poettering
.%T XDG Base Directory Specification
.%D November 24, 2010
.%U https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
.Re
.
.It
.Rs
.%A William Pitcock
.%A Jilles Tjoelker
.%T IRCv3.1 SASL Authentication
.%I IRCv3 Working Group
.%U https://ircv3.net/specs/extensions/sasl-3.1.html
.Re
.El
.
.Ss Extensions
The
.Nm
daemon implements the
.Sy causal.agency/consumer
and
.Sy causal.agency/passive
vendor-specific IRCv3 capabilities
implemented by
.Xr pounce 1 .
.
.Sh AUTHORS
.An June Bug Aq Mt june@causal.agency
.
.Sh BUGS
Send mail to
.Aq Mt list+litterbox@causal.agency
or join
.Li #ascii.town
on
.Li chat.freenode.net .