about summary refs log tree commit diff
LITTERBOX(1) FreeBSD General Commands Manual LITTERBOX(1)

litterbox
IRC logger

litterbox [-Qqv] [-N network] [-U url] [-c cert] [-d path] [-h host] [-j join] [-k priv] [-l limit] [-n nick] [-p port] [-u user] [-w pass] [config ...]

litterbox [-d path] -i | -m

litterbox [-d path] -b path

The litterbox daemon logs IRC (over TLS) activity to a database which may be queried with 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.

The litterbox daemon may be connected to the pounce(1) IRC bouncer alongside regular clients to provide central logging and a simple search query interface with -q.

The database must be initialized with -i. If the database format has changed, it will be migrated automatically when litterbox starts, or can be migrated explicitly with -m. Instances of litterbox connected to different IRC networks can share the same database.

Options can be loaded from files listed on the command line. Files are searched for in $XDG_CONFIG_DIRS/litterbox unless the path starts with ‘/’ or ‘.’. Each option is placed on a line, and lines beginning with ‘#’ are ignored. The options are listed below following their corresponding flags.

The arguments are as follows:

name, network = name
Set the network name to be used if the server does not send RPL_ISUPPORT NETWORK. The default is the server hostname.
, public-query
Enable the public search query interface. This allows anyone to perform searches in private messages to litterbox. Search results are limited to channels on the current network.

Searches use the full-text search index. The searchable columns are channel, nick, user, target, message. For search query syntax, see ⟨https://www.sqlite.org/fts5.html#full_text_query_syntax⟩.

url, scooper-url = url
Set the base URL of a scooper(1) instance used to construct links to full search results in response to the search query interface enabled by -Q or -q.
path
Perform a live database backup to path and exit. This operation requires SQLite version 3.27.0 or newer.
path, cert = path
Load the TLS client certificate from path and authenticate with SASL EXTERNAL, also known as CertFP. The path is searched for in the same manner as configuration files. If the private key is in a separate file, it is loaded with -k.
path, database = path
Set the path to the database file. The default paths are documented in FILES.
host, host = host
Connect to host.
Initialize the database and exit.
chan, join = chan
Join the comma-separated list of channels chan.
path, priv = path
Load the TLS client private key from path. The path is searched for in the same manner as configuration files.
limit, limit = limit
Limit the number of results in the search query interface enabled by -Q or -q. The default limit is 10.
Migrate the database to the latest format and exit.
nick, nick = nick
Set the nickname to nick. The default nickname is “litterbox”.
port, port = port
Connect to port. The default port is 6697.
, private-query
Enable the private search query interface. When connected to pounce(1), this allows the user to private message their own nickname with search queries. Search results are limited to the current network.

Searches use the full-text search index. The searchable columns are channel, query, nick, user, target, message. For search query syntax, see ⟨https://www.sqlite.org/fts5.html#full_text_query_syntax⟩.

user, user = user
Set the username to user. The default username is the same as the nickname.
, verbose
Write sent and received IRC messages as well as SQL INSERT statements to standard error.
pass, pass = pass
Log in with the server password pass.

$XDG_CONFIG_DIRS/litterbox
Configuration files are searched for first in $XDG_CONFIG_HOME, usually ~/.config, followed by the colon-separated list of paths $XDG_CONFIG_DIRS, usually /etc/xdg.
$XDG_DATA_DIRS/litterbox/litterbox.sqlite
The database file is searched for first in $XDG_DATA_HOME, usually ~/.local/share, followed by the colon-separated list of paths $XDG_DATA_DIRS, usually /usr/local/share:/usr/share.
~/.local/share/litterbox/litterbox.sqlite
The most likely default path to the database file.

Configuration on the command line:
litterbox -Q -h irc.example.org -j '#example'

Configuration in a file:

host = irc.example.org
join = #example
public-query

scoop(1), unscoop(1)

The litterbox daemon implements the causal.agency/consumer and causal.agency/passive vendor-specific IRCv3 capabilities implemented by pounce(1).

June Bug <june@causal.agency>

Send mail to <list+litterbox@causal.agency> or join #ascii.town on chat.freenode.net.
August 22, 2020 FreeBSD 12.2-RELEASE-p1