1ngircd.conf(5) ngIRCd Manual ngircd.conf(5)
2
6 ngircd.conf - configuration file of ngIRCd
7
9 /etc/ngircd.conf
10
12 ngircd.conf is the configuration file of the ngircd(8) Internet Relay
13 Chat (IRC) daemon, which must be customized to the local preferences
14 and needs.
15 Most variables can be modified while the ngIRCd daemon is already run‐
17 ning: It will reload its configuration file when a HUP signal or REHASH
18 command is received.
19
21 The file consists of sections and parameters. A section begins with the
22 name of the section in square brackets and continues until the next
23 section begins.
24 Sections contain parameters of the form
26 name = value
28 Empty lines and any line beginning with a semicolon (';') or a hash
30 ('#') character are treated as a comment and will be ignored. Leading
31 and trailing whitespaces are trimmed before any processing takes place.
32 The file format is line-based - that means, each non-empty newline-ter‐
34 minated line represents either a comment, a section name, or a parame‐
35 ter.
36 Section and parameter names are not case sensitive.
38 There are three types of variables: booleans, text strings, and num‐
40 bers. Boolean values are true if they are "yes", "true", or any non-
41 null integer. Text strings are used 1:1 without leading and following
42 spaces; there is no way to quote strings. And for numbers all decimal
43 integer values are valid.
44 In addition, some string or numerical variables accept lists of values,
46 separated by commas (",").
47
49 The file can contain blocks of seven types: [Global], [Limits],
50 [Options], [SSL], [Operator], [Server], and [Channel].
51 The main configuration of the server is stored in the [Global] section,
53 like the server name, administrative information and the ports on which
54 the server should be listening. The variables in this section have to
55 be adjusted to the local requirements most of the time, whereas all the
56 variables in the other sections can be left on their defaults very
57 often.
58 Options in the [Limits] block are used to tweak different limits and
60 timeouts of the daemon, like the maximum number of clients allowed to
61 connect to this server. Variables in the [Options] section can be used
62 to enable or disable specific features of ngIRCd, like support for
63 IDENT, PAM, IPv6, and protocol and cloaking features. The [SSL] block
64 contains all SSL-related configuration variables. These three sections
65 are all optional.
66 IRC operators of this server are defined in [Operator] blocks. Links to
68 remote servers are configured in [Server] sections. And [Channel]
69 blocks are used to configure pre-defined ("persistent") IRC channels.
70 There can be more than one [Operator], [Server] and [Channel] section
72 per configuration file, one for each operator, server, and channel.
73 [Global], [Limits], [Options], and [SSL] sections can occur multiple
74 times, too, but each variable overwrites itself, only the last assign‐
75 ment is relevant.
76
78 The [Global] section is used to define the main configuration of the
79 server, like the server name and the ports on which the server should
80 be listening. These settings depend on your personal preferences, so
81 you should make sure that they correspond to your installation and set‐
82 up!
83 Name (string; required)
85 Server name in the IRC network. This is an individual name of
86 the IRC server, it is not related to the DNS host name. It must
87 be unique in the IRC network and must contain at least one dot
88 (".") character.
89 AdminInfo1, AdminInfo2, AdminEMail (string)
91 Information about the server and the administrator, used by the
92 ADMIN command. This information is not required by the server
93 but by RFC!
94 HelpFile (string)
96 Text file which contains the ngIRCd help text. This file is
97 required to display help texts when using the "HELP <cmd>" com‐
98 mand. Please note: Changes made to this file take effect when
99 ngircd starts up or is instructed to re-read its configuration
100 file.
101 Info (string)
103 Info text of the server. This will be shown by WHOIS and LINKS
104 requests for example.
105 Listen (list of strings)
107 A comma separated list of IP address on which the server should
108 listen. If unset, the defaults value is "0.0.0.0" or, if ngIRCd
109 was compiled with IPv6 support, "::,0.0.0.0". So the server lis‐
110 tens on all configured IP addresses and interfaces by default.
111 MotdFile (string)
113 Text file with the "message of the day" (MOTD). This message
114 will be shown to all users connecting to the server. Please
115 note: Changes made to this file take effect when ngircd starts
116 up or is instructed to re-read its configuration file.
117 MotdPhrase (string)
119 A simple Phrase (<256 chars) if you don't want to use a MOTD
120 file.
121 Network (string)
123 The name of the IRC network to which this server belongs. This
124 name is optional, should only contain ASCII characters, and
125 can't contain spaces. It is only used to inform clients. The
126 default is empty, so no network name is announced to clients.
127 Password (string)
129 Global password for all users needed to connect to the server.
130 The default is empty, so no password is required. Please note:
131 This feature is not available if ngIRCd is using PAM!
132 PidFile (string)
134 This tells ngIRCd to write its current process ID to a file.
135 Note that the "PID file" is written AFTER chroot and switching
136 the user ID, therefore the directory the file resides in must be
137 writable by the ngIRCd user and exist in the chroot directory
138 (if configured, see above).
139 Ports (list of numbers)
141 Port number(s) on which the server should listen for unencrypted
142 connections. There may be more than one port, separated with
143 commas (","). Default: 6667.
144 ServerGID (string or number)
146 Group ID under which the ngIRCd daemon should run; you can use
147 the name of the group or the numerical ID.
148 Attention:
150 For this to work the server must have been started with root
151 privileges!
152 ServerUID (string or number)
154 User ID under which the ngIRCd daemon should run; you can use
155 the name of the user or the numerical ID.
156 Attention:
158 For this to work the server must have been started with root
159 privileges! In addition, the configuration and MOTD files must
160 be readable by this user, otherwise RESTART and REHASH won't
161 work!
162
164 This section is used to define some limits and timeouts for this ngIRCd
165 instance. Default values should be safe, but it is wise to double-check
166 :-)
167 ConnectRetry (number)
169 The server tries every <ConnectRetry> seconds to establish a
170 link to not yet (or no longer) connected servers. Default: 60.
171 IdleTimeout (number)
173 Number of seconds after which the whole daemon should shutdown
174 when no connections are left active after handling at least one
175 client (0: never). This can be useful for testing or when ngIRCd
176 is started using "socket activation" with systemd(8), for exam‐
177 ple. Default: 0.
178 MaxConnections (number)
180 Maximum number of simultaneous in- and outbound connections the
181 server is allowed to accept (0: unlimited). Default: 0.
182 MaxConnectionsIP (number)
184 Maximum number of simultaneous connections from a single IP
185 address that the server will accept (0: unlimited). This config‐
186 uration options lowers the risk of denial of service attacks
187 (DoS). Default: 5.
188 MaxJoins (number)
190 Maximum number of channels a user can be member of (0: no
191 limit). Default: 10.
192 MaxNickLength (number)
194 Maximum length of an user nickname (Default: 9, as in RFC 2812).
195 Please note that all servers in an IRC network MUST use the same
196 maximum nickname length!
197 MaxListSize (number)
199 Maximum number of channels returned in response to a LIST com‐
200 mand. Default: 100.
201 PingTimeout (number)
203 After <PingTimeout> seconds of inactivity the server will send a
204 PING to the peer to test whether it is alive or not. Default:
205 120.
206 PongTimeout (number)
208 If a client fails to answer a PING with a PONG within <PongTime‐
209 out> seconds, it will be disconnected by the server. Default:
210 20.
211
213 Optional features and configuration options to further tweak the behav‐
214 ior of ngIRCd are configured in this section. If you want to get
215 started quickly, you most probably don't have to make changes here --
216 they are all optional.
217 AllowedChannelTypes (string)
219 List of allowed channel types (channel prefixes) for newly cre‐
220 ated channels on the local server. By default, all supported
221 channel types are allowed. Set this variable to the empty
222 string to disallow creation of new channels by local clients at
223 all. Default: #&+
224 AllowRemoteOper (boolean)
226 If this option is active, IRC operators connected to remote
227 servers are allowed to control this local server using adminis‐
228 trative commands, for example like CONNECT, DIE, SQUIT etc.
229 Default: no.
230 ChrootDir (string)
232 A directory to chroot in when everything is initialized. It
233 doesn't need to be populated if ngIRCd is compiled as a static
234 binary. By default ngIRCd won't use the chroot() feature.
235 Attention:
237 For this to work the server must have been started with root
238 privileges!
239 CloakHost (string)
241 Set this hostname for every client instead of the real one.
242 Default: empty, don't change. Use %x to add the hashed value of
243 the original hostname.
244 CloakHostModeX (string)
246 Use this hostname for hostname cloaking on clients that have the
247 user mode "+x" set, instead of the name of the server. Default:
248 empty, use the name of the server. Use %x to add the hashed
249 value of the original hostname
250 CloakHostSalt (string)
252 The Salt for cloaked hostname hashing. When undefined a random
253 hash is generated after each server start.
254 CloakUserToNick (boolean)
256 Set every clients' user name and real name to their nickname and
257 hide the one supplied by the IRC client. Default: no.
258 ConnectIPv4 (boolean)
260 Set this to no if you do not want ngIRCd to connect to other IRC
261 servers using the IPv4 protocol. This allows the usage of ngIRCd
262 in IPv6-only setups. Default: yes.
263 ConnectIPv6 (boolean)
265 Set this to no if you do not want ngIRCd to connect to other IRC
266 servers using the IPv6 protocol. Default: yes.
267 DefaultUserModes (string)
269 Default user mode(s) to set on new local clients. Please note
270 that only modes can be set that the client could set using regu‐
271 lar MODE commands, you can't set "a" (away) for example!
272 Default: none.
273 DNS (boolean)
275 If set to false, ngIRCd will not make any DNS lookups when
276 clients connect. If you configure the daemon to connect to
277 other servers, ngIRCd may still perform a DNS lookup if
278 required. Default: yes.
279 Ident (boolean)
281 If ngIRCd is compiled with IDENT support this can be used to
282 disable IDENT lookups at run time. Users identified using IDENT
283 are registered without the "~" character prepended to their user
284 name. Default: yes.
285 IncludeDir (string)
287 Directory containing configuration snippets (*.conf), that
288 should be read in after parsing the current configuration file.
289 Default: none.
290 MorePrivacy (boolean)
292 This will cause ngIRCd to censor user idle time, logon time as
293 well as the PART/QUIT messages (that are sometimes used to
294 inform everyone about which client software is being used).
295 WHOWAS requests are also silently ignored, and NAMES output
296 doesn't list any clients for non-members. This option is most
297 useful when ngIRCd is being used together with anonymizing soft‐
298 ware such as TOR or I2P and one does not wish to make it too
299 easy to collect statistics on the users. Default: no.
300 NoticeBeforeRegistration (boolean)
302 Normally ngIRCd doesn't send any messages to a client until it
303 is registered. Enable this option to let the daemon send
304 "NOTICE *" messages to clients while connecting. Default: no.
305 OperCanUseMode (boolean)
307 Should IRC Operators be allowed to use the MODE command even if
308 they are not(!) channel-operators? Default: no.
309 OperChanPAutoOp (boolean)
311 Should IRC Operators get AutoOp (+o) in persistent (+P) chan‐
312 nels? Default: yes.
313 OperServerMode (boolean)
315 If OperCanUseMode is enabled, this may lead the compatibility
316 problems with Servers that run the ircd-irc2 Software. This
317 Option "masks" mode requests by non-chanops as if they were com‐
318 ing from the server. Default: no; only enable it if you have
319 ircd-irc2 servers in your IRC network.
320 PAM (boolean)
322 If ngIRCd is compiled with PAM support this can be used to dis‐
323 able all calls to the PAM library at runtime; all users connect‐
324 ing without password are allowed to connect, all passwords given
325 will fail. Users identified using PAM are registered without
326 the "~" character prepended to their user name. Default: yes.
327 PAMIsOptional (boolean)
329 When PAM is enabled, all clients are required to be authenti‐
330 cated using PAM; connecting to the server without successful PAM
331 authentication isn't possible. If this option is set, clients
332 not sending a password are still allowed to connect: they won't
333 become "identified" and keep the "~" character prepended to
334 their supplied user name. Please note: To make some use of this
335 behavior, it most probably isn't useful to enable "Ident", "PAM"
336 and "PAMIsOptional" at the same time, because you wouldn't be
337 able to distinguish between Ident'ified and PAM-authenticated
338 users: both don't have a "~" character prepended to their
339 respective user names! Default: no.
340 PAMServiceName (string)
342 When PAM is enabled, this value determines the used PAM configu‐
343 ration. This setting allows to run multiple ngIRCd instances
344 with different PAM configurations on each instance. If you set
345 it to "ngircd-foo", PAM will use /etc/pam.d/ngircd-foo instead
346 of the default /etc/pam.d/ngircd. Default: ngircd.
347 RequireAuthPing (boolean)
349 Let ngIRCd send an "authentication PING" when a new client con‐
350 nects, and register this client only after receiving the corre‐
351 sponding "PONG" reply. Default: no.
352 ScrubCTCP (boolean)
354 If set to true, ngIRCd will silently drop all CTCP requests sent
355 to it from both clients and servers. It will also not forward
356 CTCP requests to any other servers. CTCP requests can be used to
357 query user clients about which software they are using and which
358 versions said software is. CTCP can also be used to reveal
359 clients IP numbers. ACTION CTCP requests are not blocked, this
360 means that /me commands will not be dropped, but please note
361 that blocking CTCP will disable file sharing between users!
362 Default: no.
363 SyslogFacility (string)
365 Syslog "facility" to which ngIRCd should send log messages. Pos‐
366 sible values are system dependent, but most probably "auth",
367 "daemon", "user" and "local1" through "local7" are possible val‐
368 ues; see syslog(3). Default is "local5" for historical reasons,
369 you probably want to change this to "daemon", for example.
370 WebircPassword (string)
372 Password required for using the WEBIRC command used by some Web-
373 to-IRC gateways. If not set or empty, the WEBIRC command can't
374 be used. Default: not set.
375
377 All SSL-related configuration variables are located in the [SSL] sec‐
378 tion. Please note that this whole section is only recognized by ngIRCd
379 when it is compiled with support for SSL using OpenSSL or GnuTLS!
380 CertFile (string)
382 SSL Certificate file of the private server key.
383 CipherList (string)
385 Select cipher suites allowed for SSL/TLS connections. This
386 defaults to "HIGH:!aNULL:@STRENGTH:!SSLv3" (OpenSSL) or
387 "SECURE128:-VERS-SSL3.0" (GnuTLS). Please see 'man 1ssl
388 ciphers' (OpenSSL) and 'man 3 gnutls_priority_init' (GnuTLS) for
389 details.
390 DHFile (string)
392 Name of the Diffie-Hellman Parameter file. Can be created with
393 GnuTLS "certtool --generate-dh-params" or "openssl dhparam". If
394 this file is not present, it will be generated on startup when
395 ngIRCd was compiled with GnuTLS support (this may take some
396 time). If ngIRCd was compiled with OpenSSL, then
397 (Ephemeral)-Diffie-Hellman Key Exchanges and several Cipher
398 Suites will not be available.
399 KeyFile (string)
401 Filename of SSL Server Key to be used for SSL connections. This
402 is required for SSL/TLS support.
403 KeyFilePassword (string)
405 OpenSSL only: Password to decrypt the private key file.
406 Ports (list of numbers)
408 Same as Ports , except that ngIRCd will expect incoming connec‐
409 tions to be SSL/TLS encrypted. Common port numbers for SSL-
410 encrypted IRC are 6669 and 6697. Default: none.
411
413 [Operator] sections are used to define IRC Operators. There may be more
414 than one [Operator] block, one for each local operator.
415 Name (string)
417 ID of the operator (may be different of the nickname).
418 Password (string)
420 Password of the IRC operator.
421 Mask (string)
423 Mask that is to be checked before an /OPER for this account is
424 accepted. Example: nick!ident@*.example.com
425
427 Other servers are configured in [Server] sections. If you configure a
428 port for the connection, then this ngIRCd tries to connect to to the
429 other server on the given port (active); if not, it waits for the other
430 server to connect (passive).
431 ngIRCd supports "server groups": You can assign an "ID" to every server
433 with which you want this ngIRCd to link, and the daemon ensures that at
434 any given time only one direct link exists to servers with the same ID.
435 So if a server of a group won't answer, ngIRCd tries to connect to the
436 next server in the given group (="with the same ID"), but never tries
437 to connect to more than one server of this group simultaneously.
438 There may be more than one [Server] block.
440 Name (string)
442 IRC name of the remote server.
443 Host (string)
445 Internet host name (or IP address) of the peer.
446 Bind (string)
448 IP address to use as source IP for the outgoing connection.
449 Default is to let the operating system decide.
450 Port (number)
452 Port of the remote server to which ngIRCd should connect
453 (active). If no port is assigned to a configured server, the
454 daemon only waits for incoming connections (passive, default).
455 MyPassword (string)
457 Own password for this connection. This password has to be con‐
458 figured as PeerPassword on the other server. Must not have ':'
459 as first character.
460 PeerPassword (string)
462 Foreign password for this connection. This password has to be
463 configured as MyPassword on the other server.
464 Group (number)
466 Group of this server (optional).
467 Passive (boolean)
469 Disable automatic connection even if port value is specified.
470 Default: false. You can use the IRC Operator command CONNECT
471 later on to create the link.
472 SSLConnect (boolean)
474 Connect to the remote server using TLS/SSL. Default: false.
475 ServiceMask (string)
477 Define a (case insensitive) list of masks matching nicknames
478 that should be treated as IRC services when introduced via this
479 remote server, separated by commas (","). REGULAR SERVERS DON'T
480 NEED this parameter, so leave it empty (which is the default).
481 When you are connecting IRC services which mask as a IRC server
483 and which use "virtual users" to communicate with, for example
484 "NickServ" and "ChanServ", you should set this parameter to
485 something like "*Serv", "*Serv,OtherNick", or "Nick‐
486 Serv,ChanServ,XyzServ".
487
489 Pre-defined channels can be configured in [Channel] sections. Such
490 channels are created by the server when starting up and even persist
491 when there are no more members left.
492 Persistent channels are marked with the mode 'P', which can be set and
494 unset by IRC operators like other modes on the fly.
495 There may be more than one [Channel] block.
497 Name (string)
499 Name of the channel, including channel prefix ("#" or "&").
500 Topic (string)
502 Topic for this channel.
503 Modes (string)
505 Initial channel modes.
506 Key (string)
508 Sets initial channel key (only relevant if channel mode "k" is
509 set).
510 KeyFile (string)
512 Path and file name of a "key file" containing individual channel
513 keys for different users. The file consists of plain text lines
514 with the following syntax (without spaces!):
515 user : nick : key
517 user and nick can contain the wildcard character "*".
519 key is an arbitrary password.
520 Valid examples are:
522 *:*:KeY
524 *:nick:123
525 ~user:*:xyz
526 The key file is read on each JOIN command when this channel has
528 a key (channel mode +k). Access is granted, if a) the channel
529 key set using the MODE +k command or b) one of the lines in the
530 key file match.
531 Please note:
533 The file is not reopened on each access, so you can modify and
534 overwrite it without problems, but moving or deleting the file
535 will have not effect until the daemon re-reads its configura‐
536 tion!
537 MaxUsers (number)
539 Set maximum user limit for this channel (only relevant if chan‐
540 nel mode "l" is set).
541
543 It's wise to use "ngircd --configtest" to validate the configuration
544 file after changing it. See ngircd(8) for details.
545
547 Alexander Barton, <alex@barton.de>
548 Florian Westphal, <fw@strlen.de>
549 Homepage: http://ngircd.barton.de/
551
553 ngircd(8)
554ngIRCd Jan 2017 ngircd.conf(5)