aboutsummaryrefslogtreecommitdiffstatshomepage
QUARG(1) General Commands Manual QUARG(1)

quarg
search Quassel logs for matching messages and print them

quarg [-de] [-l num] [-o order] [-b buffer] [-B buftype] [-f msgflag] [-m prefix] [-n nick] [-N network] [-Q user] [-t msgtype] [--after date] [--around date[/range]] [--before date] [--joined | --no-joined] [keyword [keyword ...]]

quarg -h | --help

quarg searches Quassel logs for messages matching a set of conditions and prints the results. See CONNECTING TO QUASSEL for more information on how to set up the database connection.

A condition is any option from the 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.

If there are any results, quarg 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.

The options are as follows:

Prints additional debug information. This includes the SELECT statements executed by SQL as well as an internal representation of the conditions passed to quarg.
Interprets any keyword as a LIKE expression. This allows the use of the ‘%’ placeholder. If no placeholders are given, matches the keyword exactly.

To match ‘%’ literally, escape it with a backslash character.

num
Limits the number of matches to num.
order
Specifies in which order to sort the messages. Matches are always sorted by timestamp. order can be asc for ascending order or desc for descending order. The default is asc.

This option is useful in conjunction with -l num, as it may be used to have quarg limit output to the oldest (asc) or most recent (desc) num matches.

|
Shows the integrated help page and exits.

The conditions are as follows:
keyword
Matches messages containing keyword.
buffer
Matches messages in a specific buffer, given by its name as displayed in the Quassel client.
buftype
Matches messages in buffers of a specific type.

buftype can be one of channel, query, or status, for channels, queries, and the status (or “network”) buffers respectively.

msgflag
Matches messages of a specific context, given by a flag name.

The flag names are as follows:

highlight
Messages that triggered Quassel's “Remote Highlight” rules. By default this includes messages containing the current nickname.
none
Messages that do not have any flag set.
self
Messages that were sent by Quassel users themselves.
prefix
Matches messages sent by nicknames that have a specific channel membership prefix as defined in the Channel Membership Prefix section[1] of the Modern IRC Client Protocol specification.

Common prefixes include ‘@’ for operators, ‘%’ for half-ops, and ‘+’ for voiced users.

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 “highest” one.

nick
Matches messages sent by a specific user, given by nickname.
network
Matches messages in a specific network, given by its name as displayed in the Quassel client.
user
Matches messages relating to a specific Quassel user, given by their user name.

This condition is only useful if the Quassel database contains logs for multiple Quassel users. Without this condition, quarg matches messages from any Quassel user.

msgtype
Matches messages of a specific type.

msgtype can be one of the following, corresponding to IRC messages as defined in RFC 1459[2]: invite, join, kick, kill, mode, nick, notice, part, privmsg, quit, topic.

In addition, quarg supports the following message types:

action
The CTCP ACTION message.
error
Error messages as reported to the user by Quassel.
netsplit_join
Messages indicating the end of a netsplit, along with the users who rejoined.
netsplit_quit
Messages indicating an ongoing netsplit, along with the users who quit.
server
Server messages as reported to the user by Quassel.
Matches messages in channels that are currently joined.
Matches messages in channels that are currently not joined.

Note that as a result of the implementation in Quassel, this condition matches all query buffers. If this is undesirable, combine this condition with -B channel.

In addition, quarg supports matching on message timestamps. Wherever a date is passed as an argument to a condition, quarg parses it according to the ISO-8601 standard.

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 dateutil's isoparse documentation[3] for detailed information.

The conditions that match on message timestamps are as follows:

date
Matches messages that were sent after date.
date[/range]
Matches messages sent after date - range and before date + range. If range is not given, defaults to 12 hours.

range consists of a number and an optional suffix ‘h’ for hours or ‘m’ for minutes. If no suffix is given, defaults to hours.

For example, “2021-02-18 20:55Z/10m” matches messages sent between 20:45 and 21:05. This is equivalent to the following:

quarg --after '2021-02-18 20:45Z' --before '2021-02-18 21:05Z'
    

This option cannot be used with --after or --before.

date
Matches messages that were sent before date.

In order to access Quassel's logs, quarg 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 ssh(1). Alternatively, the database port (or socket) may be forwarded to a local machine via ssh(1) and used with a local quarg instance.

quarg uses SQLAlchemy which supports both SQLite and PostgreSQL backends. The psycopg2 backend is recommended for the latter.

If Quassel uses the PostgreSQL backend, it is highly recommended to set up a read-only database role specifically for quarg. Furthermore, consider using the Peer Authentication[4] method with a dedicated user. This type of authentication removes the need for a password and also works over a forwarded connection.

quarg reads the database URL from an INI-style configuration file. See FILES for the location of this file. The URL is specified in the Database section using the url key. See Database URLs[5] for details on the URL format.

The following is a valid configuration file specifying a connection to a local PostgreSQL instance via its default socket:

[Database]
url = postgresql+psycopg2://quarg@/quassel?host=/run/postgresql

$XDG_CONFIG_HOME/quarg/config
The configuration file for quarg.

quarg adheres to the XDG Base Directory Specification. If $XDG_CONFIG_HOME is unset or empty, it will default to ~/.config

  1. Channel Membership Prefixes

    https://modern.ircdocs.horse/#channel-membership-prefixes

  2. RFC 1459

    https://tools.ietf.org/html/rfc1459

  3. dateutil isoparse

    https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.isoparse

  4. Peer Authentication

    https://www.postgresql.org/docs/13/auth-peer.html

  5. Database URLs

    https://docs.sqlalchemy.org/en/14/core/engines.html#database-urls

quarg was written by Wolfgang Müller
May 8, 2021