Mercurial > irccd

comparison man/irccd.conf.5 @ 996:2a6d753f79f6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
man: add back
author David Demelier <markand@malikania.fr>
date Thu, 11 Feb 2021 22:13:01 +0100
parents d585adeee610
children c50f954d8c67
comparison
equal deleted inserted replaced
995:0d71bfa6c97a 996:2a6d753f79f6
20 .Sh NAME 20 .Sh NAME
21 .Nm irccd.conf 21 .Nm irccd.conf
22 .Nd irccd configuration file 22 .Nd irccd configuration file
23 .\" DESCRIPTION 23 .\" DESCRIPTION
24 .Sh DESCRIPTION 24 .Sh DESCRIPTION
25 Both 25 The
26 .Nm irccd 26 .Nm
27 and 27 uses a custom configuration file to setup the IRC daemon.
28 .Nm irccdctl 28 .\" SYNTAX
29 use configuration file in a extended INI format. This section will briefly 29 .Sh SYNTAX
30 explain the additional extensions to the INI format. 30 The file consists of several directives that are evaluated in order of
31 .Pp 31 appearance. It is advised to follow the same directive order as described in
32 The file syntax has following rules: 32 this document.
33 .Bl -enum 33 .Pp
34 .It 34 The below sections describe the supported syntax.
35 Each option is stored in a section, 35 .\" Comments
36 .It 36 .Ss Comments
37 Some sections may be redefined multiple times, 37 Comments start when a # is found and continue until the next line.
38 .It 38 .\" Strings
39 Empty option must have quotes (e.g. option = ""). 39 .Ss Strings
40 .El 40 String are either written in pure ASCII strings or enclosed between double
41 .Ss The @include and @tryinclude statements 41 quotes. Because some reserved tokens may collide with your values, it is
42 Irccd adds an extension to this format by adding an 42 recommended to use double quoted strings in user values (such as identifiers,
43 .\" @include and @tryinclude 43 channels names and such). Also, double quotes are required when string contain
44 .Ar @include keyword 44 spaces.
45 which let you splitting your configuration file. 45 .Pp
46 .Pp 46 Example:
47 Note: this @include statement must be at the beginning of the file and must be 47 .Bd -literal -offset indent
48 surrounded by quotes if the file name has spaces. 48 String
49 .Pp 49 "This is a double quoted string"
50 You can use both relative or absolute paths. If relative paths are used, they
51 are relative to the current file being parsed.
52 .Pp
53 The alternative
54 .Ar @tryinclude
55 keyword is similar but does not fails if the requested file is not found.
56 .Pp
57 Example of includes:
58 .Bd -literal -offset Ds
59 @include "rules.conf"
60 @include "servers.conf"
61
62 [mysection]
63 myoption = "1"
64 .Ed 50 .Ed
65 .\" lists 51 .\" Identifiers
66 .Ss The list construct
67 When requested, an option can have multiples values in a list. The syntax uses
68 parentheses and values are separated by commas.
69 .Pp
70 If the list have only one value, you can just use a simple string.
71 .Pp
72 Example of lists:
73 .Bd -literal -offset Ds
74 [rule]
75 servers = ( "server1", "server2" )
76
77 [rule]
78 servers = "only-one-server"
79 .Ed
80 .Pp
81 Note: spaces are completely optional.
82 .\" identifiers
83 .Ss Identifiers 52 .Ss Identifiers
84 Some sections require an identifier (specified as id) as parameter. They must be 53 Some sections require an identifier (specified as id) as parameter. They must be
85 unique, not empty and can only contain characters, numbers, '-' and '_'. 54 unique, not empty and can only contain characters, numbers,
55 .Dq -
56 and
57 .Dq _ .
86 .Pp 58 .Pp
87 Example: both 59 Example: both
88 .Ar abc 60 .Ar abc
89 and 61 and
90 .Ar server-tz2 62 .Ar server-tz2
91 are valid. 63 are valid.
64 .\" Blocks
65 .Ss Blocks
66 For configuration sections that are more complex, block using braces are
67 required and each directive between the enclosing block require a trailing
68 semicolon.
69 .Pp
70 Example:
71 .Bd -literal -offset indent
72 block {
73 option;
74 key and value;
75 }
76 .Ed
77 .\" Lists
78 .Ss Lists
79 Lists are separated by a comma.
80 .Pp
81 Example:
82 .Bd -literal -offset indent
83 one, two, three
84 .Ed
92 .\" CONFIGURATION SECTIONS 85 .\" CONFIGURATION SECTIONS
93 .Sh CONFIGURATION SECTIONS 86 .Sh CONFIGURATION SECTIONS
94 Configuration are always stored in dedicated section in the form 87 The following sections describe what is allowed in the configuration file.
95 .Ar [name] 88 .\" logs
96 where name is one of the section defined below and are case-sensitive.
97 .\" [logs]
98 .Ss logs 89 .Ss logs
99 This section can let you configure how irccd should log the messages. 90 This section can let you configure how irccd should log the messages.
100 .Pp 91 .Bl -tag
101 Available options: 92 .It Ar logs [verbose|quiet] to console
102 .Bl -tag -width 20n 93 Use the standard output and error to log content. This the default.
103 .It Va verbose No (bool) 94 .It Ar logs [verbose|quiet] to syslog
104 Be verbose (Optional, default: false). 95 Use the
105 .It Va type No (string) 96 .Xr syslog 3
106 Which kind of logging, valid values are 97 daemon to log information.
107 .Dq console , 98 .It Ar logs [verbose|quiet] to file path
108 .Dq file 99 Use
109 or 100 .Pa path
110 .Dq syslog 101 to logs every entries.
111 (Optional, default: console). 102 .El
112 .Pp 103 .Pp
113 Note: syslog is not available on all platforms. 104 The optional self explained
114 .El 105 .Op verbose|quiet
115 .Pp 106 argument controls either if verbose logging should be enabled or not. Only
116 The following options are available for the 107 informative messages are affected by this setting. Warnings and debugging
117 .Ar file 108 messages are stored independently from this setting.
118 type: 109 .\" transport
119 .Bl -tag -width 20n 110 .Ss transport
120 .It Va path-logs No (string) 111 Enable transport to interract with the
121 Path to the normal messages. 112 .Nm irccdctl
122 .It Va path-errors No (string) 113 utility or any networking program that can communicate through a UNIX domain
123 Path to the error messages. 114 socket.
124 .El 115 .Pp
125 .\" [templates] 116 .Ar transport to path
126 .Ss templates 117 .Pp
127 The templates section let you change the irccd's output. It uses the templates 118 Enable transport on
128 system (see 119 .Pa path .
129 .Xr irccd-templates 7 120 .\" server
130 for more information about templates)
131 .Pp
132 Only one keyword is defined, message which contains the message that irccd
133 wants to output.
134 .Pp
135 Note: colors and attributes are not supported on Windows.
136 .Pp
137 Available options:
138 .Bl -tag -width 18n
139 .It Va debug No (string)
140 Template to use to format debug messages (Optional, default: none).
141 .It Va info No (string)
142 Template to use to format information messages (Optional, default: none).
143 .It Va warning No (string)
144 Template to use to format warnings (Optional, default: none).
145 .El
146 .\" [server]
147 .Ss server 121 .Ss server
148 This section is used to connect to one or more server. Create a new server 122 This section is used to connect to one or more server. Create a new server
149 section for each IRC server you want to connect to. 123 section block for each IRC server you want to connect to.
150 .Pp 124 .Pp
151 Available options: 125 .Ar server id { options }
152 .Bl -tag -width 26n 126 .Pp
153 .It Va name No (identifier) 127 The following directives are allowed in the
154 The unique id. 128 .Em options
155 .It Va hostname No (string) 129 block:
156 The server address or IP. 130 .Bl -tag -width "hostname value"
157 .It Va port No (int) 131 .It Ar hostname value
158 The server port (Optional, default: 6667). 132 Connect to the
159 .It Va password No (string) 133 .Ar value
160 An optional server password (Optional, default: none). 134 hostname. This can be either a DNS name or a IP address.
161 .It Va join-invite No (bool) 135 .It Ar port value
162 Automatically join channels upon invitation (Optional, default: false). 136 Use
163 .It Va channels No (list) 137 .Ar value
164 List of channels to auto join (Optional, default: empty). 138 number as IP port to connect to.
165 .Pp 139 .It Ar ident nick user realname
166 Note: if a channel requires a password, add it after a colon (e.g. 140 Specify the IRC identity to use by using the three arguments
167 .Dq #channel:password ) . 141 .Ar nick , user
168 .It Va command-char No (string) 142 and
169 The prefix for invoking special commands (Optional, default: !). 143 .Ar realname
170 .It Va ssl No (bool) 144 as nickname, user name and your real name respectively.
171 Enable or disable SSL (Optional, default: false). 145 .Pp
172 .It Va auto-reconnect No (bool) 146 Note: this is not a list of strings but three arguments separated by a space. If
173 Enable reconnection after failure (Optional, default: true). 147 you want to use a real name with spaces, don't forget the double quotes.
174 .It Va auto-reconnect-delay No (int) 148 .It Ar ssl
175 Number of seconds to wait before retrying (Optional, default: 30). 149 Enable SSL. Only available if built with OpenSSL support.
176 .It Va ping-timeout No (int) 150 .It Ar channels list
177 Number of seconds before ping timeout (Optional, default: 1800). 151 List of channels to join automatically when the server is connected
178 .It Va nickname No (string) 152 successfully. This is a list of strings where each element is the channel name
179 The nickname (Optional, default: irccd). 153 to join prepended by a optional
180 .It Va realname No (string) 154 .Ar password@
181 The realname (Optional, default: IRC Client Daemon). 155 if required. You must use double quotes if the channel starts with a hash (#)
182 .It Va username No (string) 156 otherwise it would be detected as a comment.
183 The username name (Optional, default: irccd). 157 .It Ar options list
184 .It Va ctcp-version No (string) 158 Use specific server features. This is a list of string which can be one of
185 What version to respond to CTCP VERSION (Optional, default: IRC Client Daemon). 159 following:
186 .El 160 .Bl -tag -width "AUTO-RECONNECT"
187 .\" [paths] 161 .It Ar AUTO-RECONNECT
188 .Ss paths 162 Reconnect automatically to a server upon disconnection.
189 The paths section defines common paths used as defaults for all plugins. 163 .It Ar AUTO-REJOIN
190 .Pp 164 Automatically rejoin a channel if the bot was kicked from.
191 Any option in this section can be defined altough the following are used as 165 .It Ar JOIN-INVITE
192 common convention used in all plugins: 166 Automatically join a channel upon invitation.
193 .Pp 167 .El
194 Available options: 168 .It Ar prefix value
195 .Bl -tag -width 16n 169 Use
196 .It Va cache No (string) 170 .Ar value
197 Path for data files written by the plugin. 171 as command prefix for plugins (Optional, default:
198 .It Va data No (string) 172 .Dq \&! ) .
199 Path for data files provided by the user. 173 .El
200 .It Va config No (string) 174 .\" rule
201 Path for additional configuration from the user.
202 .El
203 .Pp
204 For each of these paths,
205 .Dq plugin/name
206 is appended with the appropriate plugin name when used.
207 .Pp
208 The section is redefinable per plugin basis using the
209 .Va [paths.<plugin>]
210 syntax.
211 .\" [plugins]
212 .Ss plugins
213 This section is used to load plugins.
214 .Pp
215 Just add any key you like to load a plugin. If the value is not specified, the
216 plugin is searched through the standard directories, otherwise, provide the full
217 path (including the .js extension).
218 .Pp
219 Warning: remember to add an empty string for searching plugins.
220 .\" [hooks]
221 .Ss hooks
222 This sections stores every hooks in key-value pairs. The option key denotes the
223 hook id and the value must be a path to the actual hook file.
224 .\" [transport]
225 .Ss transport
226 This section defines transports that are used to communicate through clients
227 connected to irccd and to perform requests to irccd.
228 .Pp
229 With transports, you may ask irccd to send a message, a notice or even to kick
230 someone from a channel. Irccd will also notify all clients connected to this
231 transport on IRC events.
232 .Pp
233 There are two types of transport availables:
234 .Bl -bullet
235 .It
236 Internet sockets, IPv4 and IPv6,
237 .It
238 Unix sockets, based on files (not available on Windows).
239 .El
240 .Pp
241 If SSL support was built in, both internet and unix sockets can be set to use
242 encrypted connections.
243 .Pp
244 Available options:
245 .Bl -tag -width 18n
246 .It Va type No (string)
247 Type of transport
248 .Dq ip
249 or
250 .Dq unix .
251 .It Va password No (string)
252 An authentication password (Optional, default: none).
253 .It Va ssl No (bool)
254 Enable SSL (Optional, default: false),
255 .It Va key No (string)
256 Path to private key file (Required if ssl is true)
257 .It Va certificate No (string)
258 Path to certificate (Required if ssl is true)
259 .El
260 .Pp
261 The following options are available for the
262 .Ar ip
263 type:
264 .Bl -tag -width 18n
265 .It Va port No (int)
266 Port number.
267 .It Va address No (string)
268 Address to bind or
269 .Dq *
270 for any (Optional, default:
271 .Dq * ) .
272 .It Va ipv4 No (bool)
273 Bind on IPv4 (Optional, default true).
274 .It Va ipv6 No (bool)
275 Bind on IPv6 (Optional, default true).
276 .El
277 .Pp
278 The following options are available for the
279 .Ar unix
280 type:
281 .Bl -tag -width 18n
282 .It Va path No (string)
283 The file path to the socket.
284 .El
285 .\" [rule]
286 .Ss rule 175 .Ss rule
287 The rule section is one of the most powerful within irccd configuration. It lets 176 The rule section is one of the most powerful within irccd configuration. It lets
288 you enable or disable plugins and IRC events for specific criterias. For 177 you enable or disable plugins and IRC events for specific criteria. For
289 instance, you may want to disable a plugin only for a specific channel on a 178 instance, you may want to disable a plugin only for a specific channel on a
290 specific server. And because rules are evaluated in the order they are defined, 179 specific server. And because rules are evaluated in the order they are defined,
291 you can override rules. 180 you can override rules.
292 .Pp 181 .Pp
293 Available options: 182 When you don't specify any value into the corresponding criteria the rule is
294 .Bl -tag -width 15n 183 considered as matched.
295 .It Va servers No (list) 184 .Pp
296 A list of servers that will match the rule (Optional, default: empty). 185 .Ar rule accept|drop { criteria }
297 .It Va channels No (list) 186 .Pp
298 A list of channel (Optional, default: empty). 187 Create a rule that either
299 .It Va origins No (list) 188 .Ar accept
300 A list of nicknames to check (Optional, default: empty).
301 .It Va plugins No (list)
302 Which plugins (Optional, default: empty),
303 .It Va events No (list)
304 Which events like onCommand, onMessage (Optional, default: empty).
305 .It Va action No (string)
306 Set to
307 .Dq accept
308 or 189 or
309 .Dq drop . 190 .Ar drop
191 the current event.
192 .Pp
193 The following directives are allowed in the
194 .Em options
195 block:
196 .Bl -tag -width "channels list"
197 .It Ar servers list
198 List of servers to match by their ids.
199 .It Ar channels list
200 List of channel to match. This can be used to match user nicknames as well.
201 .It Ar origins list
202 List of originators to match.
203 .It Ar events list
204 List of events to match (in the form onCommand, onMessage, etc). See the
205 .Xr irccd 1
206 manual page for the allowed names here.
207 .It Ar plugins list
208 List of plugins to match by their ids.
310 .El 209 .El
311 .Pp 210 .Pp
312 Warning: don't make sensitive rules on origins option, irccd does not have any 211 Warning: don't make sensitive rules on origins option, irccd does not have any
313 kind of nickname authentication. Thus, it may be very easy for someone 212 kind of nickname authentication. Thus, it may be very easy for someone
314 to use a temporary nickname. 213 to use a temporary nickname.
214 .\" hooks
215 .Ss hooks
216 This section loads hooks. The configuration does not test if the file is
217 actually executable nor present on the filesystem and will be tried as long as
218 the daemon is running.
219 .Pp
220 .Ar hook id to path
221 .Pp
222 Load the hook with name
223 .Ar id
224 from the given
225 .Pa path .
226 .\" plugins
227 .Ss plugins
228 This section is used to load plugins.
229 .Pp
230 To load plugin with default values, you can just use the declaration without
231 block of options. Otherwise, use a block to add additional options,
232 .Pp
233 .Ar plugin id { options }
234 .Pp
235 The following directives are allowed in the
236 .Em options
237 block:
238 .Bl -tag -width "hostname value"
239 .It Ar location path
240 Specify an absolute
241 .Pa path
242 to the plugin.
243 .It Ar config { key value }
244 Specify a list of options to the plugin as key-value pair. Each entry consist of
245 two arguments, the option name and its value both as strings. See
246 .Xr EXAMPLES
247 for usage.
248 .It Ar template { key value }
249 Same as
250 .Ar config
251 but for templates. See
252 .Xr irccd-templates 7
253 for more details about this section.
254 .It Ar paths { key value }
255 Same as
256 .Ar config
257 but for additional paths. Individual plugins may accept special paths but the
258 following are reserved by irccd and always set when loading the plugin unless
259 explicitly overriden in this section:
260 .Bl -tag
261 .It Ar cache
262 Directory for temporary files.
263 .It Ar data
264 Directory for additional data.
265 .It Ar config
266 Directory to additional configuration files.
267 .El
268 .El
315 .\" EXAMPLES 269 .\" EXAMPLES
316 .Sh EXAMPLES 270 .Sh EXAMPLES
317 Full example of configuration file 271 Full example of configuration file
318 .Bd -literal 272 .Bd -literal
319 # Add a transport that bind only to IPv6. 273 # Logs to syslog instead of console (which is the default).
320 [transport] 274 logs verbose to syslog
321 type = ip 275
322 ipv4 = false 276 #
323 ipv6 = true 277 # Create a server "example" that connect to example.org using "fr" as nickname,
324 port = 12000 278 # "francis" as username and "Francis Meyer" as realname.
325 279 #
326 # A transport that binds to both IPv4 and IPv6. 280 # This channel will automatically join "#test" on connection and the password
327 [transport] 281 # protected "#nightclub" channel with password "secret"
328 type = ip 282 #
329 port = 15000 283 server example {
330 284 hostname example.org;
331 # A server. 285 port 6667;
332 [server] 286 ident fr francis "Francis Meyer";
333 name = "foo" 287 channels "#test", "secret@#nightclub";
334 host = "irc.foo.org" 288 }
335 port = "6667" 289
336 nickname = "superbot" 290 # Load several plugins with their default values and locations.
337 realname = "SuperBot v1.0" 291 plugin ask
338 username = "sp" 292 plugin plugin
339 293
340 # An other server. 294 # Configure the plugin hangman to change templates and the path to the words.
341 [server] 295 plugin hangman {
342 name = "wanadoo" 296 templates {
343 host = "chat.wanadoo.fr" 297 win "Success, the word was #{word}!";
344 port = "6667" 298 }
345 299 config {
346 # Load some plugins. 300 file "/var/irccd/hard-words.txt";
347 [plugins] 301 }
348 ask = "" # Search ask 302 }
349 myplugin = /path/to/myplugin.js # Use absolute path
350 303
351 # This first rule disable the plugin reboot on all servers and channels. 304 # This first rule disable the plugin reboot on all servers and channels.
352 [rule] 305 rule drop {
353 plugins = "reboot" 306 plugins "reboot";
354 action = drop 307 }
355 308
356 # This rule enable the reboot plugin again on the server localhost, 309 # This rule enable the reboot plugin again on the server localhost,
357 # channel #staff. 310 # channel #staff.
358 [rule] 311 rule accept {
359 servers = "localhost" 312 servers "localhost";
360 channels = "#staff" 313 channels "#staff";
361 plugins = "reboot" 314 plugins "reboot";
362 action = accept 315 }
363 316
364 # Example of hooks
365 # This create an hook named "mail" with the given path. 317 # This create an hook named "mail" with the given path.
366 [hooks] 318 hook mail to "/path/to/mail.py"
367 mail = "/path/to/mail.py"
368 .Ed 319 .Ed
369 .\" SEE ALSO 320 .\" SEE ALSO
370 .Sh SEE ALSO 321 .Sh SEE ALSO
371 .Xr irccd 1 322 .Xr irccd 1
372 .\" AUTHORS 323 .\" AUTHORS