Mercurial > irccd

comparison man/irccd.conf.5 @ 856:6c4fb8f42aca

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: improve wording and style
author David Demelier <markand@malikania.fr>
date Wed, 24 Jul 2019 21:50:00 +0000
parents a23b7b574ed2
children bf2bdb41f181
comparison
equal deleted inserted replaced
855:199b146e8163 856:6c4fb8f42aca
43 .\" @include and @tryinclude 43 .\" @include and @tryinclude
44 .Ar @include keyword which 44 .Ar @include keyword which
45 let you splitting your configuration file. 45 let you splitting your configuration file.
46 .Pp 46 .Pp
47 Note: this @include statement must be at the beginning of the file and must be 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. 48 surrounded by quotes if the file name has spaces.
49 .Pp 49 .Pp
50 You can use both relative or absolute paths. If relative paths are used, they 50 You can use both relative or absolute paths. If relative paths are used, they
51 are relative to the current file being parsed. 51 are relative to the current file being parsed.
52 .Pp 52 .Pp
53 The alternative 53 The alternative
97 .\" [logs] 97 .\" [logs]
98 .Ss logs 98 .Ss logs
99 This section can let you configure how irccd should log the messages. 99 This section can let you configure how irccd should log the messages.
100 .Pp 100 .Pp
101 Available options: 101 Available options:
102 .Bl -tag -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx 102 .Bl -tag -width 20n
103 .It Va verbose No (bool) 103 .It Va verbose No (bool)
104 be verbose (Optional, default: false). 104 Be verbose (Optional, default: false).
105 .It Va type No (string) 105 .It Va type No (string)
106 which kind of logging, console, file or syslog (Optional, default: console). 106 Which kind of logging, valid values are
107 .Pp 107 .Dq console ,
108 The additional options for 108 .Dq file
109 or
110 .Dq syslog
111 (Optional, default: console).
112 .Pp
113 Note: syslog is not available on all platforms.
114 .El
115 .Pp
116 The following options are available for the
109 .Ar file 117 .Ar file
110 type: 118 type:
111 .Bl -tag -width indent-xxxxxxxxxxxxx 119 .Bl -tag -width 20n
112 .It Va path-logs No (string) 120 .It Va path-logs No (string)
113 path to the normal messages. 121 Path to the normal messages.
114 .It Va path-errors No (string) 122 .It Va path-errors No (string)
115 path to the error messages. 123 Path to the error messages.
116 .El
117 .Pp
118 Note: syslog is not available on all platforms.
119 .El 124 .El
120 .\" [templates] 125 .\" [templates]
121 .Ss templates 126 .Ss templates
122 The templates section let you change the irccd's output. It uses the templates 127 The templates section let you change the irccd's output. It uses the templates
123 system (see 128 system (see
128 wants to output. 133 wants to output.
129 .Pp 134 .Pp
130 Note: colors and attributes are not supported on Windows. 135 Note: colors and attributes are not supported on Windows.
131 .Pp 136 .Pp
132 Available options: 137 Available options:
133 .Bl -tag -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx 138 .Bl -tag -width 18n
134 .It Va debug No (string) 139 .It Va debug No (string)
135 template to use to format debug messages (Optional, default: none). 140 Template to use to format debug messages (Optional, default: none).
136 .It Va info No (string) 141 .It Va info No (string)
137 template to use to format information messages (Optional, default: none). 142 Template to use to format information messages (Optional, default: none).
138 .It Va warning No (string) 143 .It Va warning No (string)
139 template to use to format warnings (Optional, default: none). 144 Template to use to format warnings (Optional, default: none).
140 .El 145 .El
141 .\" [server] 146 .\" [server]
142 .Ss server 147 .Ss server
143 This section is used to connect to one or more server. 148 This section is used to connect to one or more server. Create a new server
144 .Pp 149 section for each IRC server you want to connect to.
145 Available options: 150 .Pp
146 .Bl -tag -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx 151 Available options:
152 .Bl -tag -width 26n
147 .It Va name No (identifier) 153 .It Va name No (identifier)
148 the unique id. 154 The unique id.
149 .It Va hostname No (string) 155 .It Va hostname No (string)
150 the server address or IP. 156 The server address or IP.
151 .It Va port No (int) 157 .It Va port No (int)
152 the server port (Optional, default: 6667). 158 The server port (Optional, default: 6667).
153 .It Va password No (string) 159 .It Va password No (string)
154 an optional server password (Optional, default: none). 160 An optional server password (Optional, default: none).
155 .It Va join-invite No (bool) 161 .It Va join-invite No (bool)
156 automatically join channels upon invitation (Optional, default: false). 162 Automatically join channels upon invitation (Optional, default: false).
157 .It Va channels No (list) 163 .It Va channels No (list)
158 list of channels to auto join (Optional, default: empty). 164 List of channels to auto join (Optional, default: empty).
159 .Pp 165 .Pp
160 Note: if a channel requires a password, add it after a colon 166 Note: if a channel requires a password, add it after a colon (e.g.
161 (e.g. #channel:password). 167 .Dq #channel:password ) .
162 .It Va command-char No (string) 168 .It Va command-char No (string)
163 the prefix for invoking special commands (Optional, default: !). 169 The prefix for invoking special commands (Optional, default: !).
164 .It Va ssl No (bool) 170 .It Va ssl No (bool)
165 enable or disable SSL (Optional, default: false). 171 Enable or disable SSL (Optional, default: false).
166 .It Va auto-reconnect No (bool) 172 .It Va auto-reconnect No (bool)
167 enable reconnection after failure (Optional, default: true). 173 Enable reconnection after failure (Optional, default: true).
168 .It Va auto-reconnect-delay No (int) 174 .It Va auto-reconnect-delay No (int)
169 number of seconds to wait before retrying (Optional, default: 30). 175 Number of seconds to wait before retrying (Optional, default: 30).
170 .It Va ping-timeout No (int) 176 .It Va ping-timeout No (int)
171 number of seconds before ping timeout (Optional, default: 300). 177 Number of seconds before ping timeout (Optional, default: 300).
172 .It Va nickname No (string) 178 .It Va nickname No (string)
173 the nickname (Optional, default: irccd). 179 The nickname (Optional, default: irccd).
174 .It Va realname No (string) 180 .It Va realname No (string)
175 the realname (Optional, default: IRC Client Daemon). 181 The realname (Optional, default: IRC Client Daemon).
176 .It Va username No (string) 182 .It Va username No (string)
177 the username name (Optional, default: irccd). 183 The username name (Optional, default: irccd).
178 .It Va ctcp-version No (string) 184 .It Va ctcp-version No (string)
179 what version to respond to CTCP VERSION (Optional, default: IRC Client Daemon). 185 What version to respond to CTCP VERSION (Optional, default: IRC Client Daemon).
180 .El 186 .El
181 .\" [paths] 187 .\" [paths]
182 .Ss paths 188 .Ss paths
183 The paths section defines common paths used as defaults for all plugins. 189 The paths section defines common paths used as defaults for all plugins.
184 .Pp 190 .Pp
185 Any option in this section can be defined altough the following are used as 191 Any option in this section can be defined altough the following are used as
186 common convention used in all plugins: 192 common convention used in all plugins:
187 .Pp 193 .Pp
188 Available options: 194 Available options:
189 .Bl -tag -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx 195 .Bl -tag -width 16n
190 .It Va cache No (string) 196 .It Va cache No (string)
191 path for data files written by the plugin. 197 Path for data files written by the plugin.
192 .It Va data No (string) 198 .It Va data No (string)
193 path for data files provided by the user. 199 Path for data files provided by the user.
194 .It Va config No (string) 200 .It Va config No (string)
195 path for additional configuration from the user. 201 Path for additional configuration from the user.
196 .El 202 .El
197 .Pp 203 .Pp
198 For each of these paths, plugin/name is appended with the appropriate plugin 204 For each of these paths,
199 name when used. 205 .Dq plugin/name
206 is appended with the appropriate plugin name when used.
200 .Pp 207 .Pp
201 The section is redefinable per plugin basis using the 208 The section is redefinable per plugin basis using the
202 .Va [paths.<plugin>] 209 .Va [paths.<plugin>]
203 syntax. 210 syntax.
204 .Ss plugins 211 .Ss plugins
212 .\" [transport] 219 .\" [transport]
213 .Ss transport 220 .Ss transport
214 This section defines transports that are used to communicate through clients 221 This section defines transports that are used to communicate through clients
215 connected to irccd and to perform requests to irccd. 222 connected to irccd and to perform requests to irccd.
216 .Pp 223 .Pp
217 With transports, you can may ask irccd to send a message, a notice or even 224 With transports, you may ask irccd to send a message, a notice or even to kick
218 kicking someone from a channel. Irccd will also notify all clients connected to 225 someone from a channel. Irccd will also notify all clients connected to this
219 this transport on IRC events. 226 transport on IRC events.
220 .Pp 227 .Pp
221 There are two type of listeners availables: 228 There are two types of transport availables:
222 .Bl -bullet 229 .Bl -bullet
223 .It 230 .It
224 Internet sockets, IPv4 and IPv6, 231 Internet sockets, IPv4 and IPv6,
225 .It 232 .It
226 Unix sockets, based on files (not available on Windows). 233 Unix sockets, based on files (not available on Windows).
228 .Pp 235 .Pp
229 If SSL support was built in, both internet and unix sockets can be set to use 236 If SSL support was built in, both internet and unix sockets can be set to use
230 encrypted connections. 237 encrypted connections.
231 .Pp 238 .Pp
232 Available options: 239 Available options:
233 .Bl -tag -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx 240 .Bl -tag -width 18n
234 .It Va type No (string) 241 .It Va type No (string)
235 type of listener "ip" or "unix". 242 Type of transport
243 .Dq ip
244 or
245 .Dq unix .
236 .It Va password No (string) 246 .It Va password No (string)
237 an authentication password (Optional, default: none). 247 An authentication password (Optional, default: none).
238 .It Va ssl No (bool) 248 .It Va ssl No (bool)
239 enable SSL (Optional, default: false), 249 Enable SSL (Optional, default: false),
240 .It Va key No (string) 250 .It Va key No (string)
241 path to private key file (Required if ssl is true) 251 Path to private key file (Required if ssl is true)
242 .It Va certificate No (string) 252 .It Va certificate No (string)
243 path to certificate (Required if ssl is true) 253 Path to certificate (Required if ssl is true)
244 .Pp 254 .El
245 The additional options for ip type: 255 .Pp
246 .Bl -tag -width indent-xxxxxxxxx 256 The following options are available for the
257 .Ar ip
258 type:
259 .Bl -tag -width 18n
247 .It Va port No (int) 260 .It Va port No (int)
248 port number. 261 Port number.
249 .It Va address No (string) 262 .It Va address No (string)
250 address to bind or * for any (Optional, default: *). 263 Address to bind or
264 .Dq *
265 for any (Optional, default:
266 .Dq * ) .
251 .It Va ipv4 No (bool) 267 .It Va ipv4 No (bool)
252 bind on IPv4 (Optional, default true). 268 Bind on IPv4 (Optional, default true).
253 .It Va ipv6 No (bool) 269 .It Va ipv6 No (bool)
254 bind on IPv6 (Optional, default true). 270 Bind on IPv6 (Optional, default true).
255 .El 271 .El
256 .Pp 272 .Pp
257 The additional options for unix type: 273 The following options are available for the
258 .Bl -tag -width indent-xxxxxxxxx 274 .Ar unix
275 type:
276 .Bl -tag -width 18n
259 .It Va path No (string) 277 .It Va path No (string)
260 the file path to the socket. 278 The file path to the socket.
261 .El 279 .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] 280 .\" [rule]
269 .Ss rule 281 .Ss rule
270 The rule section is one of the most powerful within irccd configuration. It let 282 The rule section is one of the most powerful within irccd configuration. It lets
271 you enable or disable plugins and IRC events for specific criterias. For 283 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 284 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, 285 specific server. And because rules are evaluated in the order they are defined,
274 you can override rules. 286 you can override rules.
275 .Pp 287 .Pp
276 Available options: 288 Available options:
277 .Bl -tag -offset Ds -width indent-xxxxxxxxxxxxxxxxxxx 289 .Bl -tag -width 15n
278 .It Va servers No (list) 290 .It Va servers No (list)
279 a list of servers that will match the rule (Optional, default: empty). 291 A list of servers that will match the rule (Optional, default: empty).
280 .It Va channels No (list) 292 .It Va channels No (list)
281 a list of channel (Optional, default: empty). 293 A list of channel (Optional, default: empty).
282 .It Va origins No (list) 294 .It Va origins No (list)
283 a list of nicknames to check (Optional, default: empty). 295 A list of nicknames to check (Optional, default: empty).
284 .It Va plugins No (list) 296 .It Va plugins No (list)
285 which plugins (Optional, default: empty), 297 Which plugins (Optional, default: empty),
286 .It Va events No (list) 298 .It Va events No (list)
287 which events like onCommand, onMessage (Optional, default: empty). 299 Which events like onCommand, onMessage (Optional, default: empty).
288 .It Va action No (string) 300 .It Va action No (string)
289 set to accept or drop. 301 Set to
302 .Dq accept
303 or
304 .Dq drop .
290 .El 305 .El
291 .Pp 306 .Pp
292 Warning: don't make sensitive rules on origins option, irccd does not have any 307 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 308 kind of nickname authentication. Thus, it may be very easy for someone
294 to use a temporary nickname. 309 to use a temporary nickname.
295 .Sh EXAMPLE 310 .\" EXAMPLES
311 .Sh EXAMPLES
296 Full example of configuration file 312 Full example of configuration file
297 .Bd -literal 313 .Bd -literal
298 # Add a transport that bind only to IPv6. 314 # Add a transport that bind only to IPv6.
299 [transport] 315 [transport]
300 type = ip 316 type = ip
339 servers = "localhost" 355 servers = "localhost"
340 channels = "#staff" 356 channels = "#staff"
341 plugins = "reboot" 357 plugins = "reboot"
342 action = accept 358 action = accept
343 .Ed 359 .Ed
360 .\" SEE ALSO
344 .Sh SEE ALSO 361 .Sh SEE ALSO
345 .Xr irccd 1 362 .Xr irccd 1
363 .\" AUTHORS
364 .Sh AUTHORS
365 .Nm
366 was written by David Demelier <markand@malikania.fr>