X-Git-Url: https://arthur.barton.de/cgi-bin/gitweb.cgi?p=ngircd-alex.git;a=blobdiff_plain;f=man%2Fngircd.conf.5.tmpl;h=ccf3d948165f4d87c3100ab51b3796288b111995;hp=8321900926d6218ec9ffb7ad34a3166a90f608dd;hb=bd118c65fdb1428daf4775205b0f40918b3f22fb;hpb=001c00b27312289e40425db19ce9f7d957ffbbba diff --git a/man/ngircd.conf.5.tmpl b/man/ngircd.conf.5.tmpl index 83219009..ccf3d948 100644 --- a/man/ngircd.conf.5.tmpl +++ b/man/ngircd.conf.5.tmpl @@ -1,7 +1,7 @@ .\" -.\" $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 "Jun 2011" ngircd "ngIRCd Manual" .SH NAME ngircd.conf \- configuration file of ngIRCd .SH SYNOPSIS @@ -10,8 +10,12 @@ ngircd.conf \- configuration file of ngIRCd .BR ngircd.conf is the configuration file of the .BR ngircd (8) -Internet Relay Chat (IRC) daemon which you should adept to your local +Internet Relay Chat (IRC) daemon, which must be customized to the local preferences and needs. +.PP +Most variables can be modified while the ngIRCd daemon is already running: +It will reload its configuration file when a HUP signal or REHASH command +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 @@ -26,204 +30,387 @@ Sections contain parameters of the form .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. +.PP +There are three types of variables: +.I booleans, +.I text strings, +and +.I numbers. +Boolean values are +.I true +if they are "yes", "true", or any non-null integer. Text strings are used 1:1 +without leading and following spaces; there is no way to quote strings. And +for numbers all decimal integer values are valid. +.PP +In addition, some string or numerical variables accept lists of values, +separated by commas (","). .SH "SECTION OVERVIEW" -The file can contain blocks of four types: [Global], [Operator], [Server], -and [Channel]. +The file can contain blocks of seven types: [Global], [Limits], [Options], +[SSL], [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 -ports on which the server should be listening. IRC operators of this -server are defined in +section, like the server name, administrative information and the ports on +which the server should be listening. The variables in this section have to be +adjusted to the local requirements most of the time, whereas all the variables +in the other sections can be left on there defaults very often. +.PP +Options in the +.I [Limits] +block are used to tweak different limits and timeouts of the daemon, like the +maximum number of clients allowed to connect to this server. Variables in the +.I [Options] +section can be used to enable or disable specific features of ngIRCd, like +support for IDENT, PAM, IPv6, and protocol and cloaking features. The +.I [SSL] +block contains all SSL-related configuration variables. These three sections +are all optional. +.PP +IRC operators of this server are defined in .I [Operator] -blocks. +blocks. Links to remote servers are configured in .I [Server] -is the section where server links are configured. And +sections. 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. +There can be more than one [Operator], [Server] and [Channel] section per +configuration file (one for each operator, server, and channel), but only +exactly one [Global], one [Limits], one [Options], and one [SSL] 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. +section of this file is used to define the main configuration of the server, +like the server name and the ports on which the server should be listening. +These settings depend on your personal preferences, so you should make sure +that they correspond to your installation and setup! .TP -\fBName\fR -Server name in the IRC network +\fBName\fR (string; required) +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 +\fBAdminInfo1\fR, \fBAdminInfo2\fR, \fBAdminEMail\fR (string) +Information about the server and the administrator, used by the ADMIN +command. This information is not required by the server but by RFC! +.TP +\fBInfo\fR (string) Info text of the server. This will be shown by WHOIS and LINKS requests for example. .TP -\fBAdminInfo1\fR, \fBAdminInfo2\fR, \fBAdminEMail\fR -Information about the server and the administrator, used by the ADMIN -command. +\fBListen\fR (list of strings) +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 -\fBPorts\fR -Ports on which the server should listen. There may be more than one port, -separated with ','. Default: 6667. +\fBMotdFile\fR (string) +Text file with the "message of the day" (MOTD). This message will be shown to +all users connecting to the server. Please note: Changes made to this file +take effect when ngircd starts up or is instructed to re-read its +configuration file. .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. +\fBMotdPhrase\fR (string) +A simple Phrase (<256 chars) if you don't want to use a MOTD file. .TP -\fBMotdFile\fR -Text file with the "message of the day" (MOTD). This message will be shown -to all users connecting to the server. +\fBPassword\fR (string) +Global password for all users needed to connect to the server. The default is +empty, so no password is required. Please note: This feature is not available +if ngIRCd is using PAM! .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. +\fBPidFile\fR (string) +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, e.g. the directory +the pidfile resides in must be writable by the ngIRCd user and exist in the +chroot directory (if configured, see above). .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 +\fBPorts\fR (list of numbers) +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 -\fBServerGID\fR +\fBServerGID\fR (string or number) 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! +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. +\fBServerUID\fR (string or number) +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! +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 +.SH [LIMITS] +Define some limits and timeouts for this ngIRCd instance. Default values +should be safe, but it is wise to double-check :-) .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 +\fBConnectRetry\fR (number) +The server tries every seconds to establish a link to not yet +(or no longer) connected servers. Default: 60. +.TP +\fBMaxConnections\fR (number) +Maximum number of simultaneous in- and outbound connections the server is +allowed to accept (0: unlimited). Default: 0. +.TP +\fBMaxConnectionsIP\fR (number) +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 (number) +Maximum number of channels a user can be member of (0: no limit). +Default: 10. +.TP +\fBMaxNickLength\fR (number) +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! .TP -\fBPingTimeout\fR +\fBPingTimeout\fR (number) After 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 +\fBPongTimeout\fR (number) If a client fails to answer a PING with a PONG within seconds, it will be disconnected by the server. Default: 20. +.SH [OPTIONS] +Optional features and configuration options to further tweak the behavior of +ngIRCd. If you want to get started quickly, you most probably don't have to +make changes here -- they are all optional. .TP -\fBConnectRetry\fR -The server tries every seconds to establish a link to not yet -(or no longer) connected servers. Default: 60. +\fBAllowRemoteOper\fR (boolean) +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 -\fBOperCanUseMode\fR -Should IRC Operators be allowed to use the MODE command even if they are -not(!) channel-operators? Default: no. +\fBChrootDir\fR (string) +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 -\fBOperServerMode\fR -If OperCanUseMode 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. +\fBCloakHost\fR (string) +Set this hostname for every client instead of the real one. Default: empty, +don't change. +.PP +.RS +.B Please note: +.br +Don't use the percentage sign ("%"), it is reserved for future extensions! +.RE .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. +\fBCloakUserToNick\fR (boolean) +Set every clients' user name to their nick name and hide the one supplied +by the IRC client. 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 -perform a DNS lookup if required. -Default: No. +\fBConnectIPv4\fR (boolean) +Set this to no if you do not want ngIRCd to connect to other IRC servers using +the IPv4 protocol. This allows the usage of ngIRCd in IPv6-only setups. +Default: yes. .TP -\fBMaxConnections\fR -Maximum number of simultaneous connection the server is allowed to accept -(0: unlimited). Default: 0. +\fBConnectIPv6\fR (boolean) +Set this to no if you do not want ngIRCd to connect to other IRC servers using +the IPv6 protocol. +Default: yes. .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. +\fBDNS\fR (boolean) +If set to false, ngIRCd will not make any 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: yes. +.TP +\fBIdent\fR (boolean) +If ngIRCd is compiled with IDENT support this can be used to disable IDENT +lookups at run time. +Default: yes. +.TP +\fBMorePrivacy\fR (boolean) +This will cause ngIRCd to censor user idle time, logon time as well as the +part/quit messages (that are sometimes used to inform everyone about which +client software is being used). WHOWAS requests are also silently ignored. +This option is most useful when ngIRCd is being used together with +anonymizing software such as TOR or I2P and one does not wish to make it +too easy to collect statistics on the users. +Default: no. +.TP +\fBNoticeAuth\fR (boolean) +Normally ngIRCd doesn't send any messages to a client until it is registered. +Enable this option to let the daemon send "NOTICE AUTH" messages to clients +while connecting. Default: no. +.TP +\fBOperCanUseMode\fR (boolean) +Should IRC Operators be allowed to use the MODE command even if they are +not(!) channel-operators? Default: no. .TP -\fBMaxJoins\fR -Maximum number of channels a user can be member of (0: no limit). -Default: 10. +\fBOperServerMode\fR (boolean) +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; +only enable it if you have ircd-irc2 servers in your IRC network. +.TP +\fBPAM\fR (boolean) +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: yes. +.TP +\fBPredefChannelsOnly\fR (boolean) +If enabled, no new channels can be created. Useful if you do not want to have +other channels than those defined in [Channel] sections in the configuration +file on this server. +Default: no. +.TP +\fBRequireAuthPing\fR (boolean) +Let ngIRCd send an "authentication PING" when a new client connects, and +register this client only after receiving the corresponding "PONG" reply. +Default: no. +.TP +\fBScrubCTCP\fR (boolean) +If set to true, ngIRCd will silently drop all CTCP requests sent to it from +both clients and servers. It will also not forward CTCP requests to any +other servers. CTCP requests can be used to query user clients about which +software they are using and which versions said software is. CTCP can also be +used to reveal clients IP numbers. ACTION CTCP requests are not blocked, +this means that /me commands will not be dropped, but please note that +blocking CTCP will disable file sharing between users! +Default: no. +.TP +\fBSyslogFacility\fR (string) +Syslog "facility" to which ngIRCd should send log messages. Possible +values are system dependent, 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 +\fBWebircPassword\fR (string) +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. +.SH [SSL] +All SSL-related configuration variables are located in the +.I [SSL] +section. Please note that this whole section is only recognized by ngIRCd +when it is compiled with support for SSL using OpenSSL or GnuTLS! +.TP +\fBSSLCertFile\fR (string) +SSL Certificate file of the private server key. +.TP +\fBSSLDHFile\fR (string) +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 +\fBSSLKeyFile\fR (string) +Filename of SSL Server Key to be used for SSL connections. This is required +for SSL/TLS support. +.TP +\fBSSLKeyFilePassword\fR (string) +OpenSSL only: Password to decrypt the private key file. +.TP +\fBSSLPorts\fR (list of numbers) +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. .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 +\fBName\fR (string) ID of the operator (may be different of the nick name). .TP -\fBPassword\fR +\fBPassword\fR (string) Password of the IRC operator. .TP -\fBMask\fR +\fBMask\fR (string) 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; 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 +\fBName\fR (string) +IRC name of the remote server. +.TP +\fBHost\fR (string) +Internet host name (or IP address) of the peer. .TP -\fBHost\fR -Internet host name of the peer +\fBBind\fR (string) +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. +\fBPort\fR (number) +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 +\fBMyPassword\fR (string) 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 +\fBPeerPassword\fR (string) 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 +\fBGroup\fR (number) Group of this server (optional). -\fBPassive\fR +.TP +\fBPassive\fR (boolean) 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 (boolean) +Connect to the remote server using TLS/SSL. Default: false. +.TP +\fBServiceMask\fR (string) +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] @@ -237,35 +424,75 @@ There may be more than one .I [Channel] block. .TP -\fBName\fR -Name of the channel +\fBName\fR (string) +Name of the channel, including channel prefix ("#" or "&"). .TP -\fBTopic\fR -Topic for this channel +\fBTopic\fR (string) +Topic for this channel. .TP -\fBModes\fR +\fBModes\fR (string) Initial channel modes. .TP -\fBKey\fR -Sets initial channel key (only relevant if mode k is set) +\fBKey\fR (string) +Sets initial channel key (only relevant if channel mode "k" is set). .TP -\fBMaxUsers\fR -Set maximum user limit for this channel (only relevant if mode l is set) +\fBKeyFile\fR (string) +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 (number) +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 +Alexander Barton, .br -Homepage: -.UR http://ngircd.barton.de/ -http://ngircd.barton.de/ -.UE +Florian Westphal, +.PP +Homepage: http://ngircd.barton.de/ .SH "SEE ALSO" .BR ngircd (8) .\"