Mercurial > irccd
view man/irccd.conf.5 @ 845:00a4720c4874
doc: rewrite documentation in manual pages, closes #1674
Get rid of markdown documentation and the custom generator tools, instead use
raw manual pages.
author | David Demelier <markand@malikania.fr> |
---|---|
date | Mon, 08 Jul 2019 16:15:57 +0200 |
parents | |
children | a23b7b574ed2 |
line wrap: on
line source
.\" .\" 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 .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 -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx .It Va verbose No (bool) be verbose (Optional, default: false). .It Va type No (string) which kind of logging, console, file or syslog (Optional, default: console). .Pp The additional options for .Ar file type: .Bl -tag -width indent-xxxxxxxxxxxxx .It Va path-logs No (string) path to the normal messages. .It Va path-errors No (string) path to the error messages. .El .Pp Note: syslog is not available on all platforms. .El .\" [format] .Ss format The format section let you change the irccd's output. It uses the templates system (see .Xr irccd-format 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 -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx .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. .Pp Available options: .Bl -tag -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx .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. #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 -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx .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, 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 can may ask irccd to send a message, a notice or even kicking someone from a channel. Irccd will also notify all clients connected to this transport on IRC events. .Pp There are two type of listeners 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 -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx .It Va type No (string) type of listener "ip" or "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) .Pp The additional options for ip type: .Bl -tag -width indent-xxxxxxxxx .It Va port No (int) port number. .It Va address No (string) address to bind or * for any (Optional, default: *). .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 additional options for unix type: .Bl -tag -width indent-xxxxxxxxx .It Va path No (string) the file path to the socket. .El .El .Pp Warning: consider using internet sockets with care, especially if you are running your bot on a server with multiple users. If your bot has operator rights and you bind on any address, almost every users can do a kick or a ban. .\" [rule] .Ss rule The rule section is one of the most powerful within irccd configuration. It let 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 -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx .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 accept or 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. .Sh EXAMPLE Full example of configuration file .Bd -literal # Add a transport that bind only to IPv6. [transport] type = ip ipv4 = false ipv6 = true family = ipv6 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 .Sh SEE ALSO .Xr irccd 1