Mercurial > irccd
diff man/irccd.conf.5 @ 996:2a6d753f79f6
man: add back
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 11 Feb 2021 22:13:01 +0100 |
parents | d585adeee610 |
children | c50f954d8c67 |
line wrap: on
line diff
--- a/man/irccd.conf.5 Thu Feb 11 17:39:22 2021 +0100 +++ b/man/irccd.conf.5 Thu Feb 11 22:13:01 2021 +0100 @@ -22,349 +22,300 @@ .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. +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 alternative -.Ar @tryinclude -keyword is similar but does not fails if the requested file is not found. +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 of includes: -.Bd -literal -offset Ds -@include "rules.conf" -@include "servers.conf" - -[mysection] -myoption = "1" +Example: +.Bd -literal -offset indent +String +"This is a double quoted string" .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 +.\" 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 '_'. +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, block 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 -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] +The following sections describe what is allowed in the configuration file. +.\" 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. +.Bl -tag +.It Ar logs [verbose|quiet] to console +Use the standard output and error to log content. This the default. +.It Ar logs [verbose|quiet] to syslog +Use the +.Xr syslog 3 +daemon to log information. +.It Ar logs [verbose|quiet] to file path +Use +.Pa path +to logs every entries. .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) +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. +.\" 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 -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. +.Ar transport to path .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] +Enable transport on +.Pa path . +.\" 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. +section block 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). +.Ar server id { options } .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: 1800). -.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. -.\" [plugins] -.Ss plugins -This section is used to load plugins. +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 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 -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. -.\" [hooks] -.Ss hooks -This sections stores every hooks in key-value pairs. The option key denotes the -hook id and the value must be a path to the actual hook file. -.\" [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). +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 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 -.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) +.It Ar prefix value +Use +.Ar value +as command prefix for plugins (Optional, default: +.Dq \&! ) . .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] +.\" 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 +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 -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 +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 -.Dq drop . +.Ar drop +the current event. +.Pp +The following directives are allowed in the +.Em options +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 -# 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 +# Logs to syslog instead of console (which is the default). +logs verbose to syslog -# A server. -[server] -name = "foo" -host = "irc.foo.org" -port = "6667" -nickname = "superbot" -realname = "SuperBot v1.0" -username = "sp" +# +# 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" +# +server example { + hostname example.org; + port 6667; + ident fr francis "Francis Meyer"; + channels "#test", "secret@#nightclub"; +} -# An other server. -[server] -name = "wanadoo" -host = "chat.wanadoo.fr" -port = "6667" +# Load several plugins with their default values and locations. +plugin ask +plugin plugin -# Load some plugins. -[plugins] -ask = "" # Search ask -myplugin = /path/to/myplugin.js # Use absolute path +# 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] -plugins = "reboot" -action = drop +rule drop { + plugins "reboot"; +} # This rule enable the reboot plugin again on the server localhost, # channel #staff. -[rule] -servers = "localhost" -channels = "#staff" -plugins = "reboot" -action = accept +rule accept { + servers "localhost"; + channels "#staff"; + plugins "reboot"; +} -# Example of hooks # This create an hook named "mail" with the given path. -[hooks] -mail = "/path/to/mail.py" +hook mail to "/path/to/mail.py" .Ed .\" SEE ALSO .Sh SEE ALSO