.\"
.\" Copyright (c) 2013-2022 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
The
.Nm
uses a custom configuration file to setup the IRC daemon.
.\" SYNTAX
.Sh 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.
.Pp
The below sections describe the supported syntax.
.\" Comments
.Ss Comments
Comments start when a # is found and continue until the next line.
.\" Strings
.Ss 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.
.Pp
Example:
.Bd -literal -offset indent
String
"This is a double quoted string"
.Ed
.\" 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,
.Dq -
and
.Dq _ .
.Pp
Example: both
.Ar abc
and
.Ar server-tz2
are valid.
.\" Blocks
.Ss Blocks
For configuration sections that are more complex, blocks using braces are
required and each directive between the enclosing block require a trailing
semicolon.
.Pp
Example:
.Bd -literal -offset indent
block {
	option;
	key and value;
}
.Ed
.\" Lists
.Ss Lists
Lists are separated by a comma.
.Pp
Example:
.Bd -literal -offset indent
one, two, three
.Ed
.\" CONFIGURATION SECTIONS
.Sh CONFIGURATION SECTIONS
The following sections describe what is allowed in the configuration file.
.\" logs
.Ss logs
This section let you configure how irccd should log the messages.
.Bl -tag
.It Ar logs [verbose|quiet] [template string] to console
Use the standard output and error to log content. This the default.
.It Ar logs [verbose|quiet] [template string] to syslog
Use the
.Xr syslog 3
daemon to log information.
.It Ar logs [verbose|quiet] [template string] to file path
Use
.Pa path
to logs every entries.
.El
.Pp
The optional self explained
.Op 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.
.Pp
The option
.Ar template
can be used to format the output log entries using
.Ar string
as template. This template enable shell attributes, environment variable, date
and has the following keywords:
.Bl -tag -width unknown
.It Va message
The message line.
.It Va level
The level of message (debug, info or warning).
.El
.Pp
See
.Xr irccd-templates 7
for more details.
.\" transport
.Ss transport
Enable transport to interract with the
.Nm irccdctl
utility or any networking program that can communicate through a UNIX domain
socket.
.Pp
.Ar transport to path [with uid value gid value]
.Pp
Create the UNIX domain socket on
.Pa path .
.Pp
The optional
.Ar uid
and
.Ar gid
keywords can take an optional
.Ar value
to change socket owner and group respectively, it can be a string or a number.
.\" server
.Ss 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.
.Pp
.Ar server id { options }
.Pp
The following directives are allowed in the
.Em options
block:
.Bl -tag -width "hostname value"
.It Ar hostname value
Connect to the
.Ar value
hostname. This can be either a DNS name or a IP address.
.It Ar port value
Use
.Ar value
number as IP port to connect to.
.It Ar password value
Add the password
.Ar value
if the IRC server requires it.
.It Ar ident nick user realname
Specify the IRC identity to use by using the three arguments
.Ar nick , user
and
.Ar realname
as nickname, user name and your real name respectively.
.Pp
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.
.It Ar ssl
Enable SSL. Only available if built with OpenSSL support.
.It Ar 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
.Ar password@
if required. You must use double quotes if the channel starts with a hash (#)
otherwise it would be detected as a comment.
.It Ar ctcp { key value }
Specify a CTCP version reply to
.Ar value
for the given
.Ar key
which may be one of
.Dq version
or
.Dq source .
The possible
.Ar key
are overriding their uppercase CTCP queries. Each entry in this block
should be terminated by a semicolon.
.It Ar options list
Use specific server features. This is a list of string which can be one of
following:
.Bl -tag -width "AUTO-RECONNECT"
.It Ar AUTO-RECONNECT
Reconnect automatically to a server upon disconnection.
.It Ar AUTO-REJOIN
Automatically rejoin a channel if the bot was kicked from.
.It Ar JOIN-INVITE
Automatically join a channel upon invitation.
.El
.It Ar prefix value
Use
.Ar value
as command prefix for plugins (Optional, default:
.Dq \&! ) .
.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 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.
.Pp
When you don't specify any value into the corresponding criteria the rule is
considered as matched.
.Pp
.Ar rule accept|drop { criteria }
.Pp
Create a rule that either
.Ar accept
or
.Ar drop
the current event.
.Pp
The following directives are allowed in the
.Em criteria
block:
.Bl -tag -width "channels list"
.It Ar servers list
List of servers to match by their ids.
.It Ar channels list
List of channel to match. This can be used to match user nicknames as well.
.It Ar origins list
List of originators to match.
.It Ar events list
List of events to match (in the form onCommand, onMessage, etc). See the
.Xr irccd 1
manual page for the allowed names here.
.It Ar plugins list
List of plugins to match by their ids.
.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.
.\" hooks
.Ss 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.
.Pp
.Ar hook id to path
.Pp
Load the hook with name
.Ar id
from the given
.Pa path .
.\" plugins
.Ss plugins
This section is used to load plugins.
.Pp
To load plugin with default values, you can just use the declaration without
block of options. Otherwise, use a block to add additional options,
.Pp
.Ar plugin id { options }
.Pp
The following directives are allowed in the
.Em options
block:
.Bl -tag -width "hostname value"
.It Ar location path
Specify an absolute
.Pa path
to the plugin.
.It Ar 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
.Xr EXAMPLES
for usage.
.It Ar template { key value }
Same as
.Ar config
but for templates. See
.Xr irccd-templates 7
for more details about this section.
.It Ar paths { key value }
Same as
.Ar 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:
.Bl -tag
.It Ar cache
Directory for temporary files.
.It Ar data
Directory for additional data.
.It Ar config
Directory to additional configuration files.
.El
.El
.\" EXAMPLES
.Sh EXAMPLES
Full example of configuration file
.Bd -literal
# 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"
.Ed
.\" SEE ALSO
.Sh SEE ALSO
.Xr irccd 1
.\" AUTHORS
.Sh AUTHORS
.Nm irccd
was written by David Demelier <markand@malikania.fr>
.\" AUTHORS
.Sh AUTHORS
The
.Nm irccd
daemon was written by
.An David Demelier Aq Mt markand@malikania.fr .