1ngircd.conf(5)                   ngIRCd Manual                  ngircd.conf(5)
2
3
4

NAME

6       ngircd.conf - configuration file of ngIRCd
7

SYNOPSIS

9       /etc/ngircd.conf
10

DESCRIPTION

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
16       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

FILE FORMAT

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
25       Sections contain parameters of the form
26
27              name = value
28
29       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
33       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
37       Section and parameter names are not case sensitive.
38
39       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
45       In addition, some string or numerical variables accept lists of values,
46       separated by commas (",").
47

SECTION OVERVIEW

49       The file can contain blocks of seven types:  [Global],  [Limits],  [Op‐
50       tions], [SSL], [Operator], [Server], and [Channel].
51
52       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
59       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
67       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
71       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

[GLOBAL]

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
84       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
90       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
95       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
102       Info (string)
103              Info  text  of the server. This will be shown by WHOIS and LINKS
104              requests for example.
105
106       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
112       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
118       MotdPhrase (string)
119              A simple Phrase (<127 chars) if you don't want  to  use  a  MOTD
120              file.
121
122       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
128       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
133       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
140       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
145       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
149              Attention:
150              For  this  to  work  the server must have been started with root
151              privileges!
152
153       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
157              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

[LIMITS]

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
168       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
172       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
179       MaxConnections (number)
180              Maximum  number of simultaneous in- and outbound connections the
181              server is allowed to accept (0: unlimited). Default: 0.
182
183       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
189       MaxJoins (number)
190              Maximum  number  of  channels  a  user  can  be member of (0: no
191              limit).  Default: 10.
192
193       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
198       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
205       MaxListSize (number)
206              Maximum number of channels returned in response to a  LIST  com‐
207              mand. Default: 100.
208
209       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
214       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

[OPTIONS]

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
225       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
232       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
238       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
243              Attention:
244              For  this  to  work  the server must have been started with root
245              privileges!
246
247       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
252       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
258       CloakHostSalt (string)
259              The  Salt  for cloaked hostname hashing. When undefined a random
260              hash is generated after each server start.
261
262       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
266       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
271       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
275       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
281       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
287       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
293       IncludeDir (string)
294              Directory   containing  configuration  snippets  (*.conf),  that
295              should be read in after parsing the current configuration  file.
296              Default: none.
297
298       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
308       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
313       OperCanUseMode (boolean)
314              Should IRC Operators be allowed to use the MODE command even  if
315              they are not(!) channel-operators? Default: no.
316
317       OperChanPAutoOp (boolean)
318              Should  IRC  Operators  get AutoOp (+o) in persistent (+P) chan‐
319              nels?  Default: yes.
320
321       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
328       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
335       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
348       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
355       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
360       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
371       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
378       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

[SSL]

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
388       CertFile (string)
389              SSL Certificate file of the private server key.
390
391       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
397       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
406       KeyFile (string)
407              Filename  of SSL Server Key to be used for SSL connections. This
408              is required for SSL/TLS support.
409
410       KeyFilePassword (string)
411              OpenSSL only: Password to decrypt the private key file.
412
413       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

[OPERATOR]

419       [Operator] sections are used to define IRC Operators. There may be more
420       than one [Operator] block, one for each local operator.
421
422       Name (string)
423              ID of the operator (may be different of the nickname).
424
425       Password (string)
426              Password of the IRC operator.
427
428       Mask (string)
429              Mask  that  is to be checked before an /OPER for this account is
430              accepted.  Example: nick!ident@*.example.com
431

[SERVER]

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
438       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
445       There may be more than one [Server] block.
446
447       Name (string)
448              IRC name of the remote server.
449
450       Host (string)
451              Internet host name (or IP address) of the peer.
452
453       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
457       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
462       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
467       PeerPassword (string)
468              Foreign  password  for  this connection. This password has to be
469              configured as MyPassword on the other server.
470
471       Group (number)
472              Group of this server (optional).
473
474       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
479       SSLConnect (boolean)
480              Connect to the remote server using TLS/SSL. Default: false.
481
482       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
488              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

[CHANNEL]

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
499       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
502       There may be more than one [Channel] block.
503
504       Name (string)
505              Name of the channel, including channel prefix ("#" or "&").
506
507       Topic (string)
508              Topic for this channel.
509
510       Modes (string)
511              Initial channel modes, as used  in  "MODE"  commands.  Modifying
512              lists (ban list, invite list, exception list) is supported.
513
514              This  option  can  be specified multiple times, evaluated top to
515              bottom.
516
517       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
522                     user : nick : key
523
524              user and nick can contain the wildcard character "*".
525              key is an arbitrary password.
526
527              Valid examples are:
528
529                     *:*:KeY
530                     *:nick:123
531                     ~user:*:xyz
532
533              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
538              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

HINTS

545       It's wise to use "ngircd --configtest" to  validate  the  configuration
546       file after changing it. See ngircd(8) for details.
547

AUTHOR

549       Alexander Barton, <alex@barton.de>
550       Florian Westphal, <fw@strlen.de>
551
552       Homepage: http://ngircd.barton.de/
553

SEE ALSO

555       ngircd(8)
556
557
558
559ngIRCd                             Jan 2021                     ngircd.conf(5)
Impressum