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], [Op‐
50 tions], [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 of‐
57 ten.
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
82 setup!
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 re‐
97 quired 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 ad‐
185 dress that the server will accept (0: unlimited). This configu‐
186 ration 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. De‐
236 fault: 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. De‐
249 fault: 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! De‐
279 fault: 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 re‐
285 quired. 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 in‐
301 form everyone about which client software is being used). WHOWAS
302 requests are also silently ignored, and NAMES output doesn't
303 list any clients for non-members. This option is most useful
304 when ngIRCd is being used together with anonymizing software
305 such as TOR or I2P and one does not wish to make it too easy to
306 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 "NO‐
311 TICE *" 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 Op‐
324 tion "masks" mode requests by non-chanops as if they were coming
325 from the server. Default: no; only enable it if you have ircd-
326 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 re‐
346 spective 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! De‐
369 fault: 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 de‐
393 faults to "HIGH:!aNULL:@STRENGTH:!SSLv3" (OpenSSL) or "SE‐
394 CURE128:-VERS-SSL3.0" (GnuTLS). Please see 'man 1ssl ciphers'
395 (OpenSSL) and 'man 3 gnutls_priority_init' (GnuTLS) for details.
396 DHFile (string)
398 Name of the Diffie-Hellman Parameter file. Can be created with
399 GnuTLS "certtool --generate-dh-params" or "openssl dhparam". If
400 this file is not present, it will be generated on startup when
401 ngIRCd was compiled with GnuTLS support (this may take some
402 time). If ngIRCd was compiled with OpenSSL, then
403 (Ephemeral)-Diffie-Hellman Key Exchanges and several Cipher
404 Suites will not be available.
405 KeyFile (string)
407 Filename of SSL Server Key to be used for SSL connections. This
408 is required for SSL/TLS support.
409 KeyFilePassword (string)
411 OpenSSL only: Password to decrypt the private key file.
412 Ports (list of numbers)
414 Same as Ports , except that ngIRCd will expect incoming connec‐
415 tions to be SSL/TLS encrypted. Common port numbers for SSL-en‐
416 crypted IRC are 6669 and 6697. Default: none.
417
419 [Operator] sections are used to define IRC Operators. There may be more
420 than one [Operator] block, one for each local operator.
421 Name (string)
423 ID of the operator (may be different of the nickname).
424 Password (string)
426 Password of the IRC operator.
427 Mask (string)
429 Mask that is to be checked before an /OPER for this account is
430 accepted. Example: nick!ident@*.example.com
431
433 Other servers are configured in [Server] sections. If you configure a
434 port for the connection, then this ngIRCd tries to connect to the other
435 server on the given port (active); if not, it waits for the other
436 server to connect (passive).
437 ngIRCd supports "server groups": You can assign an "ID" to every server
439 with which you want this ngIRCd to link, and the daemon ensures that at
440 any given time only one direct link exists to servers with the same ID.
441 So if a server of a group won't answer, ngIRCd tries to connect to the
442 next server in the given group (="with the same ID"), but never tries
443 to connect to more than one server of this group simultaneously.
444 There may be more than one [Server] block.
446 Name (string)
448 IRC name of the remote server.
449 Host (string)
451 Internet host name (or IP address) of the peer.
452 Bind (string)
454 IP address to use as source IP for the outgoing connection. De‐
455 fault is to let the operating system decide.
456 Port (number)
458 Port of the remote server to which ngIRCd should connect (ac‐
459 tive). If no port is assigned to a configured server, the dae‐
460 mon only waits for incoming connections (passive, default).
461 MyPassword (string)
463 Own password for this connection. This password has to be con‐
464 figured as PeerPassword on the other server. Must not have ':'
465 as first character.
466 PeerPassword (string)
468 Foreign password for this connection. This password has to be
469 configured as MyPassword on the other server.
470 Group (number)
472 Group of this server (optional).
473 Passive (boolean)
475 Disable automatic connection even if port value is specified.
476 Default: false. You can use the IRC Operator command CONNECT
477 later on to create the link.
478 SSLConnect (boolean)
480 Connect to the remote server using TLS/SSL. Default: false.
481 ServiceMask (string)
483 Define a (case insensitive) list of masks matching nicknames
484 that should be treated as IRC services when introduced via this
485 remote server, separated by commas (","). REGULAR SERVERS DON'T
486 NEED this parameter, so leave it empty (which is the default).
487 When you are connecting IRC services which mask as a IRC server
489 and which use "virtual users" to communicate with, for example
490 "NickServ" and "ChanServ", you should set this parameter to
491 something like "*Serv", "*Serv,OtherNick", or "Nick‐
492 Serv,ChanServ,XyzServ".
493
495 Pre-defined channels can be configured in [Channel] sections. Such
496 channels are created by the server when starting up and even persist
497 when there are no more members left.
498 Persistent channels are marked with the mode 'P', which can be set and
500 unset by IRC operators like other modes on the fly.
501 There may be more than one [Channel] block.
503 Name (string)
505 Name of the channel, including channel prefix ("#" or "&").
506 Topic (string)
508 Topic for this channel.
509 Modes (string)
511 Initial channel modes, as used in "MODE" commands. Modifying
512 lists (ban list, invite list, exception list) is supported.
513 This option can be specified multiple times, evaluated top to
515 bottom.
516 KeyFile (string)
518 Path and file name of a "key file" containing individual channel
519 keys for different users. The file consists of plain text lines
520 with the following syntax (without spaces!):
521 user : nick : key
523 user and nick can contain the wildcard character "*".
525 key is an arbitrary password.
526 Valid examples are:
528 *:*:KeY
530 *:nick:123
531 ~user:*:xyz
532 The key file is read on each JOIN command when this channel has
534 a key (channel mode +k). Access is granted, if a) the channel
535 key set using the MODE +k command or b) one of the lines in the
536 key file match.
537 Please note:
539 The file is not reopened on each access, so you can modify and
540 overwrite it without problems, but moving or deleting the file
541 will have not effect until the daemon re-reads its configura‐
542 tion!
543
545 It's wise to use "ngircd --configtest" to validate the configuration
546 file after changing it. See ngircd(8) for details.
547
549 Alexander Barton, <alex@barton.de>
550 Florian Westphal, <fw@strlen.de>
551 Homepage: http://ngircd.barton.de/
553
555 ngircd(8)
556ngIRCd Jan 2021 ngircd.conf(5)