.\"
.\" Copyright (c) 2013-2019 David Demelier <markand@malikania.fr>
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd @IRCCD_MAN_DATE@
.Dt IRCCD.CONF 5
.Os
.\" NAME
.Sh NAME
.Nm irccd.conf
.Nd irccd configuration file
.\" DESCRIPTION
.Sh DESCRIPTION
Both
.Nm irccd
and
.Nm irccdctl
use configuration file in a extended INI format. This section will briefly
explain the additional extensions to the INI format.
.Pp
The file syntax has following rules:
.Bl -enum
.It
Each option is stored in a section,
.It
Some sections may be redefined multiple times,
.It
Empty option must have quotes (e.g. option = "").
.El
.Ss The @include and @tryinclude statements
Irccd adds an extension to this format by adding an
.\" @include and @tryinclude
.Ar @include keyword
which let you splitting your configuration file.
.Pp
Note: this @include statement must be at the beginning of the file and must be
surrounded by quotes if the file name has spaces.
.Pp
You can use both relative or absolute paths. If relative paths are used, they
are relative to the current file being parsed.
.Pp
The alternative
.Ar @tryinclude
keyword is similar but does not fails if the requested file is not found.
.Pp
Example of includes:
.Bd -literal -offset Ds
@include "rules.conf"
@include "servers.conf"

[mysection]
myoption = "1"
.Ed
.\" lists
.Ss The list construct
When requested, an option can have multiples values in a list. The syntax uses
parentheses and values are separated by commas.
.Pp
If the list have only one value, you can just use a simple string.
.Pp
Example of lists:
.Bd -literal -offset Ds
[rule]
servers = ( "server1", "server2" )

[rule]
servers = "only-one-server"
.Ed
.Pp
Note: spaces are completely optional.
.\" identifiers
.Ss Identifiers
Some sections require an identifier (specified as id) as parameter. They must be
unique, not empty and can only contain characters, numbers, '-' and '_'.
.Pp
Example: both
.Ar abc
and
.Ar server-tz2
are valid.
.\" CONFIGURATION SECTIONS
.Sh CONFIGURATION SECTIONS
Configuration are always stored in dedicated section in the form
.Ar [name]
where name is one of the section defined below and are case-sensitive.
.\" [logs]
.Ss logs
This section can let you configure how irccd should log the messages.
.Pp
Available options:
.Bl -tag -width 20n
.It Va verbose No (bool)
Be verbose (Optional, default: false).
.It Va type No (string)
Which kind of logging, valid values are
.Dq console ,
.Dq file
or
.Dq syslog
(Optional, default: console).
.Pp
Note: syslog is not available on all platforms.
.El
.Pp
The following options are available for the
.Ar file
type:
.Bl -tag -width 20n
.It Va path-logs No (string)
Path to the normal messages.
.It Va path-errors No (string)
Path to the error messages.
.El
.\" [templates]
.Ss templates
The templates section let you change the irccd's output. It uses the templates
system (see
.Xr irccd-templates 7
for more information about templates)
.Pp
Only one keyword is defined, message which contains the message that irccd
wants to output.
.Pp
Note: colors and attributes are not supported on Windows.
.Pp
Available options:
.Bl -tag -width 18n
.It Va debug No (string)
Template to use to format debug messages (Optional, default: none).
.It Va info No (string)
Template to use to format information messages (Optional, default: none).
.It Va warning No (string)
Template to use to format warnings (Optional, default: none).
.El
.\" [server]
.Ss server
This section is used to connect to one or more server. Create a new server
section for each IRC server you want to connect to.
.Pp
Available options:
.Bl -tag -width 26n
.It Va name No (identifier)
The unique id.
.It Va hostname No (string)
The server address or IP.
.It Va port No (int)
The server port (Optional, default: 6667).
.It Va password No (string)
An optional server password (Optional, default: none).
.It Va join-invite No (bool)
Automatically join channels upon invitation (Optional, default: false).
.It Va channels No (list)
List of channels to auto join (Optional, default: empty).
.Pp
Note: if a channel requires a password, add it after a colon (e.g.
.Dq #channel:password ) .
.It Va command-char No (string)
The prefix for invoking special commands (Optional, default: !).
.It Va ssl No (bool)
Enable or disable SSL (Optional, default: false).
.It Va auto-reconnect No (bool)
Enable reconnection after failure (Optional, default: true).
.It Va auto-reconnect-delay No (int)
Number of seconds to wait before retrying (Optional, default: 30).
.It Va ping-timeout No (int)
Number of seconds before ping timeout (Optional, default: 300).
.It Va nickname No (string)
The nickname (Optional, default: irccd).
.It Va realname No (string)
The realname (Optional, default: IRC Client Daemon).
.It Va username No (string)
The username name (Optional, default: irccd).
.It Va ctcp-version No (string)
What version to respond to CTCP VERSION (Optional, default: IRC Client Daemon).
.El
.\" [paths]
.Ss paths
The paths section defines common paths used as defaults for all plugins.
.Pp
Any option in this section can be defined altough the following are used as
common convention used in all plugins:
.Pp
Available options:
.Bl -tag -width 16n
.It Va cache No (string)
Path for data files written by the plugin.
.It Va data No (string)
Path for data files provided by the user.
.It Va config No (string)
Path for additional configuration from the user.
.El
.Pp
For each of these paths,
.Dq plugin/name
is appended with the appropriate plugin name when used.
.Pp
The section is redefinable per plugin basis using the
.Va [paths.<plugin>]
syntax.
.Ss plugins
This section is used to load plugins.
.Pp
Just add any key you like to load a plugin. If the value is not specified, the
plugin is searched through the standard directories, otherwise, provide the full
path (including the .js extension).
.Pp
Warning: remember to add an empty string for searching plugins.
.\" [transport]
.Ss transport
This section defines transports that are used to communicate through clients
connected to irccd and to perform requests to irccd.
.Pp
With transports, you may ask irccd to send a message, a notice or even to kick
someone from a channel. Irccd will also notify all clients connected to this
transport on IRC events.
.Pp
There are two types of transport availables:
.Bl -bullet
.It
Internet sockets, IPv4 and IPv6,
.It
Unix sockets, based on files (not available on Windows).
.El
.Pp
If SSL support was built in, both internet and unix sockets can be set to use
encrypted connections.
.Pp
Available options:
.Bl -tag -width 18n
.It Va type No (string)
Type of transport
.Dq ip
or
.Dq unix .
.It Va password No (string)
An authentication password (Optional, default: none).
.It Va ssl No (bool)
Enable SSL (Optional, default: false),
.It Va key No (string)
Path to private key file (Required if ssl is true)
.It Va certificate No (string)
Path to certificate (Required if ssl is true)
.El
.Pp
The following options are available for the
.Ar ip
type:
.Bl -tag -width 18n
.It Va port No (int)
Port number.
.It Va address No (string)
Address to bind or
.Dq *
for any (Optional, default:
.Dq * ) .
.It Va ipv4 No (bool)
Bind on IPv4 (Optional, default true).
.It Va ipv6 No (bool)
Bind on IPv6 (Optional, default true).
.El
.Pp
The following options are available for the
.Ar unix
type:
.Bl -tag -width 18n
.It Va path No (string)
The file path to the socket.
.El
.\" [rule]
.Ss 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 criterias. 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.
.Pp
Available options:
.Bl -tag -width 15n
.It Va servers No (list)
A list of servers that will match the rule (Optional, default: empty).
.It Va channels No (list)
A list of channel (Optional, default: empty).
.It Va origins No (list)
A list of nicknames to check (Optional, default: empty).
.It Va plugins No (list)
Which plugins (Optional, default: empty),
.It Va events No (list)
Which events like onCommand, onMessage (Optional, default: empty).
.It Va action No (string)
Set to
.Dq accept
or
.Dq drop .
.El
.Pp
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.
.\" EXAMPLES
.Sh EXAMPLES
Full example of configuration file
.Bd -literal
# Add a transport that bind only to IPv6.
[transport]
type = ip
ipv4 = false
ipv6 = true
port = 12000

# A transport that binds to both IPv4 and IPv6.
[transport]
type = ip
port = 15000

# A server.
[server]
name = "foo"
host = "irc.foo.org"
port = "6667"
nickname = "superbot"
realname = "SuperBot v1.0"
username = "sp"

# An other server.
[server]
name = "wanadoo"
host = "chat.wanadoo.fr"
port = "6667"

# Load some plugins.
[plugins]
ask = ""                               # Search ask
myplugin = /path/to/myplugin.js        # Use absolute path

# This first rule disable the plugin reboot on all servers and channels.
[rule]
plugins = "reboot"
action = drop

# This rule enable the reboot plugin again on the server localhost,
# channel #staff.
[rule]
servers = "localhost"
channels = "#staff"
plugins = "reboot"
action = accept
.Ed
.\" SEE ALSO
.Sh SEE ALSO
.Xr irccd 1
.\" AUTHORS
.Sh AUTHORS
.Nm irccd
was written by David Demelier <markand@malikania.fr>