Log in | Back to darenet.org
Share

DareNET IRCd Configuration/1.5

m (→Admin Block)
(→Connect block)
 
(58 intermediate revisions not shown)
Line 1: Line 1:
__NOTOC__
__NOTOC__
-
This is a reference guide for ircd-darenet 1.4.1+'s configuration file.
+
This is a reference guide for ircd-darenet 1.5.x's configuration file.
-
The configuration format consists of various blocks, each containing name-value pairs, tags and/or string data. It is designed to be easily readable by both human and ircd.
+
The configuration format consists of various blocks, each containing name-value pairs, tags or string data. It is designed to be easily readable by both human ircd.
-
A block consists of a block name, an opening '{' brace, statements, a closing '}' brace, and a ';' semicolon. A statement consists of a name possibly followed by an '=' equals sign and a value, ending with a semicolon. All strings are surrounded by '"' double quotes.
+
A block consists of a name, an opening '{' brace, statements, a closing '}' brace, and a ';' semicolon. A statement consists of a name possibly followed by an '=' equals sign and a value, ending with a semicolon. All strings must be surrounded by '"' double quotes.
A sample block:
A sample block:
Line 15: Line 15:
};</pre></html>
};</pre></html>
-
All elements of the configuration are separated by whitespace, and can be packed on one line, or broken up over several lines. Whitespace is defined as space, tab or carriage return/linefeed. Three form of comments are allowed:
+
All elements of the configuration are separated by whitespace, and can be packed on one line, or broken up over several lines. Whitespace is defined as space, tab or carriage return/linefeed. Three forms of comments are allowed:  
-
* C style single/multi-line
+
<pre>/* C style single/multi-line */
-
* C++ style single-line
+
-
* Shell style single-line
+
-
'''Important notes:''' When the configuration file is parsed, blocks are used in reverse order than how they are listed. This means you should start multiple block definitions with the "fall through", and end with the most detailed. Class {} blocks MUST be specified before anything that uses them. That means they must be defined before client {}, connect {} and operator {}.
+
// C++ style single-line
-
Times / durations are written as:
+
# Shell style single-line
 +
</pre>
-
* A number in seconds (e.g., 60)
+
{{info|text=Blocks are used in the reverse order than how they're listed, when the configuration file is parsed. This means you should start multiple block definitions with the "fall through", and end with the most detailed.}}
-
* 1 hours 30 minutes 10 seconds
+
-
* An arithmetic expression (e.g., 1*60+20)
+
-
 
+
-
Valid units of time:
+
-
 
+
-
* Decade, year, month, week, day, hour, minute, second
+
-
 
+
-
Valid units of size:
+
-
 
+
-
* terabyte / tbyte
+
-
* gigabyte / gbyte
+
-
* megabyte / mbyte
+
-
* kilobyte / kbyte
+
-
* byte
+
-
 
+
-
Sizes and times may be specified as singular or plural.
+
== General block ==
== General block ==
-
{| class="simpletable"
+
{| class="simpletable" width="100%"
|width="250px"|Requirement:
|width="250px"|Requirement:
|REQUIRED
|REQUIRED
|-
|-
|Old conf format equivalents:
|Old conf format equivalents:
-
|M:name:vhost:description::numeric
+
|<code>M:name:vhost:description::numeric</code>
|}
|}
The General block defines information about the server itself. It is required for the server to start.
The General block defines information about the server itself. It is required for the server to start.
-
<html><pre><strong>general</strong> {
+
<html><pre><strong>General</strong> {
     <span class="comment">/* name: the name of our server. */</span>
     <span class="comment">/* name: the name of our server. */</span>
     name = <span class="qstring">"test.area.zone.darenet.org"</span>;
     name = <span class="qstring">"test.area.zone.darenet.org"</span>;
Line 65: Line 48:
     * digit between 0 and 4095, and is not updated on a rehash.
     * digit between 0 and 4095, and is not updated on a rehash.
     */</span>
     */</span>
-
     numeric = <span class="integer"> 999</span>;
+
     numeric = <span class="integer">999</span>;
     <span class="comment">/* vhost: the IP to bind to when we connect outward to other servers.
     <span class="comment">/* vhost: the IP to bind to when we connect outward to other servers.
Line 90: Line 73:
There must be exactly one General block.
There must be exactly one General block.
-
== Admin Block ==
+
== Admin block ==
-
{| class="simpletable"
+
{| class="simpletable" width="100%"
|width="250px"|Requirement:
|width="250px"|Requirement:
|SUGGESTED
|SUGGESTED
|-
|-
|Old conf format equivalents:
|Old conf format equivalents:
-
|A:line1:line2:line3
+
|<code>A:line1:line2:line3</code>
|}
|}
The Admin block defines information that can be retrieved with the <code>/ADMIN</code> command.
The Admin block defines information that can be retrieved with the <code>/ADMIN</code> command.
-
<html><pre><strong>admin</strong> {
+
<html><pre><strong>Admin</strong> {
     location = <span class="qstring">"DareNET - http://www.darenet.org"</span>;
     location = <span class="qstring">"DareNET - http://www.darenet.org"</span>;
     location = <span class="qstring">"Infrastructure Team"</span>;
     location = <span class="qstring">"Infrastructure Team"</span>;
Line 111: Line 94:
Not all lines are required. There may only be one Admin block.
Not all lines are required. There may only be one Admin block.
-
== Class Block ==
+
== Class block ==
-
{| class="wikitable" width="40%" style="font-size: 97%; text-align: left;"
+
{| class="simpletable" width="100%"
-
| Requirement:
+
|width="250px"|Requirement:
-
| SUGGESTED
+
|RECOMMENDED
 +
|-
 +
|Old conf format equivalents:
 +
|<code>Y:class:pingfreq::maxlinks:sendq (clients)</code><br /><code>Y:class:pingfreq:connectfreq:maxlinks:sendq (servers)</code>
|-
|-
-
| Old conf format equivalents:
 
-
| Y:line
 
|}
|}
-
The Class {} blocks define connection classes. All connections to the server are associated with a "connection class", whether they be incoming or outgoing (initiated by the server), be they clients or servers.
+
The Class blocks define connection classes. All connections to the server are associated with a "connection class", whether they be incoming or outgoing (initiated by the server), be they clients or servers.
-
<pre>Class
+
<html><pre><strong>Class</strong> {
-
{
+
    <span class="comment">/* name: a name for the connection class. */</span>
-
  name = "<class>";
+
    name = <span class="qstring">"Users"</span>;
-
  pingfreq = time;
+
-
  connectfreq = time;
+
-
  maxlinks = number;
+
-
  sendq = size;
+
-
  usermode = "+modes";
+
-
};</pre>
+
-
'''Required tokens:''' <code>name, pingfreq, sendq</code>
+
    <span class="comment">/* pingfreq: how often to PING idle connections. */</span>
 +
    pingfreq = 1 minute 30 seconds;
-
'''Optional tokens (client classes only):''' <code>maxlinks, usermode</code>
+
    <span class="comment">/* sendq: send buffer limit (i.e., the amount of data allowed in
 +
    * a client's queue before they are dropped.
 +
    */</span>
 +
    sendq = 100 kilobytes;
-
'''Optional tokens (server classes only):''' <code>connectfreq</code>
+
    <span class="comment">/* maxlinks: the maximum number of connections that may use this
 +
    * class. May be between 0 and 4,000,000,000.
 +
    */</span>
 +
    maxlinks = <span class="integer">100</span>;
-
For connection classes used on server links, maxlinks should be set to either 0 (for hubs) or 1 (for leafs). Client connection classes may use maxlinks between 0 and approximately 4,000,000,000. A maxlinks of 0 means there is no limit on the number of connections using the class.
+
    <span class="comment">/* usermode: an optional list of user modes that should set
 +
    * upon the user while connecting.
 +
    */</span>
 +
    usermode = <span class="qstring">"+iw"</span>;
-
<connect freq> applies only to servers, and specifies the frequency that the server tries to auto connect. Setting this to 0 will cause the server to attempt to connect repeatedly with no delay until the <maximum links> condition is satisfied. This is a Bad Thing(tm). Time can be specified as a number, or by giving something like: 1 minutes 2 seconds, or 1*60+20.
+
    <span class="comment">/* maxchans: the maximum number of channels that clients may join.
 +
    */</span>
 +
    maxchans = <span class="integer">50</span>;
 +
};
-
For connection classes intended for operator use, you can specify privileges used when the Operator {} block (see below) names this class. The local (aka globally_opered) privilege MUST be defined by either the Class or Operator block. It is highly recommended privileges be specified in the operator's Operator {} block, instead of in Class {} blocks.
+
<strong>Class</strong> {
 +
    name = <span class="qstring">"Opers"</span>;
 +
    pingfreq = 2 minutes;
 +
    sendq = 100 kilobytes;
 +
    maxlinks = <span class="integer">10</span>;
 +
    usermode = <span class="qstring">"+iw"</span>;
 +
    whox;
 +
};
-
A "default" class is created internally. This class is used when no other class is specified, but its settings are not useful for most situations. Custom classes are strongly suggested.
+
<strong>Class</strong> {
 +
    name = <span class="qstring">"Server"</span>;
 +
    pingfreq = 3 minutes;
-
There may be multiple Class {} blocks.
+
    <span class="comment">/* connectfreq: this token applies only to servers, and specifies
 +
    * the frequency that the server tries to auto connect. Setting this to 0 will cause a
 +
    * server to attempt to connect repeatedly, with no delay until the maxlinks condition
 +
    * is satisfied (which is not a good thing).
 +
    */</span>
 +
    connectfreq = 5 minutes;
-
'''Example blocks:'''
+
    <span class="comment">/* maxlinks: for server classes, specifies the maximum number of
 +
    * servers to autoconnect to. This should be 0 for hubs, and 1 for leafs.
 +
    */</span>
 +
    maxlinks = <span class="integer">0</span>;
-
Uplinks you are not a hub for:
+
    sendq = 10 megabytes;
-
<c>Class
+
};
-
{
+
-
  name = "Server";
+
-
  pingfreq = 1 minutes 30 seconds;
+
-
  connectfreq = 5 minutes;
+
-
  maxlinks = 1;
+
-
  sendq = 9000000;
+
-
};</c>
+
-
Leaf servers you hub for:
+
-
<c>Class
+
-
{
+
-
  name = "Leaf Server";
+
-
  pingfreq = 1 minutes 30 seconds;
+
-
  connectfreq = 5 minutes;
+
-
  maxlinks = 0;
+
-
  sendq = 9000000;
+
-
};</c>
+
-
All clients:
+
-
<c>Class
+
-
{
+
-
  name = "Users";
+
-
  pingfreq = 1 minutes 30 seconds;
+
-
  sendq = 60000;
+
-
  usermode = "+iw";
+
-
};</c>
+
-
Opers:
+
-
<c>Class
+
-
{
+
-
  name = "Opers";
+
-
  pingfreq = 1 minutes 30 seconds;
+
-
  sendq = 60000;
+
-
  whox = yes;
+
-
};</c>
+
-
== Client Block ==
+
<strong>Class</strong> {
 +
    name = <span class="qstring">"Leaf_Server"</span>;
 +
    pingfreq = 3 minutes;
 +
    connectfreq = 5 minutes;
 +
    maxlinks = 1;
 +
    sendq = 10 megabytes;
 +
};
 +
</pre></html>
-
{| class="wikitable" width="40%" style="font-size: 97%; text-align: left;"
+
For connection classes intended for operator use, you can specify privileges the operator should be granted when the Operator block names the class. The local privilege MUST be defined by either the Class or Operator block. It is highly recommended that most privileges be explicitly specified in the operator's Operator block on DareNET.
-
| Requirement:
+
 
-
| SUGGESTED
+
A "default" class is created internally. This class is used when no other class is specified, but its settings are not useful for most situations. Custom classes are strongly recommended.
 +
 
 +
There may be multiple Class blocks; at least one is recommended.
 +
 
 +
== Client block ==
 +
 
 +
{| class="simpletable" width="100%"
 +
|width="250px"|Requirement:
 +
|RECOMMENDED
|-
|-
-
| Old conf format equivalents:
+
|Old conf format equivalents:
-
| I:line
+
|<code>I:ipmask:passwd:hostmask:port:class</code>
|}
|}
-
To allow clients to connect, they need authorization. This can be done based on hostmask, address mask and/or with a password. With intelligent use of classes and the maxlinks field in the Client {} blocks, you can let in a specific domain, but get rid of all other domains in the same top level, thus setting up some sort of "reverse Kill {} block."
+
The Client blocks define the hosts client connections are allowed from, and places them into classes. While the server will start without a Client block, it will not be usable.
-
<pre>Client  
+
<html><pre><strong>Client</strong> {
-
{
+
    <span class="comment">/* host: resolved user@host mask allowed to connect. This is optional
-
  host = "host";
+
    * if you are using the ip mask to match against. Additionally, if you specify *@loc for
-
  ip = "127.0.0.0/8";
+
    * this field it will match all LOC users.
-
  password = "password";
+
    */</span>
-
  class = "classname";
+
    host = <span class="qstring">"*@*.wirehub.net"</span>;
-
  maxlinks = number;
+
-
};</pre>
+
-
Everything in a Client {} block is optional. If a username mask is specified, it must match the clients username from the IDENT protocol. If a hostmask is given, the client's hostname must resolve and match the hostmask. If a CIDR-style IP mask is given, the client must have an IP matching that range. If maxlinks is given, it limits the number of matching clients allowed from a particular IP address.
+
    <span class="comment">/* ip: unresolved user@ip mask allowed to connect. */</span>
 +
    ip = <span class="qstring">"*@195.86.128.*"</span>;
-
'''Technical Description:'''
+
    <span class="comment">/* password: (optional) password that is required to use this block.
 +
    * This password string is not encrypted.
 +
    */</span>
 +
    password = <span class="qstring">"letMEHin"</span>;
-
For every connectiong client, the IP address is known. A reverse lookup is performed on this IP-number to get the (/all) hostname(s). Each hostname that belongs to this IP-number is matched to <hostmask>, and the Client {} block is used when any matches; the client will then show with this particular hostname. If none of the hostnames match, then the IP-number is matched against the <IP mask ...> field, and if this matches, the Client {} block is used nevertheless and the client will show with the first (main) hostname, if any. If the IP-number does not resolve, then the client will show with the dot notation of the IP-number.
+
    <span class="comment">/* class: the class the user should be placed in. */</span>
 +
    class = <span class="qstring">"Users"</span>;
-
There is a special case for UNIX domain sockets and localhost connections. In these cases, the <IP mask...> field is compared with the name of the server (thus not with any IP-number representation). The name of the server is the one returned in the numeric 002 reply. For example:
+
    <span class="comment">/* maxlinks: if specified, the server will only accept clients when
 +
    * the total number of connections to the network from the same IP number doesn't exceed
 +
    * this number.
 +
    */</span>
 +
    maxlinks = <span class="integer">6</span>;
-
<code>002 Your host is 2.darenet.org[jolan.ppro], running version ...</code>
+
    <span class="comment">/* port: (optional) a port to limit this block to. */</span>
 +
    port = <span class="integer">6660</span>;
 +
};
 +
</pre></html>
-
In this example, "jolan.ppro" is the name used for matching. Therefore, UNIX domain sockets, and connections to localhost, would match this block:
+
The server uses a default deny policy for incoming connections. You need to define at least one Client block if you wish to use your server.
-
<code>host = "*@jolan.ppro";</code>
+
The <code>host</code> and <code>ip</code> fields specify which connections the block matches. The server always performs a DNS and ident lookup for connections. If DNS cannot find a hostname, the IP address is used instead. If ident cannot get a valid reply, "unknown" is used during this state. The client's resolved hostname, IP address, ident reply, and username (from the USER line) are used according to the results of the matches described below.
-
Example blocks:
+
'''Note:''' There is a specify case for UNIX domain sockets and localhost connections. In these cases, the <code>ip / host</code> field is compared with the name of the server, and thus not with any IP number representation. The name of the server is that returned in the numeric 002 reply, example: <code>002 Your host is 2.darenet.org[jolan.ppro]. running version ...</code> In this example, "jolan.ppro" is the name used for matching; therefore, UNIX domain sockets and connections to localhost would match a block containing: <code>host = "*@jolan.ppro";</code>.
-
Prevent unresolved clients from connecting:
+
The <code>host</code> field attempts to match first against the resolved hostname, if available, and then against the IP address. To include the connection's ident reply in the match, use a mask in the form "ident@host". If a client matches, it appears on IRC using its resolved hostname.
-
<c>Client
+
-
{
+
-
  host = "*@*";
+
-
  class = "Users";
+
-
  maxlinks = 5;
+
-
};</c>
+
-
Only accept two connections from dial up accounts that have "dial??.*" as host mask:
+
The <code>ip</code> field attempts to match against the IP address only. An ident may be specified to match against, as well.
-
<c>Client
+
-
{
+
-
  host = "*@dial??.*";
+
-
  class = "Users";
+
-
  maxlinks = 2;
+
-
};</c>
+
-
Allow anyone to connect:
+
'''Note:''' If the ident portion is specified in a mask (i.e., "ident@host" instead of "host"), and no ident reply is received from the client, it will appear on IRC with its username prefixed with a '~' tilde. If the matching mask used only the "host" form, the client's username is not prefixed. If a valid ident reply is received, it is always used and not prefixed.
-
<c>Client
+
-
{
+
-
  host = "*@*";
+
-
  ip = "*@*";
+
-
  class = "Other";
+
-
  maxlinks = 5;
+
-
};</c>
+
-
== motd Block ==
+
You need only specify a <code>host</code> or <code>ip</code> field, not both. If both are used, <code>host</code> is matched against first.
-
{| class="wikitable" width="40%" style="font-size: 97%; text-align: left;"
+
There may be multiple Client blocks; at least one is recommended.
-
| Requirement:
+
 
-
| OPTIONAL
+
== Motd block ==
 +
 
 +
{| class="simpletable" width="100%"
 +
|width="250px"|Requirement:
 +
|OPTIONAL
|-
|-
-
| Old conf format equivalents:
+
|Old conf format equivalents:
-
| T:line
+
|<code>T:hostmask&#124;classnumber:path</code>
|}
|}
-
It is possible to show a different Message of the Day (MOTD) to a connecting client depending on its origin.
+
The Motd blocks allow a different Message of the Day to be shown to connecting clients based on their origin.
-
<pre>motd
+
<html><pre><strong>Motd</strong> {
-
{
+
    <span class="comment">/* host: a hostmask, class number or class name to match against. */</span>
-
  host = "Users";
+
    host = <span class="qstring">"*.jp"</span>;
-
  file = "path/to/motd/file";
+
-
};</pre>
+
-
More than one <code>host = "mask";</code> entry may be present in one block; this has the same effect as one motd {} block for each host entry, but makes it easier to update the message's filename. Additionally, you may specify a the name of a Class {} block to match against in the <host> portion.
+
    <span class="comment">/* file: the path to the MOTD file to be shown (relative to DPATH). */</span>
 +
    file = <span class="qstring">"jp.motd"</span>;
 +
};
 +
</pre></html>
-
Example block:
+
More then one <code>host</code> field may be present in an Motd block.
-
<c>motd
+
There may be multiple Motd blocks.
-
{
+
-
  host = "*@*.jp";
+
-
  file = "japanese.motd";
+
-
};</c>
+
-
== Connect Block ==
+
== Connect block ==
-
{| class="wikitable" width="40%" style="font-size: 97%; text-align: left;"
+
{| class="simpletable" width="100%"
-
| Requirement:
+
|width="250px"|Requirement:
-
| OPTIONAL
+
|OPTIONAL
|-
|-
-
| Old conf format equivalents:
+
|Old conf format equivalents:
-
| C:line, H:line, L:line
+
|<code>C:host:cpassword:name:port:class</code><br /><code>N:host:apassword:name:flags:class</code><br /><code>H:host::name:maxhops</code><br /><code>L:host::mask:depth</code>
|}
|}
-
Connect {} blocks define what servers the server may connect to, and which servers are allowed to connect.
+
The Connect blocks define links to other servers.
-
IRC servers connect to other servers forming a network with a star or tree topology. Loops are not allowed. In this network, two servers can be distinguished: "hub" and "leaf". Leaf servers connect to hubs; hubs connect to each other. Of course, many servers can't be directly classified in either of these categories. Both a fixed and a rule-based decision making system for server links exists to aide ircd in deciding what links to allow, what to let humans do themselves and what links to (forcefully) disallow.
+
<html><pre><strong>Connect</strong> {
 +
    <span class="comment">/* name: the name of the server. */</span>
 +
    name = <span class="qstring">"uplink.darenet.org"</span>;
-
<pre>Connect
+
    <span class="comment">/* host: the host or IP to connect to. If a hostname is used it
-
{
+
    * must mat