Mercurial > irccd

comparison man/irccd.conf.5 @ 845:00a4720c4874

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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