Mercurial > irccd
comparison 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 |
comparison
equal
deleted
inserted
replaced
844:dc6b42d7b97a | 845:00a4720c4874 |
---|---|
1 .\" | |
2 .\" Copyright (c) 2013-2019 David Demelier <markand@malikania.fr> | |
3 .\" | |
4 .\" Permission to use, copy, modify, and/or distribute this software for any | |
5 .\" purpose with or without fee is hereby granted, provided that the above | |
6 .\" copyright notice and this permission notice appear in all copies. | |
7 .\" | |
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | |
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
15 .\" | |
16 .Dd @IRCCD_MAN_DATE@ | |
17 .Dt IRCCD.CONF 5 | |
18 .Os | |
19 .\" NAME | |
20 .Sh NAME | |
21 .Nm irccd | |
22 .Nd irccd configuration file | |
23 .\" DESCRIPTION | |
24 .Sh DESCRIPTION | |
25 Both | |
26 .Nm irccd | |
27 and | |
28 .Nm irccdctl | |
29 use configuration file in a extended INI format. This section will briefly | |
30 explain the additional extensions to the INI format. | |
31 .Pp | |
32 The file syntax has following rules: | |
33 .Bl -enum | |
34 .It | |
35 Each option is stored in a section, | |
36 .It | |
37 Some sections may be redefined multiple times, | |
38 .It | |
39 Empty option must have quotes (e.g. option = ""). | |
40 .El | |
41 .Ss The @include and @tryinclude statements | |
42 Irccd adds an extension to this format by adding an | |
43 .\" @include and @tryinclude | |
44 .Ar @include keyword which | |
45 let you splitting your configuration file. | |
46 .Pp | |
47 Note: this @include statement must be at the beginning of the file and must be | |
48 surrounded by quotes if the file name has spaces. | |
49 .Pp | |
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 | |
65 .\" lists | |
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 | |
84 Some sections require an identifier (specified as id) as parameter. They must be | |
85 unique, not empty and can only contain characters, numbers, '-' and '_'. | |
86 .Pp | |
87 Example: both | |
88 .Ar abc | |
89 and | |
90 .Ar server-tz2 | |
91 are valid. | |
92 .\" CONFIGURATION SECTIONS | |
93 .Sh CONFIGURATION SECTIONS | |
94 Configuration are always stored in dedicated section in the form | |
95 .Ar [name] | |
96 where name is one of the section defined below and are case-sensitive. | |
97 .\" [logs] | |
98 .Ss logs | |
99 This section can let you configure how irccd should log the messages. | |
100 .Pp | |
101 Available options: | |
102 .Bl -tag -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx | |
103 .It Va verbose No (bool) | |
104 be verbose (Optional, default: false). | |
105 .It Va type No (string) | |
106 which kind of logging, console, file or syslog (Optional, default: console). | |
107 .Pp | |
108 The additional options for | |
109 .Ar file | |
110 type: | |
111 .Bl -tag -width indent-xxxxxxxxxxxxx | |
112 .It Va path-logs No (string) | |
113 path to the normal messages. | |
114 .It Va path-errors No (string) | |
115 path to the error messages. | |
116 .El | |
117 .Pp | |
118 Note: syslog is not available on all platforms. | |
119 .El | |
120 .\" [format] | |
121 .Ss format | |
122 The format section let you change the irccd's output. It uses the templates | |
123 system (see | |
124 .Xr irccd-format 7 | |
125 for more information about templates) | |
126 .Pp | |
127 Only one keyword is defined, message which contains the message that irccd | |
128 wants to output. | |
129 .Pp | |
130 Note: colors and attributes are not supported on Windows. | |
131 .Pp | |
132 Available options: | |
133 .Bl -tag -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx | |
134 .It Va debug No (string) | |
135 template to use to format debug messages (Optional, default: none). | |
136 .It Va info No (string) | |
137 template to use to format information messages (Optional, default: none). | |
138 .It Va warning No (string) | |
139 template to use to format warnings (Optional, default: none). | |
140 .El | |
141 .\" [server] | |
142 .Ss server | |
143 This section is used to connect to one or more server. | |
144 .Pp | |
145 Available options: | |
146 .Bl -tag -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx | |
147 .It Va name No (identifier) | |
148 the unique id. | |
149 .It Va hostname No (string) | |
150 the server address or IP. | |
151 .It Va port No (int) | |
152 the server port (Optional, default: 6667). | |
153 .It Va password No (string) | |
154 an optional server password (Optional, default: none). | |
155 .It Va join-invite No (bool) | |
156 automatically join channels upon invitation (Optional, default: false). | |
157 .It Va channels No (list) | |
158 list of channels to auto join (Optional, default: empty). | |
159 .Pp | |
160 Note: if a channel requires a password, add it after a colon | |
161 (e.g. #channel:password). | |
162 .It Va command-char No (string) | |
163 the prefix for invoking special commands (Optional, default: !). | |
164 .It Va ssl No (bool) | |
165 enable or disable SSL (Optional, default: false). | |
166 .It Va auto-reconnect No (bool) | |
167 enable reconnection after failure (Optional, default: true). | |
168 .It Va auto-reconnect-delay No (int) | |
169 number of seconds to wait before retrying (Optional, default: 30). | |
170 .It Va ping-timeout No (int) | |
171 number of seconds before ping timeout (Optional, default: 300). | |
172 .It Va nickname No (string) | |
173 the nickname (Optional, default: irccd). | |
174 .It Va realname No (string) | |
175 the realname (Optional, default: IRC Client Daemon). | |
176 .It Va username No (string) | |
177 the username name (Optional, default: irccd). | |
178 .It Va ctcp-version No (string) | |
179 what version to respond to CTCP VERSION (Optional, default: IRC Client Daemon). | |
180 .El | |
181 .\" [paths] | |
182 .Ss paths | |
183 The paths section defines common paths used as defaults for all plugins. | |
184 .Pp | |
185 Any option in this section can be defined altough the following are used as | |
186 common convention used in all plugins: | |
187 .Pp | |
188 Available options: | |
189 .Bl -tag -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx | |
190 .It Va cache No (string) | |
191 path for data files written by the plugin. | |
192 .It Va data No (string) | |
193 path for data files provided by the user. | |
194 .It Va config No (string) | |
195 path for additional configuration from the user. | |
196 .El | |
197 .Pp | |
198 For each of these paths, plugin/name is appended with the appropriate plugin | |
199 name when used. | |
200 .Pp | |
201 The section is redefinable per plugin basis using the | |
202 .Va [paths.<plugin>] | |
203 syntax. | |
204 .Ss plugins | |
205 This section is used to load plugins. | |
206 .Pp | |
207 Just add any key you like to load a plugin. If the value is not specified, the | |
208 plugin is searched through the standard directories, otherwise, provide the full | |
209 path (including the .js extension). | |
210 .Pp | |
211 Warning: remember to add an empty string for searching plugins. | |
212 .\" [transport] | |
213 .Ss transport | |
214 This section defines transports that are used to communicate through clients | |
215 connected to irccd and to perform requests to irccd. | |
216 .Pp | |
217 With transports, you can may ask irccd to send a message, a notice or even | |
218 kicking someone from a channel. Irccd will also notify all clients connected to | |
219 this transport on IRC events. | |
220 .Pp | |
221 There are two type of listeners availables: | |
222 .Bl -bullet | |
223 .It | |
224 Internet sockets, IPv4 and IPv6, | |
225 .It | |
226 Unix sockets, based on files (not available on Windows). | |
227 .El | |
228 .Pp | |
229 If SSL support was built in, both internet and unix sockets can be set to use | |
230 encrypted connections. | |
231 .Pp | |
232 Available options: | |
233 .Bl -tag -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx | |
234 .It Va type No (string) | |
235 type of listener "ip" or "unix". | |
236 .It Va password No (string) | |
237 an authentication password (Optional, default: none). | |
238 .It Va ssl No (bool) | |
239 enable SSL (Optional, default: false), | |
240 .It Va key No (string) | |
241 path to private key file (Required if ssl is true) | |
242 .It Va certificate No (string) | |
243 path to certificate (Required if ssl is true) | |
244 .Pp | |
245 The additional options for ip type: | |
246 .Bl -tag -width indent-xxxxxxxxx | |
247 .It Va port No (int) | |
248 port number. | |
249 .It Va address No (string) | |
250 address to bind or * for any (Optional, default: *). | |
251 .It Va ipv4 No (bool) | |
252 bind on IPv4 (Optional, default true). | |
253 .It Va ipv6 No (bool) | |
254 bind on IPv6 (Optional, default true). | |
255 .El | |
256 .Pp | |
257 The additional options for unix type: | |
258 .Bl -tag -width indent-xxxxxxxxx | |
259 .It Va path No (string) | |
260 the file path to the socket. | |
261 .El | |
262 .El | |
263 .Pp | |
264 Warning: consider using internet sockets with care, especially if you are | |
265 running your bot on a server with multiple users. If your bot has | |
266 operator rights and you bind on any address, almost every users | |
267 can do a kick or a ban. | |
268 .\" [rule] | |
269 .Ss rule | |
270 The rule section is one of the most powerful within irccd configuration. It let | |
271 you enable or disable plugins and IRC events for specific criterias. For | |
272 instance, you may want to disable a plugin only for a specific channel on a | |
273 specific server. And because rules are evaluated in the order they are defined, | |
274 you can override rules. | |
275 .Pp | |
276 Available options: | |
277 .Bl -tag -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx | |
278 .It Va servers No (list) | |
279 a list of servers that will match the rule (Optional, default: empty). | |
280 .It Va channels No (list) | |
281 a list of channel (Optional, default: empty). | |
282 .It Va origins No (list) | |
283 a list of nicknames to check (Optional, default: empty). | |
284 .It Va plugins No (list) | |
285 which plugins (Optional, default: empty), | |
286 .It Va events No (list) | |
287 which events like onCommand, onMessage (Optional, default: empty). | |
288 .It Va action No (string) | |
289 set to accept or drop. | |
290 .El | |
291 .Pp | |
292 Warning: don't make sensitive rules on origins option, irccd does not have any | |
293 kind of nickname authentication. Thus, it may be very easy for someone | |
294 to use a temporary nickname. | |
295 .Sh EXAMPLE | |
296 Full example of configuration file | |
297 .Bd -literal | |
298 # Add a transport that bind only to IPv6. | |
299 [transport] | |
300 type = ip | |
301 ipv4 = false | |
302 ipv6 = true | |
303 family = ipv6 | |
304 port = 12000 | |
305 | |
306 # A transport that binds to both IPv4 and IPv6. | |
307 [transport] | |
308 type = ip | |
309 port = 15000 | |
310 | |
311 # A server. | |
312 [server] | |
313 name = "foo" | |
314 host = "irc.foo.org" | |
315 port = "6667" | |
316 nickname = "superbot" | |
317 realname = "SuperBot v1.0" | |
318 username = "sp" | |
319 | |
320 # An other server. | |
321 [server] | |
322 name = "wanadoo" | |
323 host = "chat.wanadoo.fr" | |
324 port = "6667" | |
325 | |
326 # Load some plugins. | |
327 [plugins] | |
328 ask = "" # Search ask | |
329 myplugin = /path/to/myplugin.js # Use absolute path | |
330 | |
331 # This first rule disable the plugin reboot on all servers and channels. | |
332 [rule] | |
333 plugins = "reboot" | |
334 action = drop | |
335 | |
336 # This rule enable the reboot plugin again on the server localhost, | |
337 # channel #staff. | |
338 [rule] | |
339 servers = "localhost" | |
340 channels = "#staff" | |
341 plugins = "reboot" | |
342 action = accept | |
343 .Ed | |
344 .Sh SEE ALSO | |
345 .Xr irccd 1 |