IRCCD.CONF(5) - File Formats Manual

NAME

irccd.conf - irccd configuration file

DESCRIPTION

The irccd.conf uses a custom configuration file to setup the IRC daemon.

SYNTAX

The file consists of several directives that are evaluated in order of appearance. It is advised to follow the same directive order as described in this document.

The below sections describe the supported syntax.

Comments

Comments start when a # is found and continue until the next line.

Strings

String are either written in pure ASCII strings or enclosed between double quotes. Because some reserved tokens may collide with your values, it is recommended to use double quoted strings in user values (such as identifiers, channels names and such). Also, double quotes are required when string contain spaces.

Example:

String
"This is a double quoted string"

Identifiers

Some sections require an identifier (specified as id) as parameter. They must be unique, not empty and can only contain characters, numbers, “-” and “_”.

Example: both abc and server-tz2 are valid.

Blocks

For configuration sections that are more complex, blocks using braces are required and each directive between the enclosing block require a trailing semicolon.

Example:

block {
    option;
    key and value;
}

Lists

Lists are separated by a comma.

Example:

one, two, three

CONFIGURATION SECTIONS

The following sections describe what is allowed in the configuration file.

logs

This section let you configure how irccd should log the messages.

logs [verbose|quiet] [template string] to console

Use the standard output and error to log content. This the default.

logs [verbose|quiet] [template string] to syslog

Use the syslog(3) daemon to log information.

logs [verbose|quiet] [template string] to file path

Use path to logs every entries.

The optional self explained [verbose|quiet] argument controls either if verbose logging should be enabled or not. Only informative messages are affected by this setting. Warnings and debugging messages are stored independently from this setting.

The option template can be used to format the output log entries using string as template. This template enable shell attributes, environment variable, date and has the following keywords:

message

The message line.

level

The level of message (debug, info or warning).

See irccd-templates(7) for more details.

transport

Enable transport to interract with the irccdctl utility or any networking program that can communicate through a UNIX domain socket.

transport to path [with uid value gid value]

Create the UNIX domain socket on path.

The optional uid and gid keywords can take an optional value to change socket owner and group respectively, it can be a string or a number.

server

This section is used to connect to one or more server. Create a new server section block for each IRC server you want to connect to.

server id { options }

The following directives are allowed in the options block:

hostname value

Connect to the value hostname. This can be either a DNS name or a IP address.

port value

Use value number as IP port to connect to.

password value

Add the password value if the IRC server requires it.

ident nick user realname

Specify the IRC identity to use by using the three arguments nick, user and realname as nickname, user name and your real name respectively.

Note: this is not a list of strings but three arguments separated by a space. If you want to use a real name with spaces, don’t forget the double quotes.

ssl

Enable SSL. Only available if built with OpenSSL support.

channels list

List of channels to join automatically when the server is connected successfully. This is a list of strings where each element is the channel name to join prepended by a optional password@ if required. You must use double quotes if the channel starts with a hash (#) otherwise it would be detected as a comment.

ctcp { key value }

Specify a CTCP version reply to value for the given key which may be one of “version” or “source”. The possible key are overriding their uppercase CTCP queries. Each entry in this block should be terminated by a semicolon.

options list

Use specific server features. This is a list of string which can be one of following:

AUTO-RECONNECT

Reconnect automatically to a server upon disconnection.

AUTO-REJOIN

Automatically rejoin a channel if the bot was kicked from.

JOIN-INVITE

Automatically join a channel upon invitation.

prefix value

Use value as command prefix for plugins (Optional, default: “!”).

rule

The rule section is one of the most powerful within irccd configuration. It lets you enable or disable plugins and IRC events for specific criteria. For instance, you may want to disable a plugin only for a specific channel on a specific server. And because rules are evaluated in the order they are defined, you can override rules.

When you don’t specify any value into the corresponding criteria the rule is considered as matched.

rule accept|drop { criteria }

Create a rule that either accept or drop the current event.

The following directives are allowed in the criteria block:

servers list

List of servers to match by their ids.

channels list

List of channel to match. This can be used to match user nicknames as well.

origins list

List of originators to match.

events list

List of events to match (in the form onCommand, onMessage, etc). See the irccd(1) manual page for the allowed names here.

plugins list

List of plugins to match by their ids.

Warning: don’t make sensitive rules on origins option, irccd does not have any kind of nickname authentication. Thus, it may be very easy for someone to use a temporary nickname.

hooks

This section loads hooks. The configuration does not test if the file is actually executable nor present on the filesystem and will be tried as long as the daemon is running.

hook id to path

Load the hook with name id from the given path.

plugins

This section is used to load plugins.

To load plugin with default values, you can just use the declaration without block of options. Otherwise, use a block to add additional options,

plugin id { options }

The following directives are allowed in the options block:

location path

Specify an absolute path to the plugin.

config { key value }

Specify a list of options to the plugin as key-value pair. Each entry consist of two arguments, the option name and its value both as strings. See EXAMPLES for usage.

template { key value }

Same as config but for templates. See irccd-templates(7) for more details about this section.

paths { key value }

Same as config but for additional paths. Individual plugins may accept special paths but the following are reserved by irccd and always set when loading the plugin unless explicitly overriden in this section:

cache

Directory for temporary files.

data

Directory for additional data.

config

Directory to additional configuration files.

EXAMPLES

Full example of configuration file

# Logs to syslog instead of console (which is the default).
logs verbose to syslog

# Logs using a specific format string (console is recommended for colors).
logs verbose template "%H:%M @{orange}#{level}@{} #{message}"

# Enable transport with default permissions.
transport to "/tmp/irccd.sock"

#
# Create a server "example" that connect to example.org using "fr" as nickname,
# "francis" as username and "Francis Meyer" as realname.
#
# This channel will automatically join "#test" on connection and the password
# protected "#nightclub" channel with password "secret"
#
# We also override the CTCP VERSION and SOURCE reply.
#
server example {
    hostname example.org;
    port 6667;
    ident fr francis "Francis Meyer";
    channels "#test", "secret@#nightclub";
    ctcp {
        version "custom CTCP VERSION reply";
        source "custom SCM repository";
    }
}

# Load several plugins with their default values and locations.
plugin ask
plugin plugin

# Configure the plugin hangman to change templates and the path to the words.
plugin hangman {
    templates {
        win "Success, the word was #{word}!";
    }
    config {
        file "/var/irccd/hard-words.txt";
    }
}

# This first rule disable the plugin reboot on all servers and channels.
rule drop {
    plugins "reboot";
}

# This rule enable the reboot plugin again on the server localhost,
# channel #staff.
rule accept {
    servers "localhost";
    channels "#staff";
    plugins "reboot";
}

# This create an hook named "mail" with the given path.
hook mail to "/path/to/mail.py"

SEE ALSO

irccd(1)

AUTHORS

irccd was written by David Demelier <markand@malikania.fr>

AUTHORS

The irccd daemon was written by David Demelier <markand@malikania.fr>.

macOS 13.5 - February 3, 2022