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 (<127 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 MaxPenaltyTime (number)
199 Maximum penalty time increase in seconds, per penalty event. Set
200 to -1 for no limit (the default), 0 to disable penalties alto‐
201 gether. ngIRCd doesn't use penalty increases higher than 2 sec‐
202 onds during normal operation, so values greater than 1 rarely
203 make sense.
204 MaxListSize (number)
206 Maximum number of channels returned in response to a LIST com‐
207 mand. Default: 100.
208 PingTimeout (number)
210 After <PingTimeout> seconds of inactivity the server will send a
211 PING to the peer to test whether it is alive or not. Default:
212 120.
213 PongTimeout (number)
215 If a client fails to answer a PING with a PONG within <PongTime‐
216 out> seconds, it will be disconnected by the server. Default:
217 20.
218
220 Optional features and configuration options to further tweak the behav‐
221 ior of ngIRCd are configured in this section. If you want to get
222 started quickly, you most probably don't have to make changes here --
223 they are all optional.
224 AllowedChannelTypes (string)
226 List of allowed channel types (channel prefixes) for newly cre‐
227 ated channels on the local server. By default, all supported
228 channel types are allowed. Set this variable to the empty
229 string to disallow creation of new channels by local clients at
230 all. Default: #&+
231 AllowRemoteOper (boolean)
233 If this option is active, IRC operators connected to remote
234 servers are allowed to control this local server using adminis‐
235 trative commands, for example like CONNECT, DIE, SQUIT etc.
236 Default: no.
237 ChrootDir (string)
239 A directory to chroot in when everything is initialized. It
240 doesn't need to be populated if ngIRCd is compiled as a static
241 binary. By default ngIRCd won't use the chroot() feature.
242 Attention:
244 For this to work the server must have been started with root
245 privileges!
246 CloakHost (string)
248 Set this hostname for every client instead of the real one.
249 Default: empty, don't change. Use %x to add the hashed value of
250 the original hostname.
251 CloakHostModeX (string)
253 Use this hostname for hostname cloaking on clients that have the
254 user mode "+x" set, instead of the name of the server. Default:
255 empty, use the name of the server. Use %x to add the hashed
256 value of the original hostname
257 CloakHostSalt (string)
259 The Salt for cloaked hostname hashing. When undefined a random
260 hash is generated after each server start.
261 CloakUserToNick (boolean)
263 Set every clients' user name and real name to their nickname and
264 hide the one supplied by the IRC client. Default: no.
265 ConnectIPv4 (boolean)
267 Set this to no if you do not want ngIRCd to connect to other IRC
268 servers using the IPv4 protocol. This allows the usage of ngIRCd
269 in IPv6-only setups. Default: yes.
270 ConnectIPv6 (boolean)
272 Set this to no if you do not want ngIRCd to connect to other IRC
273 servers using the IPv6 protocol. Default: yes.
274 DefaultUserModes (string)
276 Default user mode(s) to set on new local clients. Please note
277 that only modes can be set that the client could set using regu‐
278 lar MODE commands, you can't set "a" (away) for example!
279 Default: none.
280 DNS (boolean)
282 If set to false, ngIRCd will not make any DNS lookups when
283 clients connect. If you configure the daemon to connect to
284 other servers, ngIRCd may still perform a DNS lookup if
285 required. Default: yes.
286 Ident (boolean)
288 If ngIRCd is compiled with IDENT support this can be used to
289 disable IDENT lookups at run time. Users identified using IDENT
290 are registered without the "~" character prepended to their user
291 name. Default: yes.
292 IncludeDir (string)
294 Directory containing configuration snippets (*.conf), that
295 should be read in after parsing the current configuration file.
296 Default: none.
297 MorePrivacy (boolean)
299 This will cause ngIRCd to censor user idle time, logon time as
300 well as the PART/QUIT messages (that are sometimes used to
301 inform everyone about which client software is being used).
302 WHOWAS requests are also silently ignored, and NAMES output
303 doesn't list any clients for non-members. This option is most
304 useful when ngIRCd is being used together with anonymizing soft‐
305 ware such as TOR or I2P and one does not wish to make it too
306 easy to collect statistics on the users. Default: no.
307 NoticeBeforeRegistration (boolean)
309 Normally ngIRCd doesn't send any messages to a client until it
310 is registered. Enable this option to let the daemon send
311 "NOTICE *" messages to clients while connecting. Default: no.
312 OperCanUseMode (boolean)
314 Should IRC Operators be allowed to use the MODE command even if
315 they are not(!) channel-operators? Default: no.
316 OperChanPAutoOp (boolean)
318 Should IRC Operators get AutoOp (+o) in persistent (+P) chan‐
319 nels? Default: yes.
320 OperServerMode (boolean)
322 If OperCanUseMode is enabled, this may lead the compatibility
323 problems with Servers that run the ircd-irc2 Software. This
324 Option "masks" mode requests by non-chanops as if they were com‐
325 ing from the server. Default: no; only enable it if you have
326 ircd-irc2 servers in your IRC network.
327 PAM (boolean)
329 If ngIRCd is compiled with PAM support this can be used to dis‐
330 able all calls to the PAM library at runtime; all users connect‐
331 ing without password are allowed to connect, all passwords given
332 will fail. Users identified using PAM are registered without
333 the "~" character prepended to their user name. Default: yes.
334 PAMIsOptional (boolean)
336 When PAM is enabled, all clients are required to be authenti‐
337 cated using PAM; connecting to the server without successful PAM
338 authentication isn't possible. If this option is set, clients
339 not sending a password are still allowed to connect: they won't
340 become "identified" and keep the "~" character prepended to
341 their supplied user name. Please note: To make some use of this
342 behavior, it most probably isn't useful to enable "Ident", "PAM"
343 and "PAMIsOptional" at the same time, because you wouldn't be
344 able to distinguish between Ident'ified and PAM-authenticated
345 users: both don't have a "~" character prepended to their
346 respective user names! Default: no.
347 PAMServiceName (string)
349 When PAM is enabled, this value determines the used PAM configu‐
350 ration. This setting allows running multiple ngIRCd instances
351 with different PAM configurations on each instance. If you set
352 it to "ngircd-foo", PAM will use /etc/pam.d/ngircd-foo instead
353 of the default /etc/pam.d/ngircd. Default: ngircd.
354 RequireAuthPing (boolean)
356 Let ngIRCd send an "authentication PING" when a new client con‐
357 nects, and register this client only after receiving the corre‐
358 sponding "PONG" reply. Default: no.
359 ScrubCTCP (boolean)
361 If set to true, ngIRCd will silently drop all CTCP requests sent
362 to it from both clients and servers. It will also not forward
363 CTCP requests to any other servers. CTCP requests can be used to
364 query user clients about which software they are using and which
365 versions said software is. CTCP can also be used to reveal
366 clients IP numbers. ACTION CTCP requests are not blocked, this
367 means that /me commands will not be dropped, but please note
368 that blocking CTCP will disable file sharing between users!
369 Default: no.
370 SyslogFacility (string)
372 Syslog "facility" to which ngIRCd should send log messages. Pos‐
373 sible values are system dependent, but most probably "auth",
374 "daemon", "user" and "local1" through "local7" are possible val‐
375 ues; see syslog(3). Default is "local5" for historical reasons,
376 you probably want to change this to "daemon", for example.
377 WebircPassword (string)
379 Password required for using the WEBIRC command used by some Web-
380 to-IRC gateways. If not set or empty, the WEBIRC command can't
381 be used. Default: not set.
382
384 All SSL-related configuration variables are located in the [SSL] sec‐
385 tion. Please note that this whole section is only recognized by ngIRCd
386 when it is compiled with support for SSL using OpenSSL or GnuTLS!
387 CertFile (string)
389 SSL Certificate file of the private server key.
390 CipherList (string)
392 Select cipher suites allowed for SSL/TLS connections. This
393 defaults to "HIGH:!aNULL:@STRENGTH:!SSLv3" (OpenSSL) or
394 "SECURE128:-VERS-SSL3.0" (GnuTLS). Please see 'man 1ssl
395 ciphers' (OpenSSL) and 'man 3 gnutls_priority_init' (GnuTLS) for
396 details.
397 DHFile (string)
399 Name of the Diffie-Hellman Parameter file. Can be created with
400 GnuTLS "certtool --generate-dh-params" or "openssl dhparam". If
401 this file is not present, it will be generated on startup when
402 ngIRCd was compiled with GnuTLS support (this may take some
403 time). If ngIRCd was compiled with OpenSSL, then
404 (Ephemeral)-Diffie-Hellman Key Exchanges and several Cipher
405 Suites will not be available.
406 KeyFile (string)
408 Filename of SSL Server Key to be used for SSL connections. This
409 is required for SSL/TLS support.
410 KeyFilePassword (string)
412 OpenSSL only: Password to decrypt the private key file.
413 Ports (list of numbers)
415 Same as Ports , except that ngIRCd will expect incoming connec‐
416 tions to be SSL/TLS encrypted. Common port numbers for SSL-
417 encrypted IRC are 6669 and 6697. Default: none.
418
420 [Operator] sections are used to define IRC Operators. There may be more
421 than one [Operator] block, one for each local operator.
422 Name (string)
424 ID of the operator (may be different of the nickname).
425 Password (string)
427 Password of the IRC operator.
428 Mask (string)
430 Mask that is to be checked before an /OPER for this account is
431 accepted. Example: nick!ident@*.example.com
432
434 Other servers are configured in [Server] sections. If you configure a
435 port for the connection, then this ngIRCd tries to connect to the other
436 server on the given port (active); if not, it waits for the other
437 server to connect (passive).
438 ngIRCd supports "server groups": You can assign an "ID" to every server
440 with which you want this ngIRCd to link, and the daemon ensures that at
441 any given time only one direct link exists to servers with the same ID.
442 So if a server of a group won't answer, ngIRCd tries to connect to the
443 next server in the given group (="with the same ID"), but never tries
444 to connect to more than one server of this group simultaneously.
445 There may be more than one [Server] block.
447 Name (string)
449 IRC name of the remote server.
450 Host (string)
452 Internet host name (or IP address) of the peer.
453 Bind (string)
455 IP address to use as source IP for the outgoing connection.
456 Default is to let the operating system decide.
457 Port (number)
459 Port of the remote server to which ngIRCd should connect
460 (active). If no port is assigned to a configured server, the
461 daemon only waits for incoming connections (passive, default).
462 MyPassword (string)
464 Own password for this connection. This password has to be con‐
465 figured as PeerPassword on the other server. Must not have ':'
466 as first character.
467 PeerPassword (string)
469 Foreign password for this connection. This password has to be
470 configured as MyPassword on the other server.
471 Group (number)
473 Group of this server (optional).
474 Passive (boolean)
476 Disable automatic connection even if port value is specified.
477 Default: false. You can use the IRC Operator command CONNECT
478 later on to create the link.
479 SSLConnect (boolean)
481 Connect to the remote server using TLS/SSL. Default: false.
482 ServiceMask (string)
484 Define a (case insensitive) list of masks matching nicknames
485 that should be treated as IRC services when introduced via this
486 remote server, separated by commas (","). REGULAR SERVERS DON'T
487 NEED this parameter, so leave it empty (which is the default).
488 When you are connecting IRC services which mask as a IRC server
490 and which use "virtual users" to communicate with, for example
491 "NickServ" and "ChanServ", you should set this parameter to
492 something like "*Serv", "*Serv,OtherNick", or "Nick‐
493 Serv,ChanServ,XyzServ".
494
496 Pre-defined channels can be configured in [Channel] sections. Such
497 channels are created by the server when starting up and even persist
498 when there are no more members left.
499 Persistent channels are marked with the mode 'P', which can be set and
501 unset by IRC operators like other modes on the fly.
502 There may be more than one [Channel] block.
504 Name (string)
506 Name of the channel, including channel prefix ("#" or "&").
507 Topic (string)
509 Topic for this channel.
510 Modes (string)
512 Initial channel modes, as used in "MODE" commands. Modifying
513 lists (ban list, invite list, exception list) is supported.
514 This option can be specified multiple times, evaluated top to
516 bottom.
517 KeyFile (string)
519 Path and file name of a "key file" containing individual channel
520 keys for different users. The file consists of plain text lines
521 with the following syntax (without spaces!):
522 user : nick : key
524 user and nick can contain the wildcard character "*".
526 key is an arbitrary password.
527 Valid examples are:
529 *:*:KeY
531 *:nick:123
532 ~user:*:xyz
533 The key file is read on each JOIN command when this channel has
535 a key (channel mode +k). Access is granted, if a) the channel
536 key set using the MODE +k command or b) one of the lines in the
537 key file match.
538 Please note:
540 The file is not reopened on each access, so you can modify and
541 overwrite it without problems, but moving or deleting the file
542 will have not effect until the daemon re-reads its configura‐
543 tion!
544
546 It's wise to use "ngircd --configtest" to validate the configuration
547 file after changing it. See ngircd(8) for details.
548
550 Alexander Barton, <alex@barton.de>
551 Florian Westphal, <fw@strlen.de>
552 Homepage: http://ngircd.barton.de/
554
556 ngircd(8)
557ngIRCd May 2020 ngircd.conf(5)