LITTERBOX(1) | General Commands Manual | LITTERBOX(1) |
NAME
litterbox
— IRC
logger
SYNOPSIS
litterbox |
[-Qqv ] [-N
network] [-U
url] [-c
cert] [-d
path] [-h
host] [-j
join] [-k
priv] [-l
limit] [-n
nick] [-p
port] [-t
trust] [-u
user] [-w
pass] [config ...] |
litterbox |
-i | -m
[-d path] |
litterbox |
-b path
[-d path] |
DESCRIPTION
Thelitterbox
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
. Live backups of the database can be made with
-b
. Instances of litterbox
connected to different IRC networks will 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:
-N
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.
-Q
|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
. -U
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
. -b
path- Perform a live database backup to path and exit. This operation requires SQLite version 3.27.0 or newer.
-c
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
. -d
path |database =
path- Set the path to the database file. See FILES for the default paths.
-h
host |host =
host- Connect to host.
-i
- Initialize the database and exit.
-j
chan |join =
chan- Join the comma-separated list of channels chan.
-k
path |priv =
path- Load the TLS client private key from path. The path is searched for in the same manner as configuration files.
-l
limit |limit =
limit- Limit the number of results in the search query interface enabled by
-Q
or-q
. The default limit is 10. -m
- Migrate the database to the latest format and exit.
-n
nick |nick =
nick- Set the nickname to nick. The default nickname is “litterbox”.
-p
port |port =
port- Connect to port. The default port is 6697.
-q
|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
. -t
path |trust =
path- Trust the self-signed certificate loaded from path and disable server name verification. The path is searched for in the same manner as configuration files.
-u
user |user =
user- Set the username to user. The default username is the same as the nickname.
-v
|verbose
- Write sent and received IRC messages as well as SQL INSERT statements to standard error.
-w
pass |pass =
pass- Log in with the server password pass.
FILES
- $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
. - $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
. - ~/.local/share/litterbox/litterbox.sqlite
- The most likely default path of the database file.
EXAMPLES
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
SEE ALSO
STANDARDS
- C. Kalt, Internet Relay Chat: Client Protocol, IETF, RFC 2812, https://tools.ietf.org/html/rfc2812, April 2000.
- Kyle Fuller, Stéphan Kochen, Alexey Sokolov, and James Wheare, IRCv3.2 server-time Extension, IRCv3 Working Group, https://ircv3.net/specs/extensions/server-time-3.2.
- Waldo Bastian, Ryan Lortie, and Lennart Poettering, XDG Base Directory Specification, https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html, November 24, 2010.
- William Pitcock and Jilles Tjoelker, IRCv3.1 SASL Authentication, IRCv3 Working Group, https://ircv3.net/specs/extensions/sasl-3.1.html.
Extensions
The litterbox
daemon implements the
causal.agency/consumer
and
causal.agency/passive
vendor-specific IRCv3 capabilities offered by
pounce(1).
AUTHORS
June McEnroe <june@causal.agency>
BUGS
Send mail to
<list+litterbox@causal.agency>
or join #ascii.town
on
irc.tilde.chat
.
April 3, 2021 | OpenBSD 7.4 |