Mercurial > irccd
comparison doc/src/irccd.conf.md @ 607:bb9771fb5f44
Docs: rework documentation
- Change directories,
- Remove handwritten manual pages.
author | David Demelier <markand@malikania.fr> |
---|---|
date | Fri, 08 Dec 2017 20:11:22 +0100 |
parents | |
children | 168ea30142d9 |
comparison
equal
deleted
inserted
replaced
606:4f5f306d13ac | 607:bb9771fb5f44 |
---|---|
1 % irccd.conf | |
2 % David Demelier | |
3 % 2017-12-08 | |
4 | |
5 Both `irccd` and `irccdctl` use configuration file in a extended [INI][ini] | |
6 format. | |
7 | |
8 # General syntax | |
9 | |
10 The file syntax has following rules: | |
11 | |
12 1. Each option is stored in a section, | |
13 2. Some sections may be redefined multiple times, | |
14 3. Empty option must have quotes (e.g. `option = ""`). | |
15 | |
16 # The @include statement | |
17 | |
18 Irccd adds an extension to this format by adding an `@include` keyword which | |
19 let you splitting your configuration file. | |
20 | |
21 Note: this `@include` statement must be at the beginning of the file and must be | |
22 surrounded by quotes if the file name has spaces. | |
23 | |
24 You can use both relative or absolute paths. If relative paths are used, they | |
25 are relative to the current file being parsed. | |
26 | |
27 ## Example | |
28 | |
29 ```ini | |
30 @include "rules.conf" | |
31 @include "servers.conf" | |
32 | |
33 [mysection] | |
34 myoption = "1" | |
35 ``` | |
36 | |
37 # The list construct | |
38 | |
39 When requested, an option can have multiples values in a list. The syntax uses | |
40 parentheses and values are separated by commas. | |
41 | |
42 If the list have only one value, you can just use a simple string. | |
43 | |
44 ## Examples | |
45 | |
46 ```ini | |
47 [rule] | |
48 servers = ( "server1", "server2" ) | |
49 ``` | |
50 | |
51 ```ini | |
52 [rule] | |
53 servers = "only-one-server" | |
54 ``` | |
55 | |
56 Note: spaces are completely optional. | |
57 | |
58 Options that have a default value are optional and can be omitted. | |
59 | |
60 # Identifiers | |
61 | |
62 Some sections require an identifier (specified as id) as parameter. They must be | |
63 unique, not empty and can only contain characters, numbers, '-' and '_'. | |
64 | |
65 Example: | |
66 | |
67 - abc | |
68 - server-tz2 | |
69 | |
70 # The general section | |
71 | |
72 This section contains global options that are used in the whole irccd | |
73 application. | |
74 | |
75 The available options: | |
76 | |
77 - **uid**: (string or number) the user id to use (Optional, default: none), | |
78 - **gid**: (string or number) the group id to use (Optional, default: none), | |
79 - **foreground**: (bool) set to true to not daemonize | |
80 (Optional, default: false) | |
81 - **pidfile**: (string) path to a file where to store the irccd pid | |
82 (Optional, default: none). | |
83 | |
84 **Warning:** these options are available only if the system supports them. | |
85 | |
86 ## Example | |
87 | |
88 ```ini | |
89 [general] | |
90 pidfile = "/var/run/irccd/pid" | |
91 uid = "nobody" | |
92 gid = 1002 | |
93 ``` | |
94 | |
95 # The logs section | |
96 | |
97 This section can let you configure how irccd should log the messages. | |
98 | |
99 The available options: | |
100 | |
101 - **verbose**: (bool) be verbose (Optional, default: false), | |
102 - **type**: (string) which kind of logging, console, file or syslog | |
103 (Optional, default: console). | |
104 | |
105 The options for **file** type: | |
106 | |
107 - **path-logs**: (string) path to the normal messages, | |
108 - **path-errors**: (string) path to the error messages. | |
109 | |
110 **Note:** syslog is not available on all platforms. | |
111 | |
112 ## Example | |
113 | |
114 ```ini | |
115 [logs] | |
116 type = file | |
117 verbose = true | |
118 path-logs = "/var/log/irccd/log.txt" | |
119 path-errors = "/var/log/irccd/errors.txt" | |
120 ``` | |
121 | |
122 # The format section | |
123 | |
124 The format section let you change the irccd's output. It uses the templates | |
125 system. | |
126 | |
127 Only one keyword is defined, `message` which contains the message that irccd | |
128 wants to output. | |
129 | |
130 **Note:** colors and attributes are not supported. | |
131 | |
132 The available options: | |
133 | |
134 - **debug**: (string) template to use to format debug messages | |
135 (Optional, default: none), | |
136 - **info**: (string) template to use to format information messages | |
137 (Optional, default: none), | |
138 - **warning**: (string) template to use to format warnings | |
139 (Optional, default: none). | |
140 | |
141 ## Example | |
142 | |
143 ```ini | |
144 [format] | |
145 debug = "%H:%M debug: #{message}" | |
146 info = "%H:%M info: #{message}" | |
147 warning = "%H:%M warning: #{message}" | |
148 ``` | |
149 | |
150 # The identity section | |
151 | |
152 This section is completely optional, if you don't provide one, irccd will use a | |
153 default identity with your system account name as nickname and username. If | |
154 irccd was unable to get your account name, it uses **irccd** as a fallback. | |
155 | |
156 This section is redefinable, you can create one or more. | |
157 | |
158 The available options: | |
159 | |
160 - **name**: (id) the identity unique id, | |
161 - **nickname**: (string) the nickname | |
162 (Optional, default: system username if available or irccd), | |
163 - **realname**: (string) the realname | |
164 (Optional, default: IRC Client Daemon), | |
165 - **username**: (string) the username name | |
166 (Optional, default: system username if available or irccd), | |
167 - **ctcp-version**: (string) what version to respond to CTCP VERSION | |
168 (Optional, default: IRC Client Daemon). | |
169 | |
170 ## Example | |
171 | |
172 ```ini | |
173 [identity] | |
174 name = "default" | |
175 nickname = "jean" | |
176 | |
177 [identity] | |
178 name = "development" | |
179 nickname = "unstable" | |
180 username = "un" | |
181 ``` | |
182 | |
183 # The server section | |
184 | |
185 This section is used to connect to one or more server. | |
186 | |
187 This section is redefinable, you can create one or more. | |
188 | |
189 The available options: | |
190 | |
191 - **name**: (id) the unique id, | |
192 - **host**: (string) the server address, | |
193 - **port**: (int) the server port (Optional, default: 6667), | |
194 - **identity**: (string) an identity to use | |
195 (Optional, default: irccd's default), | |
196 - **password**: (string) an optional password | |
197 (Optional, default: none), | |
198 - **join-invite**: (bool) join channels upon invitation | |
199 (Optional, default: false), | |
200 - **channels**: (list) list of channels to auto join | |
201 (Optional, default: empty), | |
202 - **command-char**: (string) the prefix for invoking special commands | |
203 (Optional, default: !), | |
204 - **ssl**: (bool) enable or disable SSL (Optional, default: false), | |
205 - **ssl-verify**: (bool) verify the SSL certificates | |
206 (Optional, default: true), | |
207 - **reconnect**: (bool) enable reconnection after failure | |
208 (Optional, default: true), | |
209 - **reconnect-tries**: (int) number of tries before giving up. A value of | |
210 -1 means indefinitely (Optional, default: -1), | |
211 - **reconnect-timeout**: (int) number of seconds to wait before retrying | |
212 (Optional, default: 30), | |
213 - **ping-timeout** (int) number of seconds before ping timeout | |
214 (Optional, default: 300). | |
215 | |
216 **Note:** if a channel requires a password, add it after a colon | |
217 (e.g. "#channel:password"). | |
218 | |
219 ## Example | |
220 | |
221 ```ini | |
222 [server] | |
223 name = "local" | |
224 host = "localhost" | |
225 port = 6667 | |
226 channels = ( "#staff", "#club:secret" ) | |
227 ``` | |
228 | |
229 # The paths section | |
230 | |
231 The paths section defines common paths used as defaults for all plugins. | |
232 | |
233 Any option in this section can be defined altough the following are used as | |
234 common convention used in all plugins: | |
235 | |
236 - **cache**: (string) path for data files written by the plugin, | |
237 - **data**: (string) path for data files provided by the user, | |
238 - **config**: (string) path for additional configuration from the user. | |
239 | |
240 For each of these paths, **plugin/name** is appended with the appropriate | |
241 plugin name when loaded. | |
242 | |
243 The section is redefinable per plugin basis using the `[paths.<plugin>]` syntax. | |
244 | |
245 ## Example | |
246 | |
247 ```ini | |
248 # | |
249 # Common for all plugins. | |
250 # | |
251 # Example with ask plugin: | |
252 # | |
253 # cache -> /var/cache/irccd/plugin/ask | |
254 # config -> /usr/local/etc/irccd/plugin/ask | |
255 # data -> /var/data/irccd/plugin/ask | |
256 # | |
257 [paths] | |
258 cache = "/var/cache/irccd" | |
259 config = "/usr/local/etc/irccd" | |
260 data = "/var/data/irccd" | |
261 | |
262 # | |
263 # Explicit override for plugin hangman. | |
264 # | |
265 [paths.hangman] | |
266 config = "/etc/hangman" | |
267 ``` | |
268 | |
269 # The plugins section | |
270 | |
271 This section is used to load plugins. | |
272 | |
273 Just add any key you like to load a plugin. If the value is not specified, the | |
274 plugin is searched through the standard directories, otherwise, provide the full | |
275 path (including the .js extension). | |
276 | |
277 **Warning:** remember to add an empty string for searching plugins. | |
278 | |
279 ## Example | |
280 | |
281 ```ini | |
282 [plugins] | |
283 history = "" | |
284 myplugin = /tmp/myplugin.js | |
285 ``` | |
286 | |
287 The `history` plugin will be searched while `myplugin` will be load from | |
288 **/tmp/myplugin.js**. | |
289 | |
290 # The transport section | |
291 | |
292 This section defines transports, you may use sockets to do a basic IPC system | |
293 within irccd. | |
294 | |
295 With transports, you can may ask `irccd` to send a message, a notice or even | |
296 kicking someone from a channel. Irccd will also notify all clients connected to | |
297 this transport on IRC events. | |
298 | |
299 There are two type of listeners availables: | |
300 | |
301 1. Internet sockets, IPv4 and IPv6, | |
302 2. Unix sockets, based on files (not available on Windows). | |
303 | |
304 The available options: | |
305 | |
306 - **type**: (string) type of listener "ip" or "unix". | |
307 - **password**: (string) an authentication password (Optional, default: none). | |
308 | |
309 The options for **ip** type: | |
310 | |
311 - **port**: (int) port number, | |
312 - **address**: (string) address to bind or "\*" for any | |
313 (Optional, default: \*), | |
314 - **family**: (list) ipv6, ipv4. Both are accepted (Optional, default: ipv4), | |
315 - **ssl**: (bool) enable SSL (Optional, default: false), | |
316 - **key**: (string) path to private key file (Optional, default: none), | |
317 - **certificate**: (string) path to certificate (Optional, default: none). | |
318 | |
319 The options for **unix** type: | |
320 | |
321 - **path**: (string) the file path to the socket. | |
322 | |
323 ## Example of internet transports | |
324 | |
325 ```ini | |
326 [transport] | |
327 type = "ip" | |
328 address = "*" | |
329 family = ( "ipv4", "ipv6" ) | |
330 port = 9999 | |
331 ``` | |
332 | |
333 This will let you controlling irccd on port 9999 with both IPv4 and IPv6 | |
334 families. | |
335 | |
336 **Warning**: consider using internet sockets with care, especially if you are | |
337 running your bot on a server with multiple users. If your bot has | |
338 operator rights and you bind on any address, almost every users | |
339 can do a kick or a ban. | |
340 | |
341 ## Example of unix transports | |
342 | |
343 ```ini | |
344 [transport] | |
345 type = "unix" | |
346 path = "/tmp/irccd.sock" | |
347 ``` | |
348 | |
349 This will let you controlling irccd on path **/tmp/irccd.sock**, the file is | |
350 automatically deleted when irccd starts, but not when it stops. | |
351 | |
352 # The rule section | |
353 | |
354 The rule section is one of the most powerful within irccd configuration. It let | |
355 you enable or disable plugins and IRC events for specific criterias. For | |
356 instance, you may want to disable a plugin only for a specific channel on a | |
357 specific server. And because rules are evaluated in the order they are defined, | |
358 you can override rules. | |
359 | |
360 The available options: | |
361 | |
362 - **servers**, (list) a list of servers that will match the rule | |
363 (Optional, default: empty), | |
364 - **channels**, (list) a list of channel (Optional, default: empty), | |
365 - **plugins**, (list) which plugins (Optional, default: empty), | |
366 - **events**, (list) which events (e.g onCommand, onMessage, ...) | |
367 (Optional, default: empty), | |
368 - **action**, (string) set to **accept** or **drop**. | |
369 | |
370 ## Basic rules example | |
371 | |
372 This first rule disable the plugin reboot on **all** servers and channels. | |
373 | |
374 ```ini | |
375 [rule] | |
376 plugins = "reboot" | |
377 action = drop | |
378 ``` | |
379 | |
380 This rule enable the reboot plugin again on the server **localhost**, | |
381 channel **#staff**. | |
382 | |
383 ```ini | |
384 [rule] | |
385 servers = "localhost" | |
386 channels = "#staff" | |
387 plugins = "reboot" | |
388 action = accept | |
389 ``` | |
390 | |
391 # Full example of configuration file | |
392 | |
393 ```ini | |
394 # Add a transport that bind only to IPv6. | |
395 [transport] | |
396 type = ip | |
397 family = ipv6 | |
398 port = 12000 | |
399 | |
400 # A transport that binds to both IPv4 and IPv6. | |
401 [transport] | |
402 type = ip | |
403 family = ( ipv4, ipv6 ) | |
404 port = 15000 | |
405 | |
406 # Identity reused by many servers. | |
407 [identity] | |
408 name = "myIdentity" | |
409 nickname = "superbot" | |
410 realname = "SuperBot v1.0" | |
411 username = "sp" | |
412 | |
413 # A server. | |
414 [server] | |
415 name = "foo" | |
416 host = "irc.foo.org" | |
417 port = "6667" | |
418 identity = myIdentity | |
419 | |
420 # An other server. | |
421 [server] | |
422 name = "wanadoo" | |
423 host = "chat.wanadoo.fr" | |
424 port = "6667" | |
425 identity = myIdentity | |
426 | |
427 # Load some plugins. | |
428 [plugins] | |
429 ask = "" # Search ask | |
430 myplugin = /path/to/myplugin.js # Use absolute path | |
431 ``` | |
432 | |
433 [ini]: https://en.wikipedia.org/wiki/INI_file | |
434 |