.\"
-.\" $Id: ngircd.conf.5.tmpl,v 1.5 2007/10/25 11:01:19 fw Exp $
+.\" ngircd.conf(5) manual page template
.\"
-.TH ngircd.conf 5 "August 2005" ngircd "ngIRCd Manual"
+.TH ngircd.conf 5 "Dec 2008" ngircd "ngIRCd Manual"
.SH NAME
ngircd.conf \- configuration file of ngIRCd
.SH SYNOPSIS
.BR ngircd (8)
Internet Relay Chat (IRC) daemon which you should adept to your local
preferences and needs.
+.PP
+Most variables can be modified while the ngIRCd daemon is already running:
+It will reload its configuration when a HUP signal is received.
.SH "FILE FORMAT"
The file consists of sections and parameters. A section begins with the name
of the section in square brackets and continues until the next section
.RE
.PP
Empty lines and any line beginning with a semicolon (';') or a hash ('#')
-character is treated as a comment and will be ignored.
+character are treated as a comment and will be ignored. Leading and trailing
+whitespaces are trimmed before any processing takes place.
.PP
-The file format is line-based - that means, each newline-terminated line
-represents either a comment, a section name or a parameter.
+The file format is line-based - that means, each non-empty newline-terminated
+line represents either a comment, a section name, or a parameter.
.PP
Section and parameter names are not case sensitive.
.SH "SECTION OVERVIEW"
The file can contain blocks of four types: [Global], [Operator], [Server],
and [Channel].
.PP
-In the
+The main configuration of the server is stored in the
.I [Global]
-section, there is the main configuration like the server name and the
+section, like the server name, administrative information and the
ports on which the server should be listening. IRC operators of this
server are defined in
.I [Operator]
name and the ports on which the server should be listening.
.TP
\fBName\fR
-Server name in the IRC network
+Server name in the IRC network. This is an individual name of the IRC
+server, it is not related to the DNS host name. It must be unique in the
+IRC network and must contain at least one dot (".") character.
.TP
\fBInfo\fR
Info text of the server. This will be shown by WHOIS and LINKS requests for
example.
.TP
+\fBPassword\fR
+Global password for all users needed to connect to the server. The default
+is empty, so no password is required.
+.TP
+\fBWebircPassword\fR
+Password required for using the WEBIRC command used by some Web-to-IRC
+gateways. If not set or empty, the WEBIRC command can't be used.
+Default: not set.
+.TP
\fBAdminInfo1\fR, \fBAdminInfo2\fR, \fBAdminEMail\fR
Information about the server and the administrator, used by the ADMIN
command.
.TP
\fBPorts\fR
Ports on which the server should listen. There may be more than one port,
-separated with ','. Default: 6667.
+separated with commas (","). Default: 6667, unless \fBSSL_Ports\fR are also
+specified.
+.TP
+\fBSSLPorts\fR
+Same as \fBPorts\fR , except that ngIRCd will expect incoming connections
+to be SSL/TLS encrypted. Common port numbers for SSL-encrypted IRC are 6669
+and 6697. Default: none.
+.TP
+\fBSSLKeyFile\fR
+Filename of SSL Server Key to be used for SSL connections. This is required for
+SSL/TLS support.
+.TP
+\fBSSLKeyFilePassword\fR
+(OpenSSL only:) Password to decrypt private key.
+.TP
+\fBSSLCertFile\fR
+Certificate file of the private key.
+.TP
+\fBSSLDHFile\fR
+Name of the Diffie-Hellman Parameter file. Can be created with gnutls
+"certtool \-\-generate-dh-params" or "openssl dhparam".
+If this file is not present, it will be generated on startup when ngIRCd
+was compiled with gnutls support (this may take some time). If ngIRCd
+was compiled with OpenSSL, then (Ephemeral)-Diffie-Hellman Key Exchanges and several
+Cipher Suites will not be available.
.TP
\fBListen\fR
-The IP address on which the server should listen. Default is empty, so
-the server listens on all configured IP addresses and interfaces.
+A comma separated list of IP address on which the server should listen.
+If unset, the defaults value is "0.0.0.0" or, if ngIRCd was compiled
+with IPv6 support, "::,0.0.0.0". So the server listens on all configured
+IP addresses and interfaces by default.
+.TP
+\fBSyslogFacility\fR
+Syslog "facility" to which ngIRCd should send log messages. Possible
+values are system dependant, but most probably "auth", "daemon", "user"
+and "local1" through "local7" are possible values; see syslog(3).
+Default is "local5" for historical reasons, you probably want to
+change this to "daemon", for example.
.TP
\fBMotdFile\fR
Text file with the "message of the day" (MOTD). This message will be shown
-to all users connecting to the server.
+to all users connecting to the server. Changes made to this file
+take effect when ngircd is instructed to re-read its configuration file.
.TP
\fBMotdPhrase\fR
A simple Phrase (<256 chars) if you don't want to use a MOTD file.
-If it is set no MotdFile will be read at all.
.TP
\fBServerUID\fR
User ID under which the server should run; you can use the name of the user
not(!) channel-operators? Default: no.
.TP
\fBOperServerMode\fR
-If OperCanUseMode is enabled, this may lead the compatibility problems with
+If \fBOperCanUseMode\fR is enabled, this may lead the compatibility problems with
Servers that run the ircd-irc2 Software. This Option "masks" mode requests
by non-chanops as if they were coming from the server. Default: no.
.TP
+\fBAllowRemoteOper\fR
+Are IRC operators connected to remote servers allowed to control this server,
+e. g. are they allowed to use administrative commands like CONNECT, DIE,
+SQUIT, ... that affect this server? Default: no.
+.TP
\fBPredefChannelsOnly\fR
If enabled, no new channels can be created. Useful if
you do not want to have channels other than those defined in
-the config file.
-Default: No.
+[Channel] sections in the configuration file.
+Default: no.
.TP
\fBNoDNS\fR
-If enabled, ngircd will not make DNS lookups when clients connect.
-If you configure ngircd to connect to other servers, ngircd may still
+If set to true, ngIRCd will not make DNS lookups when clients connect.
+If you configure the daemon to connect to other servers, ngIRCd may still
perform a DNS lookup if required.
-Default: No.
+Default: no.
+.TP
+\fBNoIdent\fR
+If ngIRCd is compiled with IDENT support this can be used to disable IDENT
+lookups at run time.
+Default: no.
+.TP
+\fBNoPAM\fR
+If ngIRCd is compiled with PAM support this can be used to disable all calls
+to the PAM library at runtime; all users connecting without password are
+allowed to connect, all passwords given will fail.
+Default: no.
+.TP
+\fBConnectIPv4\fR
+Set this to no if you do not want ngIRCd to connect to other IRC servers using
+IPv4. This allows usage of ngIRCd in IPv6-only setups.
+Default: yes.
+.TP
+\fBConnectIPv6\fR
+Set this to no if you do not want ngIRCd to connect to other irc servers using IPv6.
+Default: yes.
.TP
\fBMaxConnections\fR
-Maximum number of simultaneous connection the server is allowed to accept
-(0: unlimited). Default: 0.
+Maximum number of simultaneous in- and outbound connections the server is
+allowed to accept (0: unlimited). Default: 0.
.TP
\fBMaxConnectionsIP\fR
Maximum number of simultaneous connections from a single IP address that
\fBMaxJoins\fR
Maximum number of channels a user can be member of (0: no limit).
Default: 10.
+.TP
+\fBMaxNickLength\fR
+Maximum length of an user nick name (Default: 9, as in RFC 2812). Please
+note that all servers in an IRC network MUST use the same maximum nick name
+length!
.SH [OPERATOR]
.I [Operator]
sections are used to define IRC Operators. There may be more than one
Other servers are configured in
.I [Server]
sections. If you configure a port for the connection, then this ngIRCd
-tries to connect to to the other server on the given port; if not, it waits
-for the other server to connect.
+tries to connect to to the other server on the given port (active);
+if not, it waits for the other server to connect (passive).
.PP
-The ngIRCd allows "server groups": You can assign an "ID" to every server
-with which you want this ngIRCd to link. If a server of a group won't
-answer, the ngIRCd tries to connect to the next server in the given group.
-But ngIRCd never tries to connect to two servers with the same group ID.
+ngIRCd supports "server groups": You can assign an "ID" to every server
+with which you want this ngIRCd to link, and the daemon ensures that at
+any given time only one direct link exists to servers with the same ID.
+So if a server of a group won't answer, ngIRCd tries to connect to the next
+server in the given group (="with the same ID"), but never tries to connect
+to more than one server of this group simultaneously.
.PP
There may be more than one
.I [Server]
block.
.TP
\fBName\fR
-IRC name of the server
+IRC name of the remote server.
.TP
\fBHost\fR
-Internet host name of the peer
+Internet host name (or IP address) of the peer.
+.TP
+\fBBind\fR
+IP address to use as source IP for the outgoing connection. Default is
+to let the operating system decide.
.TP
\fBPort\fR
-Port of the server to which the ngIRCd should connect. If you assign no port
-the ngIRCd waits for incoming connections.
+Port of the remote server to which ngIRCd should connect (active).
+If no port is assigned to a configured server, the daemon only waits for
+incoming connections (passive, default).
.TP
\fBMyPassword\fR
Own password for this connection. This password has to be configured as
-"PeerPassword" on the other server. Must not have ':' as first character.
+\fBPeerPassword\fR on the other server. Must not have ':' as first character.
.TP
\fBPeerPassword\fR
Foreign password for this connection. This password has to be configured as
-"MyPassword" on the other server.
+\fBMyPassword\fR on the other server.
.TP
\fBGroup\fR
Group of this server (optional).
+.TP
\fBPassive\fR
Disable automatic connection even if port value is specified. Default: false.
You can use the IRC Operator command CONNECT later on to create the link.
+.TP
+\fBSSLConnect\fR
+Connect to the remote server using TLS/SSL. Default: false.
+.TP
+\fBServiceMask\fR
+Define a (case insensitive) mask matching nick names that should be treated as
+IRC services when introduced via this remote server. REGULAR SERVERS DON'T NEED
+this parameter, so leave it empty (which is the default).
+.PP
+.RS
+When you are connecting IRC services which mask as a IRC server and which use
+"virtual users" to communicate with, for example "NickServ" and "ChanServ",
+you should set this parameter to something like "*Serv".
.SH [CHANNEL]
Pre-defined channels can be configured in
.I [Channel]
block.
.TP
\fBName\fR
-Name of the channel
+Name of the channel, including channel prefix ("#" or "&").
.TP
\fBTopic\fR
-Topic for this channel
+Topic for this channel.
.TP
\fBModes\fR
Initial channel modes.
.TP
\fBKey\fR
-Sets initial channel key (only relevant if mode k is set)
+Sets initial channel key (only relevant if channel mode "k" is set).
+.TP
+\fBKeyFile\fR
+Path and file name of a "key file" containing individual channel keys for
+different users. The file consists of plain text lines with the following
+syntax (without spaces!):
+.PP
+.RS
+.RS
+.I user
+:
+.I nick
+:
+.I key
+.RE
+.PP
+.I user
+and
+.I nick
+can contain the wildcard character "*".
+.br
+.I key
+is an arbitrary password.
+.PP
+Valid examples are:
+.PP
+.RS
+*:*:KeY
+.br
+*:nick:123
+.br
+~user:*:xyz
+.RE
+.PP
+The key file is read on each JOIN command when this channel has a key
+(channel mode +k). Access is granted, if a) the channel key set using the
+MODE +k command or b) one of the lines in the key file match.
+.PP
+.B Please note:
+.br
+The file is not reopened on each access, so you can modify and overwrite it
+without problems, but moving or deleting the file will have not effect until
+the daemon re-reads its configuration!
+.RE
.TP
\fBMaxUsers\fR
-Set maximum user limit for this channel (only relevant if mode l is set)
+Set maximum user limit for this channel (only relevant if channel mode "l"
+is set).
.SH HINTS
-It's wise to use "ngircd --configtest" to validate the configuration file
+It's wise to use "ngircd \-\-configtest" to validate the configuration file
after changing it. See
.BR ngircd (8)
for details.
.SH AUTHOR
Alexander Barton,
.UR mailto:alex@barton.de
-alex@barton.de
.UE
.br
Homepage:
.UR http://ngircd.barton.de/
-http://ngircd.barton.de/
.UE
.SH "SEE ALSO"
.BR ngircd (8)
projects / ngircd-alex.git / blobdiff