The information in this document is provided on the "as is" basis, you are using this information on your own risk. Authors do not take the responsibility for any danger and damage, caused by any misunderstanding or misconception of this documentation, directly or indirectly.
Faerion is an IRC (Internet Relay Chat) daemon, used to run an IRC server. Almost all aspects of its functioning are controlled using a single configuration file, typically - ircd.conf, the content of which is described by this document.
Configuration file contains a number of plain text lines, where each line is a single configuration option. Lines that start with a hash sign ("#") are treated as comments and are skipped. Every line can have up to 1024 bytes of useful information, the rest is skipped. That is more than enough, since no configuration option needs that much data normally.
Historically, ircd.conf has a very strict syntax and could only contain a set of lines beginning with a letter of latin alphabet, a colon and some extra colon-separated parameters. This provides a compact and efficient storage for the configurations. Those lines are usually referred to as K-Lines, M-Lines and so forth, depending on the starting letter. A line of configuration can not be split up (that is, contain carriage return and line feed characters). Faerion allows escaping of the colon sign by prefixing it with a back slash character (thus you can, for example, set a valid URI in your server's description in the M-Line).
While editing your configuration line, it is important to keep in mind that the lines of each type, if many are allowed, are processed upside-down, thus your last K-Line will actually be checked first, and vice-versa. Order of lines of different types does not matter.
Since version 1.17.5, Faerion allows ircd.conf to contain a set of additional parameters, used to override various setting and messages that were previously hard-coded into the daemon binary. These new configuration lines consist of an option name, some amount of white space and the option value (everything up to the end of line, including the trailing spaces - beware). These lines are referred to as "configuration options", to distinguish with "lines".
None of the configuration options, when changed, require the daemon to be restarted. The only thing you should do after editing the configuration file is to rehash your server by either issuing the REHASH command as an IRC Operator, or a `kill -HUP' command as a user that has access to the daemon process.
To check the active values of the options, described below, an IRC Operator can use the INFO command, either locally or forwarded to a remote server. Regular users do not receive this information when using that command.
The value for this option can contain a single word (i.e., it is truncated on the first space character), and holds the name of your network. This is sent within numeric reply 005 to your clients when they successfully connect, and is used as a fake host name for IRC Operators when they set +x user mode on (host masking).
Also, when this option is set, it is checked against all servers that are trying to link to yours. If they provide a different network name, an error message is sent and their connection is closed. Servers from different networks are not accepted. However, if the incoming server does not provide a network name (it is not set in the configuration file, for example), the link is accepted.
By setting this option to a valid URI (an e-mail address) you give your clients a chance to complain when they are denied by a miss-placed K-Line. For example, this might happen when someone is in a hurry and bans a mach wider range of addresses, than it was necessary (IRC Operator guide is not a subject of this document). However, if you trust your operators and do not wish to hear anything from banned clients, it is a good idea to have at least a web page telling them about it - do not leave the users wondering.
When this option is set, your clients receive a notice telling them where to find information about connection problem, when they connect. This notice is sent when the host resolving process starts, which can take very long time for clients that do not have their ISP's DNS configured properly, and impatient clients can think that there is an error with the server.
Typically, this option contains either a web site URL or an email address.
Setting this option enables the so-called "Head-in-Sand" network protection, intended to completely hide the network structure from the regular users. This is useful for protecting your network from impulsive flooders who are targeting servers for personal reasons.
They will also be unable to use the MAP and LINKS commands - intead of the normal reply they will receive a notice containing the web site for information. When a netsplit happens, quit messages will contain a human-readable reason instead of server names.
Nickname based command forwarding is also disabled, with the only exception for WHOIS, but a strict check for target and destination is made. Commands can still be forwarded if there is a dot in the destination (which means that a server mask was specified).
Note that the information about a user's current server is not hidden from oneself - doing so would be not very efficient, because users can easily find what server they are using. However, this leaves a chance for information leakage, since a user can tell others the name of the server.
With this option you can define the default user mode for your clients. For example, specifying the "x" mode here will force your clients to have their hosts masked. Currently, you can only use "x" (host masking), "i" (invisible) and "f" (flood control) in this option. No user mode is set for clients if you skip this option in your configuration.
This option is used for specifying the amount of seconds a client must wait between sequential nickname changes. A single nickname change generates quite a bit of traffic, and is destroying whowas history. It is a good idea to set this to about 30 seconds.
Having this option lets your users receive a notice about the connection process - hostname resolving, and so forth. To disable this behaviour, either remove this option or comment it out. By default, notices are not sent.
Add this option to force your clients to receive Message Of The Day automatically, as soon as they successfully connect. This is a good idea to have an informative message in your MOTD, but some high-traffic servers might wish to save some load during the client connection phase by disabling this. The users who still wish to read the message, will do that manually.
If you are using IRC Services of some favour, you need to define the name of the server they stay on. This is used to secure the things up a bit by forcing messages to services be sent to a specific server, thus not leaving a chance for anyone to steal any sensitive data (typically - passwords) by taking the magic nicknames, in case you have not set the Q-Lines on all of your servers. Obviously, this only works if your clients are using special commands like NICKSERV to access the services. It will not protect against direct private messages sent to a NickServ that was taken over.
If you leave this option undefined, commands like NICKSERV will not be available.
With this option you can override the name of your channel service. If you specify an empty string or don't use this option at all, if defaults to "ChanServ". This option only has a meaning when you define ServicesHost.
With this option you can override the name of your nickname service. If you specify an empty string or don't use this option at all, if defaults to "NickServ". This option only has a meaning when you define ServicesHost.
With this option you can override the name of your memo service. If you specify an empty string or don't use this option at all, if defaults to "MemoServ". This option only has a meaning when you define ServicesHost.
With this option you can override the name of your IRC Operator helper service. If you specify an empty string or don't use this option at all, if defaults to "OperServ". This option only has a meaning when you define ServicesHost.
With this option you can override the directory where the daemon will look for the codepage conversion tables. You should not use the trailing slashes, as the daemon adds them automatically. Details about the codepage files can be found in the Installation documentation.
If you do not use this option in your configuration file, it defaults to "codepage", a subdirectory in your daemon working directory.
This lets you specify the name of the file to log all OPER attempts (both failed and succeeded), which include time, used credentials and identity of the user who attempts to get the privilege.
Under unices, you may set this to "syslog" - Faerion will use the INFO facility. Daemon's process id is also logged, to distinguish between the instances.
Syntax: M:host:bind:description:port
This mandatory line defines how the server will identify itself. There can be only one such line. The fields are:
This is a mandatory line that allows you to set up to three lines of text information that is sent to your clients when they use the ADMIN command. Usually, the fields contain server location, admin nick / real name and contact address. However, there is no fixed standard for that, so it's up to you.
These lines connection clises. They allow you to fine-tune your incoming and outgoing connections, both server and client types. These classes are for use with C-, N-, I- and O-Lines, more on this in later sections. Fields are:
These lines are the ones initially responsible for letting clients connect to your server. So called "client-authorization" lines, they define who may connect, and which connection class they will connect through. I-Lines, like C-, N- and O-Lines refer back to Y-Lines, as they allow connections, and each connection needs to be assigned to a connection class. If you dont provide a connection class, the connection will be governed by the defaults set at compile time, which will most likely be not what you desired. When a client connects to the server, it gives its own information, this information includes username, nick and can include a password, the server then goes through its client-authorization rules (I-Lines) to see if the client fits any of the connection criteria.
The rules for connection on the I-Lines are read from right to left, so if a connection is made, it is made on the right most rule it matches on the line. Also, since the ircd.conf is processed upside down, the server will put the client on the lowest I-Line matching the client information. This means that if the 1st rule the client can connect on matches a connection class (Y-Line) that is 'full' (see above), the client will be rejected, even if there is a line further up in the file that the client matches on that uses a connection class that has room for more clients.
Syntax: I:address:password:host::class
Wildcards ("*") may be used in the mask fields (1 and 3) to allow very broad connection rules. Also in field 1 you can use x.x.x.x/n where n is netmask (from 0 to 32).
If you specify a password, then all clients matching this rule will have to supply it to successfully log in. If you leave the password field empty, and you are using IRC Services (read about the ServicesName option), and clients send a password, it is forwarded straight to NickServ, to authenticate for the used nickname.
These lines provide rules as to who may gain Operator status on your server. O-Lines are much like I-Lines in their operation and syntax. Servers need not have any Operators as the daemon, given well defined connections, can perform all of its functions automatically. Server admins have the ability to `kill -HUP' the daemon process to rehash the config file, removing the need to use the REHASH command (not on a windows platform, though). However, a well running network wants a couple of operators to oversee the users of the server, and make sure users actually enjoy their time on IRC without being continually harrased by troublemakers.
Syntax: O:hostname:password:nickname:flags:class
Passwords themselves are not stored in the configuration file, only their md5 hashes are. However, to authenticate against an O-Line, you will need to use the plain password with the OPER command. To produce a password hash, you will want to use the `md5 -s"password"' command.
Flags are used to give the operators different permission, and can contain the following case-sensitive characters:
These lines define which servers on the network will be able to "hack" modes. This power is usually given only to the network Services, to be able to force channel/user modes. All servers in the network must have their U-Lines set properly. A single misconfigured server will cause all modes to be bounced and will render the services useless.
U-lined servers also have the capability to add AKILL's to your server, AKILLs are much the same as the K-Lines except that they show up marked with capital letter "A" in STATS and can not be removed manually.
These lines are always used in pairs, one will not work without the other. C-Lines define who your server may connect to, while N-Lines define what servers may connect to you.
When two servers connect, they both send eachother the SERVER command to introduce themselves. Along with the information specified in the M-Line, they send a password with the PASS command. C- and N-Lines provide a set of rules governing the connection between servers.
When one server initiates the connection, the other server will check the details of the incomming server against its N-Lines and, if a match is found, the server will reply with its own information using SERVER and PASS commands, which are checked the same way by the initiating party. C-Lines tell the server where to go to make the connection and what to send for the pass command.
What this all means is that for two servers to make a complete connection, they must have both C- and N-Lines to refer to for the other server.
Syntax: C:IP:password:name:port/flags:class
The fields are:
These lines restric access to certain users to your server based on user@host matches and time of the day.
Syntax: K:hostmask:comment:username
Syntax: Z:address_mask
The main purpose of these is also to deny connections. But, unlike K-Lines, these do not deal with users, they deny any TCP connection based on the source address matching. This is very useful when you have a flood of clones connecting to your network.
The main idea behind Z-Lines is that they don't send any data to the connection, don't waste time resolving the host names and so on. The connection is dropped as soon as the daemon received is. This is done to save the overhead of useless traffic, but also means that the legitimate clients that are mistakenly affected by the Z-Line will not receive the information on where to complain, so use this with extra care.
The hostmask parameter can be an exact IP address in the dotted-decimal form, an IP address with the last octet masked by an asterisk, or a netmask of the x.x.x.x/b form.
The list of currently active Z-Lines can be seen using the `STATS K' command, where permanent K-Lines (the ones read from ircd.conf) are marked with a capital letter "Z", manually added lines (using the ZLINE command) are marked with a regular "z".
Syntax: Q:*:*:servername
These lines are used to dissalow operators on certain servers to use commands such as remote KILL, and remote CONNECT, this will effectivly restrict the operators on the server to LocOp priveleges. This is usually only used for test server situations. If a server isn't officially part of the network, they may be temporarily linked and Q-Lined, this means the server can be tested while not posing a threat to the rest of thenetwork. Q-Lines need only be placed on the hub connecting the test server.
The 1st 2 fields are currently unused. A Q-Line placed on a hub connected to the named server will dissalow operators on the server to affect other users and servers.
Syntax: Q:*:reason:nickmask
This form of Q-Lines has the ability to deny certain nicknames to users. If a nickname is Q-Lined, the only people allowed to use those nicknames are IRC Operators. Q-Lines, like most other things in your ircd.conf, are local only, for a nickname to be Q-Lined on a whole network all servers must have a Q-Line for that nick. Q-Lines may also contain comments, these comments are given to the user when they attempt to use the nickname and are asked to choose another.
This is usually a good approach to Q-Line the nicks that are used by the Services, if you're using any.
These lines specify which servers are to behave as leaves, that is, servers that may not have any other servers connected to them. They will only be usefull if your server is a non-leaf (hub) server. Not only can you limit servers to leaves, but you can also specify what tree depth may appear after certain servers. If a server connects but tells your server that it has a larger tree depth behind it than is allowed via your L-Line, the server will be rejected. A limit of 0 will mean the server may only be a leaf. A limit of 1 will mean that only leaf servers may be connected to the L-Lined server when it is connected to your server. You may also use L-Lines to restrict what servers may connect to certain servers while they are connected to your server.
Syntax: L:hostmask:*:name:depth
These lines are similar to L-Lines, except that they define what servers may act as a hub while connected to you. That is, which servers may introduce other servers behind them. You may limit what servers may be connected behind the H-Lined server.
Syntax: H:mask:*:name
These lines will open up ports for client connections and set the default codepage name. You can not use port numbers below 1024.
Syntax: P:host::codepage:port
These lines are used to resolve IP addresses internally, without the use of DNS services.
Syntax: V:address:prefix:suffix
When the server is resolving an address regarding to a V-Line, the masked part of the address is split into octets, prepended with the prefix and appended the suffix part. For example, if you specify a /16 address mask, last two octets of the resolved address will be inserted in a dotted decimal form between the prefix and the suffix.
$Id: ircd.conf.html,v 1.1 2002/07/14 13:08:21 hex Exp $