Mercurial > irccd
view man/irccd.conf.5 @ 1091:52be05336310
irccdctl: misc cleanups
author | David Demelier <markand@malikania.fr> |
---|---|
date | Wed, 21 Jul 2021 16:06:36 +0200 |
parents | c1c9a2cd63cb |
children | c46217eaac45 |
line wrap: on
line source
.\" .\" Copyright (c) 2013-2021 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 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" # server example { hostname example.org; port 6667; ident fr francis "Francis Meyer"; channels "#test", "secret@#nightclub"; } # 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>