path: root/litterbox.1

.Dd April  3, 2021
.Dt LITTERBOX 1
.Os
.
.Sh NAME
.Nm litterbox
.Nd IRC logger
.
.Sh SYNOPSIS
.Nm
.Op Fl Qqv
.Op Fl N Ar network
.Op Fl U Ar url
.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 t Ar trust
.Op Fl u Ar user
.Op Fl w Ar pass
.Op Ar config ...
.
.Nm
.Fl i | m
.Op Fl d Ar path
.
.Nm
.Fl b Ar path
.Op Fl d 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 .
Live backups of the database
can be made with
.Fl b .
Instances of
.Nm
connected to different IRC networks
will 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 / ,
.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 .
.
.It Fl U Ar url | Cm scooper-url = Ar url
Set the base URL of a
.Xr scooper 1
instance
used to construct links to full search results
in response to the search query interface enabled by
.Fl Q
or
.Fl q .
.
.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.
The
.Ar path
is searched for in the same manner
as configuration files.
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.
See
.Sx FILES
for the default paths.
.
.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 .
The
.Ar path
is searched for in the same manner
as configuration files.
.
.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 .
.
.It Fl t Ar path | Cm trust = Ar path
Trust the self-signed certificate loaded from
.Ar path
and disable server name verification.
The
.Ar path
is searched for in the same manner
as configuration files.
.
.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
.
.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 .
.
.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 .
.
.It Pa ~/.local/share/litterbox/litterbox.sqlite
The most likely default path of 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
.Pp
.Lk https://www.sqlite.org/fts5.html#full_text_query_syntax "Full-text Query Syntax"
.
.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
offered 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 irc.tilde.chat .