Annotation of ircnowd/man/ngircd.conf.5.tmpl, Revision 1.1.1.1
1.1 tomglok 1: .\"
2: .\" ngircd.conf(5) manual page template
3: .\"
4: .TH ngircd.conf 5 "Jan 2021" ngIRCd "ngIRCd Manual"
5: .SH NAME
6: ngircd.conf \- configuration file of ngIRCd
7: .SH SYNOPSIS
8: .B :ETCDIR:/ngircd.conf
9: .SH DESCRIPTION
10: .BR ngircd.conf
11: is the configuration file of the
12: .BR ngircd (8)
13: Internet Relay Chat (IRC) daemon, which must be customized to the local
14: preferences and needs.
15: .PP
16: Most variables can be modified while the ngIRCd daemon is already running:
17: It will reload its configuration file when a HUP signal or REHASH command
18: is received.
19: .SH "FILE FORMAT"
20: The file consists of sections and parameters. A section begins with the name
21: of the section in square brackets and continues until the next section
22: begins.
23: .PP
24: Sections contain parameters of the form
25: .PP
26: .RS
27: .I name
28: =
29: .I value
30: .RE
31: .PP
32: Empty lines and any line beginning with a semicolon (';') or a hash ('#')
33: character are treated as a comment and will be ignored. Leading and trailing
34: whitespaces are trimmed before any processing takes place.
35: .PP
36: The file format is line-based - that means, each non-empty newline-terminated
37: line represents either a comment, a section name, or a parameter.
38: .PP
39: Section and parameter names are not case sensitive.
40: .PP
41: There are three types of variables:
42: .I booleans,
43: .I text strings,
44: and
45: .I numbers.
46: Boolean values are
47: .I true
48: if they are "yes", "true", or any non-null integer. Text strings are used 1:1
49: without leading and following spaces; there is no way to quote strings. And
50: for numbers all decimal integer values are valid.
51: .PP
52: In addition, some string or numerical variables accept lists of values,
53: separated by commas (",").
54: .SH "SECTION OVERVIEW"
55: The file can contain blocks of seven types: [Global], [Limits], [Options],
56: [SSL], [Operator], [Server], and [Channel].
57: .PP
58: The main configuration of the server is stored in the
59: .I [Global]
60: section, like the server name, administrative information and the ports on
61: which the server should be listening. The variables in this section have to be
62: adjusted to the local requirements most of the time, whereas all the variables
63: in the other sections can be left on their defaults very often.
64: .PP
65: Options in the
66: .I [Limits]
67: block are used to tweak different limits and timeouts of the daemon, like the
68: maximum number of clients allowed to connect to this server. Variables in the
69: .I [Options]
70: section can be used to enable or disable specific features of ngIRCd, like
71: support for IDENT, PAM, IPv6, and protocol and cloaking features. The
72: .I [SSL]
73: block contains all SSL-related configuration variables. These three sections
74: are all optional.
75: .PP
76: IRC operators of this server are defined in
77: .I [Operator]
78: blocks. Links to remote servers are configured in
79: .I [Server]
80: sections. And
81: .I [Channel]
82: blocks are used to configure pre-defined ("persistent") IRC channels.
83: .PP
84: There can be more than one [Operator], [Server] and [Channel] section per
85: configuration file, one for each operator, server, and channel. [Global],
86: [Limits], [Options], and [SSL] sections can occur multiple times, too, but
87: each variable overwrites itself, only the last assignment is relevant.
88: .SH [GLOBAL]
89: The
90: .I [Global]
91: section is used to define the main configuration of the server,
92: like the server name and the ports on which the server should be listening.
93: These settings depend on your personal preferences, so you should make sure
94: that they correspond to your installation and setup!
95: .TP
96: \fBName\fR (string; required)
97: Server name in the IRC network. This is an individual name of the IRC
98: server, it is not related to the DNS host name. It must be unique in the
99: IRC network and must contain at least one dot (".") character.
100: .TP
101: \fBAdminInfo1\fR, \fBAdminInfo2\fR, \fBAdminEMail\fR (string)
102: Information about the server and the administrator, used by the ADMIN
103: command. This information is not required by the server but by RFC!
104: .TP
105: \fBHelpFile\fR (string)
106: Text file which contains the ngIRCd help text. This file is required
107: to display help texts when using the "HELP <cmd>" command.
108: Please note: Changes made to this file take effect when ngircd starts up
109: or is instructed to re-read its configuration file.
110: .TP
111: \fBInfo\fR (string)
112: Info text of the server. This will be shown by WHOIS and LINKS requests for
113: example.
114: .TP
115: \fBListen\fR (list of strings)
116: A comma separated list of IP address on which the server should listen.
117: If unset, the defaults value is "0.0.0.0" or, if ngIRCd was compiled
118: with IPv6 support, "::,0.0.0.0". So the server listens on all configured
119: IP addresses and interfaces by default.
120: .TP
121: \fBMotdFile\fR (string)
122: Text file with the "message of the day" (MOTD). This message will be shown to
123: all users connecting to the server. Please note: Changes made to this file
124: take effect when ngircd starts up or is instructed to re-read its
125: configuration file.
126: .TP
127: \fBMotdPhrase\fR (string)
128: A simple Phrase (<127 chars) if you don't want to use a MOTD file.
129: .TP
130: \fBNetwork\fR (string)
131: The name of the IRC network to which this server belongs. This name is
132: optional, should only contain ASCII characters, and can't contain spaces.
133: It is only used to inform clients. The default is empty, so no network
134: name is announced to clients.
135: .TP
136: \fBPassword\fR (string)
137: Global password for all users needed to connect to the server. The default is
138: empty, so no password is required. Please note: This feature is not available
139: if ngIRCd is using PAM!
140: .TP
141: \fBPidFile\fR (string)
142: This tells ngIRCd to write its current process ID to a file. Note that the
143: "PID file" is written AFTER chroot and switching the user ID, therefore the
144: directory the file resides in must be writable by the ngIRCd user and exist
145: in the chroot directory (if configured, see above).
146: .TP
147: \fBPorts\fR (list of numbers)
148: Port number(s) on which the server should listen for unencrypted connections.
149: There may be more than one port, separated with commas (","). Default: 6667.
150: .TP
151: \fBServerGID\fR (string or number)
152: Group ID under which the ngIRCd daemon should run; you can use the name of the
153: group or the numerical ID.
154: .PP
155: .RS
156: .B Attention:
157: .br
158: For this to work the server must have been started with root privileges!
159: .RE
160: .TP
161: \fBServerUID\fR (string or number)
162: User ID under which the ngIRCd daemon should run; you can use the name of the
163: user or the numerical ID.
164: .PP
165: .RS
166: .B Attention:
167: .br
168: For this to work the server must have been started with root privileges! In
169: addition, the configuration and MOTD files must be readable by this user,
170: otherwise RESTART and REHASH won't work!
171: .RE
172: .SH [LIMITS]
173: This section is used to define some limits and timeouts for this ngIRCd
174: instance. Default values should be safe, but it is wise to double-check :-)
175: .TP
176: \fBConnectRetry\fR (number)
177: The server tries every <ConnectRetry> seconds to establish a link to not yet
178: (or no longer) connected servers. Default: 60.
179: .TP
180: \fBIdleTimeout\fR (number)
181: Number of seconds after which the whole daemon should shutdown when no
182: connections are left active after handling at least one client (0: never). This
183: can be useful for testing or when ngIRCd is started using "socket activation"
184: with systemd(8), for example. Default: 0.
185: .TP
186: \fBMaxConnections\fR (number)
187: Maximum number of simultaneous in- and outbound connections the server is
188: allowed to accept (0: unlimited). Default: 0.
189: .TP
190: \fBMaxConnectionsIP\fR (number)
191: Maximum number of simultaneous connections from a single IP address that
192: the server will accept (0: unlimited). This configuration options lowers
193: the risk of denial of service attacks (DoS). Default: 5.
194: .TP
195: \fBMaxJoins\fR (number)
196: Maximum number of channels a user can be member of (0: no limit).
197: Default: 10.
198: .TP
199: \fBMaxNickLength\fR (number)
200: Maximum length of an user nickname (Default: 9, as in RFC 2812). Please
201: note that all servers in an IRC network MUST use the same maximum nickname
202: length!
203: .TP
204: \fBMaxPenaltyTime\fR (number)
205: Maximum penalty time increase in seconds, per penalty event. Set to -1 for no
206: limit (the default), 0 to disable penalties altogether. ngIRCd doesn't use
207: penalty increases higher than 2 seconds during normal operation, so values
208: greater than 1 rarely make sense.
209: .TP
210: \fBMaxListSize\fR (number)
211: Maximum number of channels returned in response to a LIST command. Default: 100.
212: .TP
213: \fBPingTimeout\fR (number)
214: After <PingTimeout> seconds of inactivity the server will send a PING to
215: the peer to test whether it is alive or not. Default: 120.
216: .TP
217: \fBPongTimeout\fR (number)
218: If a client fails to answer a PING with a PONG within <PongTimeout>
219: seconds, it will be disconnected by the server. Default: 20.
220: .SH [OPTIONS]
221: Optional features and configuration options to further tweak the behavior of
222: ngIRCd are configured in this section. If you want to get started quickly, you
223: most probably don't have to make changes here -- they are all optional.
224: .TP
225: \fBAllowedChannelTypes\fR (string)
226: List of allowed channel types (channel prefixes) for newly created channels
227: on the local server. By default, all supported channel types are allowed.
228: Set this variable to the empty string to disallow creation of new channels
229: by local clients at all. Default: #&+
230: .TP
231: \fBAllowRemoteOper\fR (boolean)
232: If this option is active, IRC operators connected to remote servers are allowed
233: to control this local server using administrative commands, for example like
234: CONNECT, DIE, SQUIT etc. Default: no.
235: .TP
236: \fBChrootDir\fR (string)
237: A directory to chroot in when everything is initialized. It doesn't need
238: to be populated if ngIRCd is compiled as a static binary. By default ngIRCd
239: won't use the chroot() feature.
240: .PP
241: .RS
242: .B Attention:
243: .br
244: For this to work the server must have been started with root privileges!
245: .RE
246: .TP
247: \fBCloakHost\fR (string)
248: Set this hostname for every client instead of the real one. Default: empty,
249: don't change. Use %x to add the hashed value of the original hostname.
250: .TP
251: \fBCloakHostModeX\fR (string)
252: Use this hostname for hostname cloaking on clients that have the user mode
253: "+x" set, instead of the name of the server. Default: empty, use the name
254: of the server. Use %x to add the hashed value of the original hostname
255: .TP
256: \fBCloakHostSalt\fR (string)
257: The Salt for cloaked hostname hashing. When undefined a random hash is
258: generated after each server start.
259: .TP
260: \fBCloakUserToNick\fR (boolean)
261: Set every clients' user name and real name to their nickname and hide the one
262: supplied by the IRC client. Default: no.
263: .TP
264: \fBConnectIPv4\fR (boolean)
265: Set this to no if you do not want ngIRCd to connect to other IRC servers using
266: the IPv4 protocol. This allows the usage of ngIRCd in IPv6-only setups.
267: Default: yes.
268: .TP
269: \fBConnectIPv6\fR (boolean)
270: Set this to no if you do not want ngIRCd to connect to other IRC servers using
271: the IPv6 protocol.
272: Default: yes.
273: .TP
274: \fBDefaultUserModes\fR (string)
275: Default user mode(s) to set on new local clients. Please note that only modes
276: can be set that the client could set using regular MODE commands, you can't
277: set "a" (away) for example!
278: Default: none.
279: .TP
280: \fBDNS\fR (boolean)
281: If set to false, ngIRCd will not make any DNS lookups when clients connect.
282: If you configure the daemon to connect to other servers, ngIRCd may still
283: perform a DNS lookup if required.
284: Default: yes.
285: .TP
286: \fBIdent\fR (boolean)
287: If ngIRCd is compiled with IDENT support this can be used to disable IDENT
288: lookups at run time.
289: Users identified using IDENT are registered without the "~" character
290: prepended to their user name.
291: Default: yes.
292: .TP
293: \fBIncludeDir\fR (string)
294: Directory containing configuration snippets (*.conf), that should be read in
295: after parsing the current configuration file.
296: Default: none.
297: .TP
298: \fBMorePrivacy\fR (boolean)
299: This will cause ngIRCd to censor user idle time, logon time as well as the
300: PART/QUIT messages (that are sometimes used to inform everyone about which
301: client software is being used). WHOWAS requests are also silently ignored,
302: and NAMES output doesn't list any clients for non-members.
303: This option is most useful when ngIRCd is being used together with
304: anonymizing software such as TOR or I2P and one does not wish to make it
305: too easy to collect statistics on the users.
306: Default: no.
307: .TP
308: \fBNoticeBeforeRegistration\fR (boolean)
309: Normally ngIRCd doesn't send any messages to a client until it is registered.
310: Enable this option to let the daemon send "NOTICE *" messages to clients
311: while connecting. Default: no.
312: .TP
313: \fBOperCanUseMode\fR (boolean)
314: Should IRC Operators be allowed to use the MODE command even if they are
315: not(!) channel-operators? Default: no.
316: .TP
317: \fBOperChanPAutoOp\fR (boolean)
318: Should IRC Operators get AutoOp (+o) in persistent (+P) channels?
319: Default: yes.
320: .TP
321: \fBOperServerMode\fR (boolean)
322: If \fBOperCanUseMode\fR is enabled, this may lead the compatibility problems
323: with Servers that run the ircd-irc2 Software. This Option "masks" mode
324: requests by non-chanops as if they were coming from the server. Default: no;
325: only enable it if you have ircd-irc2 servers in your IRC network.
326: .TP
327: \fBPAM\fR (boolean)
328: If ngIRCd is compiled with PAM support this can be used to disable all calls
329: to the PAM library at runtime; all users connecting without password are
330: allowed to connect, all passwords given will fail.
331: Users identified using PAM are registered without the "~" character
332: prepended to their user name.
333: Default: yes.
334: .TP
335: \fBPAMIsOptional\fR (boolean)
336: When PAM is enabled, all clients are required to be authenticated using PAM;
337: connecting to the server without successful PAM authentication isn't possible.
338: If this option is set, clients not sending a password are still allowed to
339: connect: they won't become "identified" and keep the "~" character prepended
340: to their supplied user name.
341: Please note:
342: To make some use of this behavior, it most probably isn't useful to enable
343: "Ident", "PAM" and "PAMIsOptional" at the same time, because you wouldn't be
344: able to distinguish between Ident'ified and PAM-authenticated users: both
345: don't have a "~" character prepended to their respective user names!
346: Default: no.
347: .TP
348: \fBPAMServiceName\fR (string)
349: When PAM is enabled, this value determines the used PAM configuration.
350: This setting allows running multiple ngIRCd instances with different
351: PAM configurations on each instance. If you set it to "ngircd-foo",
352: PAM will use /etc/pam.d/ngircd-foo instead of the default
353: /etc/pam.d/ngircd.
354: Default: ngircd.
355: .TP
356: \fBRequireAuthPing\fR (boolean)
357: Let ngIRCd send an "authentication PING" when a new client connects, and
358: register this client only after receiving the corresponding "PONG" reply.
359: Default: no.
360: .TP
361: \fBScrubCTCP\fR (boolean)
362: If set to true, ngIRCd will silently drop all CTCP requests sent to it from
363: both clients and servers. It will also not forward CTCP requests to any
364: other servers. CTCP requests can be used to query user clients about which
365: software they are using and which versions said software is. CTCP can also be
366: used to reveal clients IP numbers. ACTION CTCP requests are not blocked,
367: this means that /me commands will not be dropped, but please note that
368: blocking CTCP will disable file sharing between users!
369: Default: no.
370: .TP
371: \fBSyslogFacility\fR (string)
372: Syslog "facility" to which ngIRCd should send log messages. Possible
373: values are system dependent, but most probably "auth", "daemon", "user"
374: and "local1" through "local7" are possible values; see syslog(3).
375: Default is "local5" for historical reasons, you probably want to
376: change this to "daemon", for example.
377: .TP
378: \fBWebircPassword\fR (string)
379: Password required for using the WEBIRC command used by some Web-to-IRC
380: gateways. If not set or empty, the WEBIRC command can't be used.
381: Default: not set.
382: .SH [SSL]
383: All SSL-related configuration variables are located in the
384: .I [SSL]
385: section. 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: .TP
388: \fBCertFile\fR (string)
389: SSL Certificate file of the private server key.
390: .TP
391: \fBCipherList\fR (string)
392: Select cipher suites allowed for SSL/TLS connections. This defaults to
393: "HIGH:!aNULL:@STRENGTH:!SSLv3" (OpenSSL) or "SECURE128:-VERS-SSL3.0" (GnuTLS).
394: Please see 'man 1ssl ciphers' (OpenSSL) and 'man 3 gnutls_priority_init'
395: (GnuTLS) for details.
396: .TP
397: \fBDHFile\fR (string)
398: Name of the Diffie-Hellman Parameter file. Can be created with GnuTLS
399: "certtool \-\-generate-dh-params" or "openssl dhparam". If this file is not
400: present, it will be generated on startup when ngIRCd was compiled with GnuTLS
401: support (this may take some time). If ngIRCd was compiled with OpenSSL, then
402: (Ephemeral)-Diffie-Hellman Key Exchanges and several Cipher Suites will not be
403: available.
404: .TP
405: \fBKeyFile\fR (string)
406: Filename of SSL Server Key to be used for SSL connections. This is required
407: for SSL/TLS support.
408: .TP
409: \fBKeyFilePassword\fR (string)
410: OpenSSL only: Password to decrypt the private key file.
411: .TP
412: \fBPorts\fR (list of numbers)
413: Same as \fBPorts\fR , except that ngIRCd will expect incoming connections
414: to be SSL/TLS encrypted. Common port numbers for SSL-encrypted IRC are 6669
415: and 6697. Default: none.
416: .SH [OPERATOR]
417: .I [Operator]
418: sections are used to define IRC Operators. There may be more than one
419: .I [Operator]
420: block, one for each local operator.
421: .TP
422: \fBName\fR (string)
423: ID of the operator (may be different of the nickname).
424: .TP
425: \fBPassword\fR (string)
426: Password of the IRC operator.
427: .TP
428: \fBMask\fR (string)
429: Mask that is to be checked before an /OPER for this account is accepted.
430: Example: nick!ident@*.example.com
431: .SH [SERVER]
432: Other servers are configured in
433: .I [Server]
434: sections. If you configure a port for the connection, then this ngIRCd
435: tries to connect to the other server on the given port (active);
436: if not, it waits for the other server to connect (passive).
437: .PP
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 next
442: server in the given group (="with the same ID"), but never tries to connect
443: to more than one server of this group simultaneously.
444: .PP
445: There may be more than one
446: .I [Server]
447: block.
448: .TP
449: \fBName\fR (string)
450: IRC name of the remote server.
451: .TP
452: \fBHost\fR (string)
453: Internet host name (or IP address) of the peer.
454: .TP
455: \fBBind\fR (string)
456: IP address to use as source IP for the outgoing connection. Default is
457: to let the operating system decide.
458: .TP
459: \fBPort\fR (number)
460: Port of the remote server to which ngIRCd should connect (active).
461: If no port is assigned to a configured server, the daemon only waits for
462: incoming connections (passive, default).
463: .TP
464: \fBMyPassword\fR (string)
465: Own password for this connection. This password has to be configured as
466: \fBPeerPassword\fR on the other server. Must not have ':' as first character.
467: .TP
468: \fBPeerPassword\fR (string)
469: Foreign password for this connection. This password has to be configured as
470: \fBMyPassword\fR on the other server.
471: .TP
472: \fBGroup\fR (number)
473: Group of this server (optional).
474: .TP
475: \fBPassive\fR (boolean)
476: Disable automatic connection even if port value is specified. Default: false.
477: You can use the IRC Operator command CONNECT later on to create the link.
478: .TP
479: \fBSSLConnect\fR (boolean)
480: Connect to the remote server using TLS/SSL. Default: false.
481: .TP
482: \fBServiceMask\fR (string)
483: Define a (case insensitive) list of masks matching nicknames that should be
484: treated as IRC services when introduced via this remote server, separated
485: by commas (","). REGULAR SERVERS DON'T NEED this parameter, so leave it empty
486: (which is the default).
487: .PP
488: .RS
489: When you are connecting IRC services which mask as a IRC server and which use
490: "virtual users" to communicate with, for example "NickServ" and "ChanServ",
491: you should set this parameter to something like "*Serv", "*Serv,OtherNick",
492: or "NickServ,ChanServ,XyzServ".
493: .SH [CHANNEL]
494: Pre-defined channels can be configured in
495: .I [Channel]
496: sections. Such channels are created by the server when starting up and even
497: persist when there are no more members left.
498: .PP
499: Persistent channels are marked with the mode 'P', which can be set and unset
500: by IRC operators like other modes on the fly.
501: .PP
502: There may be more than one
503: .I [Channel]
504: block.
505: .TP
506: \fBName\fR (string)
507: Name of the channel, including channel prefix ("#" or "&").
508: .TP
509: \fBTopic\fR (string)
510: Topic for this channel.
511: .TP
512: \fBModes\fR (string)
513: Initial channel modes, as used in "MODE" commands. Modifying lists (ban list,
514: invite list, exception list) is supported.
515: .PP
516: .RS
517: This option can be specified multiple times, evaluated top to bottom.
518: .RE
519: .TP
520: \fBKeyFile\fR (string)
521: Path and file name of a "key file" containing individual channel keys for
522: different users. The file consists of plain text lines with the following
523: syntax (without spaces!):
524: .PP
525: .RS
526: .RS
527: .I user
528: :
529: .I nick
530: :
531: .I key
532: .RE
533: .PP
534: .I user
535: and
536: .I nick
537: can contain the wildcard character "*".
538: .br
539: .I key
540: is an arbitrary password.
541: .PP
542: Valid examples are:
543: .PP
544: .RS
545: *:*:KeY
546: .br
547: *:nick:123
548: .br
549: ~user:*:xyz
550: .RE
551: .PP
552: The key file is read on each JOIN command when this channel has a key
553: (channel mode +k). Access is granted, if a) the channel key set using the
554: MODE +k command or b) one of the lines in the key file match.
555: .PP
556: .B Please note:
557: .br
558: The file is not reopened on each access, so you can modify and overwrite it
559: without problems, but moving or deleting the file will have not effect until
560: the daemon re-reads its configuration!
561: .RE
562: .SH HINTS
563: It's wise to use "ngircd \-\-configtest" to validate the configuration file
564: after changing it. See
565: .BR ngircd (8)
566: for details.
567: .SH AUTHOR
568: Alexander Barton, <alex@barton.de>
569: .br
570: Florian Westphal, <fw@strlen.de>
571: .PP
572: Homepage: http://ngircd.barton.de/
573: .SH "SEE ALSO"
574: .BR ngircd (8)
575: .\"
576: .\" -eof-
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ngircd.conf.5.tmpl CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [local] / ircnowd / man