123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417 |
- .\"
- .\" ngircd.conf(5) manual page template
- .\"
- .TH ngircd.conf 5 "Dec 2010" ngircd "ngIRCd Manual"
- .SH NAME
- ngircd.conf \- configuration file of ngIRCd
- .SH SYNOPSIS
- .B :ETCDIR:/ngircd.conf
- .SH DESCRIPTION
- .BR ngircd.conf
- is the configuration file of the
- .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
- begins.
- .PP
- Sections contain parameters of the form
- .PP
- .RS
- .I name
- =
- .I value
- .RE
- .PP
- Empty lines and any line beginning with a semicolon (';') or a hash ('#')
- 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 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
- The main configuration of the server is stored in the
- .I [Global]
- 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]
- blocks.
- .I [Server]
- is the section where server links are configured. And
- .I [Channel]
- blocks are used to configure pre-defined ("persistent") IRC channels.
- .PP
- There can be more than one [Operator], [Server] and [Channel] sections
- per configuration file, but only one [Global] section.
- .SH [GLOBAL]
- The
- .I [Global]
- section is used to define the server main configuration, like the server
- name and the ports on which the server should be listening.
- .TP
- \fBName\fR
- 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 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
- 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. 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.
- .TP
- \fBServerUID\fR
- User ID under which the server should run; you can use the name of the user
- or the numerical ID.
- .PP
- .RS
- .B Attention:
- .br
- For this to work the server must have been
- started with root privileges! In addition, the configuration and MOTD files
- must be readable by this user, otherwise RESTART and REHASH won't work!
- .RE
- .TP
- \fBServerGID\fR
- Group ID under which the ngIRCd should run; you can use the name of the
- group or the numerical ID.
- .PP
- .RS
- .B Attention:
- .br
- For this to work the server must have
- been started with root privileges!
- .RE
- .TP
- \fBChrootDir\fR
- A directory to chroot in when everything is initialized. It doesn't need
- to be populated if ngIRCd is compiled as a static binary. By default ngIRCd
- won't use the chroot() feature.
- .PP
- .RS
- .B Attention:
- .br
- For this to work the server must have
- been started with root privileges!
- .RE
- .TP
- \fBPidFile\fR
- This tells ngIRCd to write its current process ID to a file. Note that the
- pidfile is written AFTER chroot and switching the user ID, i. e. the
- directory the pidfile resides in must be writeable by the ngIRCd user and
- exist in the chroot directory (if configured, see above).
- .RE
- .TP
- \fBPingTimeout\fR
- After <PingTimeout> seconds of inactivity the server will send a PING to
- the peer to test whether it is alive or not. Default: 120.
- .TP
- \fBPongTimeout\fR
- If a client fails to answer a PING with a PONG within <PongTimeout>
- seconds, it will be disconnected by the server. Default: 20.
- .TP
- \fBConnectRetry\fR
- The server tries every <ConnectRetry> seconds to establish a link to not yet
- (or no longer) connected servers. Default: 60.
- .TP
- \fBOperCanUseMode\fR
- Should IRC Operators be allowed to use the MODE command even if they are
- not(!) channel-operators? Default: no.
- .TP
- \fBOperServerMode\fR
- 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
- [Channel] sections in the configuration file.
- Default: no.
- .TP
- \fBNoDNS\fR
- 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.
- .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
- \fBNoZeroConf\fR
- If ngIRCd is compiled to register its services using ZeroConf (e.g. using
- Howl, Avahi or on Mac OS X) this parameter can be used to disable service
- registration at runtime.
- 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 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
- the server will accept (0: unlimited). This configuration options lowers
- the risk of denial of service attacks (DoS). Default: 5.
- .TP
- \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
- .I [Operator]
- block, one for each local operator.
- .TP
- \fBName\fR
- ID of the operator (may be different of the nick name).
- .TP
- \fBPassword\fR
- Password of the IRC operator.
- .TP
- \fBMask\fR
- Mask that is to be checked before an /OPER for this account is accepted.
- Example: nick!ident@*.example.com
- .SH [SERVER]
- 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 (active);
- if not, it waits for the other server to connect (passive).
- .PP
- 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 remote server.
- .TP
- \fBHost\fR
- 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 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
- \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
- \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]
- sections. Such channels are created by the server when starting up and even
- persist when there are no more members left.
- .PP
- Persistent channels are marked with the mode 'P', which can be set and unset
- by IRC operators like other modes on the fly.
- .PP
- There may be more than one
- .I [Channel]
- block.
- .TP
- \fBName\fR
- Name of the channel, including channel prefix ("#" or "&").
- .TP
- \fBTopic\fR
- Topic for this channel.
- .TP
- \fBModes\fR
- Initial channel modes.
- .TP
- \fBKey\fR
- 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
- .br
- .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 channel mode "l"
- is set).
- .SH HINTS
- 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, <alex@barton.de>
- .br
- Florian Westphal, <fw@strlen.de>
- .PP
- Homepage: http:
- .SH "SEE ALSO"
- .BR ngircd (8)
- .\"
- .\" -eof-
|