path: root/quarg.1

.Dd May 8, 2021
.Dt QUARG 1
.Os
.Sh NAME
.Nm quarg
.Nd search Quassel logs for matching messages and print them
.Sh SYNOPSIS
.Nm
.Op Fl de
.Op Fl l Ar num
.Op Fl o Ar order
.Op Fl b Ar buffer
.Op Fl B Ar buftype
.Op Fl f Ar msgflag
.Op Fl m Ar prefix
.Op Fl n Ar nick
.Op Fl N Ar network
.Op Fl Q Ar user
.Op Fl t Ar msgtype
.Op Fl -after Ar date
.Op Fl -around Ar date Ns Op / Ns Ar range
.Op Fl -before Ar date
.Op Fl -joined | -no-joined
.Op Ar keyword Op Ar keyword ...
.Nm
.Fl h | -help
.Sh DESCRIPTION
.Nm
searches Quassel logs for messages matching a set of conditions and
prints the results.
See
.Sx CONNECTING TO QUASSEL
for more information on how to set up the database connection.
.Pp
A condition is any option from the
.Sx CONDITIONS
section.
At least one condition needs to be specified.
If multiple different types of conditions are given, all of them must
match.
The same condition can be specified multiple times with different
arguments, in which case it matches any of the arguments.
.Pp
If there are any results,
.Nm
prints each match using Quassel's message format, prefixed with the
timestamp in local time and the origin buffer of the message separated
by the tab
character.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl d
Prints additional debug information.
This includes the
.Em SELECT
statements executed by SQL as well as an internal representation of the
conditions passed to
.Nm .
.It Fl e
Interprets any
.Ar keyword
as a
.Em LIKE
expression.
This allows the use of the
.Sq %
placeholder.
If no placeholders are given, matches the
.Ar keyword
exactly.
.Pp
To match
.Sq %
literally, escape it with a backslash character.
.It Fl l Ar num
Limits the number of matches to
.Ar num .
.It Fl o Ar order
Specifies in which order to sort the messages.
Matches are always sorted by timestamp.
.Ar order
can be
.Sy asc
for ascending order or
.Sy desc
for descending order.
The default is
.Sy asc .
.Pp
This option is useful in conjunction with
.Fl l Ar num ,
as it may be used to have
.Nm
limit output to the oldest
.Pq Sy asc
or most recent
.Pq Sy desc
.Ar num
matches.
.It Fl h | -help
Shows the integrated help page and exits.
.El
.Sh CONDITIONS
The conditions are as follows:
.Bl -tag -width Ds
.It Ar keyword
Matches messages containing
.Ar keyword .
.It Fl b Ar buffer
Matches messages in a specific buffer, given by its name as displayed in
the Quassel client.
.It Fl B Ar buftype
Matches messages in buffers of a specific type.
.Pp
.Ar buftype
can be one of
.Sy channel ,
.Sy query ,
or
.Sy status ,
for channels, queries, and the status (or
.Dq network )
buffers respectively.
.It Fl f Ar msgflag
Matches messages of a specific context, given by a flag name.
.Pp
The flag names are as follows:
.Bl -tag -width Ds
.It Sy highlight
Messages that triggered Quassel's
.Dq Remote Highlight
rules.
By default this includes messages containing the current nickname.
.It Sy none
Messages that do not have any flag set.
.It Sy self
Messages that were sent by Quassel users themselves.
.El
.It Fl m Ar prefix
Matches messages sent by nicknames that have a specific channel
membership prefix as defined in the
.Sy Channel Membership Prefix section Ns No [1]
of the Modern IRC Client Protocol specification.
.Pp
Common prefixes include
.Sq @
for operators,
.Sq %
for half-ops, and
.Sq +
for voiced users.
.Pp
Note that multiple prefixes may be set at the same time (for example a
voiced operator).
In this case, any prefix will match, but the printed message will only
show the
.Dq highest
one.
.It Fl n Ar nick
Matches messages sent by a specific user, given by nickname.
.It Fl N Ar network
Matches messages in a specific network, given by its name as displayed
in the Quassel client.
.It Fl Q Ar user
Matches messages relating to a specific Quassel user, given by their
user name.
.Pp
This condition is only useful if the Quassel database contains logs
for multiple Quassel users.
Without this condition,
.Nm
matches messages from any Quassel user.
.It Fl t Ar msgtype
Matches messages of a specific type.
.Pp
.Ar msgtype
can be one of the following, corresponding to IRC messages as defined
in
.Sy RFC 1459 Ns No [2] :
.Sy invite ,
.Sy join ,
.Sy kick ,
.Sy kill ,
.Sy mode ,
.Sy nick ,
.Sy notice ,
.Sy part ,
.Sy privmsg ,
.Sy quit ,
.Sy topic .
.Pp
In addition,
.Nm
supports the following message types:
.Bl -tag -width Ds
.It Sy action
The CTCP ACTION message.
.It Sy error
Error messages as reported to the user by Quassel.
.It Sy netsplit_join
Messages indicating the end of a netsplit, along with the users who
rejoined.
.It Sy netsplit_quit
Messages indicating an ongoing netsplit, along with the users who quit.
.It Sy server
Server messages as reported to the user by Quassel.
.El
.It Fl -joined
Matches messages in channels that are currently joined.
.It Fl -no-joined
Matches messages in channels that are currently not joined.
.Pp
Note that as a result of the implementation in Quassel, this condition
matches all query buffers.
If this is undesirable, combine this condition with
.Fl B No channel .
.El
.Pp
In addition,
.Nm
supports matching on message timestamps.
Wherever a date is passed as an argument to a condition,
.Nm
parses it according to the
.Sy ISO-8601
standard.
.Pp
A date may include a time element and a time zone offset.
If no time zone offset is given, the date is assumed to be in local
time.
Refer to
.Sy dateutil's isoparse documentation Ns No [3]
for detailed information.
.Pp
The conditions that match on message timestamps are as follows:
.Bl -tag -width Ds
.It Fl -after Ar date
Matches messages that were sent after
.Ar date .
.It Fl -around Ar date Ns Op / Ns Ar range
Matches messages sent after
.Ar date -
.Ar range
and before
.Ar date +
.Ar range .
If
.Ar range
is not given, defaults to 12 hours.
.Pp
.Ar range
consists of a number and an optional suffix
.Sq h
for hours or
.Sq m
for minutes.
If no suffix is given, defaults to hours.
.Pp
For example,
.Dq 2021-02-18 20:55Z/10m
matches messages sent between 20:45 and 21:05.
This is equivalent to the following:
.Bd -literal -offset indent
quarg --after '2021-02-18 20:45Z' --before '2021-02-18 21:05Z'
.Ed
.Pp
This option cannot be used with
.Fl -after
or
.Fl -before .
.It Fl -before Ar date
Matches messages that were sent before
.Ar date .
.El
.Sh CONNECTING TO QUASSEL
In order to access Quassel's logs,
.Nm
needs access to the Quassel database.
The easiest way to achieve this is to have it running on the database
host and remotely invoke it using
.Xr ssh 1 .
Alternatively, the database port (or socket) may be forwarded to a local
machine
via
.Xr ssh 1
and used with a local
.Nm
instance.
.Pp
.Nm
uses SQLAlchemy which supports both SQLite and PostgreSQL backends.
The psycopg2 backend is recommended for the latter.
.Pp
If Quassel uses the PostgreSQL backend,
it is highly recommended to set up a read-only database role
specifically for
.Nm .
Furthermore, consider using the
.Sy Peer Authentication Ns No [4]
method with a dedicated user.
This type of authentication removes the need for a password and
also works over a forwarded connection.
.Pp
.Nm
reads the database URL from an INI-style configuration file.
See
.Sx FILES
for the location of this file.
The URL is specified in the
.Em Database
section using the
.Em url
key.
See
.Sy Database URLs Ns No [5]
for details on the URL format.
.Pp
The following is a valid configuration file specifying a connection to a
local PostgreSQL instance via its default socket:
.Bd -literal -offset indent
[Database]
url = postgresql+psycopg2://quarg@/quassel?host=/run/postgresql
.Ed
.Sh FILES
.Bl -tag -width Ds
.It Em $XDG_CONFIG_HOME/quarg/config
The configuration file for
.Nm .
.El
.Pp
.Nm
adheres to the XDG Base Directory Specification.
If $XDG_CONFIG_HOME is unset or empty, it will default to
.Em ~/.config
.Sh NOTES
.Bl -enum
.It
.Sy Channel Membership Prefixes
.Pp
https://modern.ircdocs.horse/#channel-membership-prefixes
.It
.Sy RFC 1459
.Pp
https://tools.ietf.org/html/rfc1459
.It
.Sy dateutil isoparse
.Pp
https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.isoparse
.It
.Sy Peer Authentication
.Pp
https://www.postgresql.org/docs/13/auth-peer.html
.It
.Sy Database URLs
.Pp
https://docs.sqlalchemy.org/en/14/core/engines.html#database-urls
.El
.Sh AUTHORS
.An -nosplit
.Nm
was written by
.An Wolfgang Müller Aq Mt wolf@oriole.systems