Log in | Back to darenet.org
Share

DareNET IRCd Configuration/1.5

(→Port Block)
(→Connect block)
 
(46 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
Line 55: Line 38:
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 92: Line 75:
== Admin block ==
== Admin block ==
-
{| class="simpletable"
+
{| class="simpletable" width="100%"
|width="250px"|Requirement:
|width="250px"|Requirement:
|SUGGESTED
|SUGGESTED
Line 102: Line 85:
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 113: Line 96:
== Class block ==
== Class block ==
-
{| class="simpletable"
+
{| class="simpletable" width="100%"
|width="250px"|Requirement:
|width="250px"|Requirement:
|RECOMMENDED
|RECOMMENDED
Line 124: Line 107:
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.
-
<html><pre><strong>class</strong> {
+
<html><pre><strong>Class</strong> {
     <span class="comment">/* name: a name for the connection class. */</span>
     <span class="comment">/* name: a name for the connection class. */</span>
     name = <span class="qstring">"Users"</span>;
     name = <span class="qstring">"Users"</span>;
Line 141: Line 124:
     maxlinks = <span class="integer">100</span>;
     maxlinks = <span class="integer">100</span>;
-
     <span class="comment">/* usermode: an optional list of user modes that should be set
+
     <span class="comment">/* usermode: an optional list of user modes that should set
     * upon the user while connecting.
     * upon the user while connecting.
     */</span>
     */</span>
     usermode = <span class="qstring">"+iw"</span>;  
     usermode = <span class="qstring">"+iw"</span>;  
 +
 +
    <span class="comment">/* maxchans: the maximum number of channels that clients may join.
 +
    */</span>
 +
    maxchans = <span class="integer">50</span>;
};
};
-
<strong>class</strong> {
+
<strong>Class</strong> {
     name = <span class="qstring">"Opers"</span>;
     name = <span class="qstring">"Opers"</span>;
     pingfreq = 2 minutes;
     pingfreq = 2 minutes;
Line 156: Line 143:
};
};
-
<strong>class</strong> {
+
<strong>Class</strong> {
     name = <span class="qstring">"Server"</span>;
     name = <span class="qstring">"Server"</span>;
     pingfreq = 3 minutes;
     pingfreq = 3 minutes;
Line 175: Line 162:
};
};
-
<strong>class</strong> {
+
<strong>Class</strong> {
     name = <span class="qstring">"Leaf_Server"</span>;
     name = <span class="qstring">"Leaf_Server"</span>;
     pingfreq = 3 minutes;
     pingfreq = 3 minutes;
Line 192: Line 179:
== Client block ==
== Client block ==
-
{| class="simpletable"
+
{| class="simpletable" width="100%"
|width="250px"|Requirement:
|width="250px"|Requirement:
|RECOMMENDED
|RECOMMENDED
Line 202: Line 189:
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.
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.
-
<html><pre><strong>client</strong> {
+
<html><pre><strong>Client</strong> {
     <span class="comment">/* host: resolved user@host mask allowed to connect. This is optional
     <span class="comment">/* host: resolved user@host mask allowed to connect. This is optional
-
     * if you are using the ip mask to match against.
+
     * if you are using the ip mask to match against.  Additionally, if you specify *@loc for
 +
    * this field it will match all LOC users.
     */</span>
     */</span>
     host = <span class="qstring">"*@*.wirehub.net"</span>;
     host = <span class="qstring">"*@*.wirehub.net"</span>;
Line 230: Line 218:
</pre></html>
</pre></html>
-
The server uses a default deny policy for incoming connections; at least one Client block must be supplied if you wish to use your server.
+
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.
-
The <code>host</code> and <code>ip</code> tokens specify which connections the block matches. The server always performs DNS and ident lookups for connections. If DNS cannot find a hostname, the IP is used instead. If ident cannot get a valid response, "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.
+
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.
-
Note: There is a special case for UNIX domain sockets and localhost connections. In these cases, the <code><ip mask></code> 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.
+
'''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>.
-
For example: <code>002 Your host is 2.darenet.org[jolan.ppro]. running version ...</code>
+
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.
-
In the above 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>
+
The <code>ip</code> field attempts to match against the IP address only. An ident may be specified to match against, as well.
-
The <code>host</code> token attempts to match first against the resolved hostname if available, then against the IP address. To include the connection's ident response in the match, use a mask in the form "ident@host". If a client matches this token, it appears on IRC using its resolved name.
+
'''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.
-
The <code>ip</code> token attempts to match against the IP address only. An ident may be specified to match against, as well.
+
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.
-
 
+
-
If the matching mask used ident ("ident@host" instead of "host"), and no ident response was received from the client, it appears on IRC with its username prefixed with '~'. If the matching mask used only the "host" form, the client's username is not prefixed. If a valid ident response was received, it is always used (without prefixed), regardless of the mask form.
+
-
 
+
-
Only one of the <code>host</code> and <code>ip</code> tokens is needed; if both are used, host is matched first. For typical configurations, using only the <code>host</code> token with a "*@host" or "ident@host" mask is recommended.
+
There may be multiple Client blocks; at least one is recommended.
There may be multiple Client blocks; at least one is recommended.
Line 252: Line 236:
== Motd block ==
== Motd block ==
-
{| class="simpletable"
+
{| class="simpletable" width="100%"
|width="250px"|Requirement:
|width="250px"|Requirement:
|OPTIONAL
|OPTIONAL
Line 262: Line 246:
The Motd blocks allow a different Message of the Day to be shown to connecting clients based on their origin.
The Motd blocks allow a different Message of the Day to be shown to connecting clients based on their origin.
-
<html><pre><strong>motd</strong> {
+
<html><pre><strong>Motd</strong> {
     <span class="comment">/* host: a hostmask, class number or class name to match against. */</span>
     <span class="comment">/* host: a hostmask, class number or class name to match against. */</span>
     host = <span class="qstring">"*.jp"</span>;
     host = <span class="qstring">"*.jp"</span>;
Line 271: Line 255:
</pre></html>
</pre></html>
-
More then one 'host' entry may be present in an Motd block.
+
More then one <code>host</code> field may be present in an Motd block.
There may be multiple Motd blocks.
There may be multiple Motd blocks.
Line 277: Line 261:
== Connect block ==
== Connect block ==
-
{| class="simpletable"
+
{| class="simpletable" width="100%"
|width="250px"|Requirement:
|width="250px"|Requirement:
|OPTIONAL
|OPTIONAL
Line 287: Line 271:
The Connect blocks define links to other servers.
The Connect blocks define links to other servers.
-
<html><pre><strong>connect</strong> {
+
<html><pre><strong>Connect</strong> {
     <span class="comment">/* name: the name of the server. */</span>
     <span class="comment">/* name: the name of the server. */</span>
     name = <span class="qstring">"uplink.darenet.org"</span>;
     name = <span class="qstring">"uplink.darenet.org"</span>;
Line 294: Line 278:
     * must match the reverse dns of the server.
     * must match the reverse dns of the server.
     */</span>
     */</span>
-
     host = <span class="qstring">"192.168.0.50"</span>;
+
     host = <span class="qstring">"192.168.0.1"</span>;
     <span class="comment">/* password: the password we send and accept. */</span>
     <span class="comment">/* password: the password we send and accept. */</span>
Line 329: Line 313:
== CRule block ==
== CRule block ==
-
{| class="simpletable"
+
{| class="simpletable" width="100%"
|width="250px"|Requirement:
|width="250px"|Requirement:
|OPTIONAL
|OPTIONAL
Line 339: Line 323:
The CRule (connection rule) blocks control ircd-darenet's advanced, real-time rule-based routing decision making system.
The CRule (connection rule) blocks control ircd-darenet's advanced, real-time rule-based routing decision making system.
-
<html><pre><strong>crules</strong> {
+
<html><pre><strong>CRule</strong> {
     <span class="comment">/* server: rules will be applied towards servers matching this mask. */</span>
     <span class="comment">/* server: rules will be applied towards servers matching this mask. */</span>
     server = <span class="qstring">"*.eu.darenet.org"</span>;
     server = <span class="qstring">"*.eu.darenet.org"</span>;
Line 361: Line 345:
== Port Block ==
== Port Block ==
-
{| class="simpletable"
+
{| class="simpletable" width="100%"
|width="250px"|Requirement:
|width="250px"|Requirement:
|REQUIRED
|REQUIRED
Line 371: Line 355:
The Port blocks define where the server will accept connections. At least one port block is required to start.
The Port blocks define where the server will accept connections. At least one port block is required to start.
-
<html><pre><strong>port</strong> {
+
<html><pre><strong>Port</strong> {
     <span class="comment">/* port: the specific port to listen on. */</span>
     <span class="comment">/* port: the specific port to listen on. */</span>
     port = <span class="integer">7325</span>;
     port = <span class="integer">7325</span>;
Line 405: Line 389:
</pre></html>
</pre></html>
-
The mask setting should only contain IP addresses or '*' if used. This does not use DNS in any way, so you cannot use it to allow *.nl or *.uk, for example. Attempting to specify anything other than IP addresses will result in the port allowing connections from anyone (as if you used '*').
+
The <code>mask</code> field should only contain IP addresses (CIDR notation is supported) or '*', if used. This does not use DNS in any way, so you cannot use it to allow *.dk or *.uk, for example. Attempting to specify anything other than IP addresses will result in the port allowing connections from anyone (as if you used '*').
-
If a bind address (vhost) is not specified, the server will listen on all available interfaces for that port.
+
If the <code>vhost</code> field (i.e., bind address) is not specified, the server will listen on all available interfaces for that port.
There may be multiple Port blocks.
There may be multiple Port blocks.
-
== Operator Block ==
+
== Operator block ==
-
{| class="wikitable" width="40%" style="font-size: 97%; text-align: left;"
+
{| class="simpletable" width="100%"
-
| Requirement:
+
|width="250px"|Requirement:
-
| SUGGESTED
+
|SUGGESTED
|-
|-
-
| Old conf format equivalents:
+
|Old conf format equivalents:
-
| O:line
+
|<code>O:host:password:name:flags:class</code><br /><code>o:host:password:name:flags:class</code>
|}
|}
-
The Operator {} block defines a server operator. Oper status grants some special privileges to a user, like the power to make the server break or (try to) establish a connection with another server. and to "kill" users off the network.
+
The Operator blocks define server operators. One or more of these blocks is recommended if you intend to maintain your server.
-
More than one host = "mask"; entry may be present in one block; this has the same effect as one Operator block for each host entry, but makes it easier to update operator nicks, passwords, classes, and privileges.
+
<html><pre><strong>Operator</strong> {
 +
    <span class="comment">/* name: the oper's username. */</span>
 +
    name = <span class="qstring">"johndoe"</span>;
-
There may be multiple Operator {} blocks.
+
    <span class="comment">/* host: the user@host/IP mask required for this operator. CIDR
 +
    * notation is supported. Multiple host="" lines are supported.
 +
    */</span>
 +
    host = <span class="qstring">"god@*"</span>;
 +
    host = <span class="qstring">"*@127.0.0.1"</span>;
-
<pre>Operator
+
    <span class="comment">/* password: the password required to oper. By default, the password is
-
{
+
    * hashed using the system's native crypt() function. Other password
-
  name = "opername";
+
    * mechanisms are available; the umkpasswd utility located in the ircd
-
  host = "host/IP mask";
+
    * directory can hash passwords using those mechanisms. If you use a
-
  password = "encryptedpass";
+
    * password format that is not generated by umkpasswd, ircd-darenet will
-
  flags = "oper flags";
+
    * not recognize the oper's password.
-
  class = "classname";
+
    */</span>
-
  local = no;
+
    password = <span class="qstring">"/home/irc/keys/johndoe.key"</span>;
-
  snomask = "snomask";
+
-
  display_mode = yes;  routing = yes;  routeinfo = yes;
+
-
};</pre>
+
-
'''Required tokens:''' <code>name, host, password, flags</code>
+
    <span class="comment">/* flags: misc options for the oper. */</span>
 +
    flags = <span class="qstring">"OAWInFR"</span>;
-
'''Optional tokens:''' <code>class, snomask</code>
+
    <span class="comment">/* snomask: (optional) specific server notice mask on oper up. If this
 +
    * is specified, an oper will not be given sno_default.
 +
    */</span>
 +
    snomask = <span class="qstring">"+cegGiKorRs"</span>;
-
By default, the password is hashed using the system's native crypt() function. Other password mechanisms are available; the umkpasswd utility located in the ircd directory can hash passwords using those mechanisms. If you use a password format that is NOT generated by umkpasswd, ircd-darenet will not recognize the oper's password. If you want to use a non-encrypted password, prefix the password with $PLAIN$ (e.g., "$PLAIN$aPplE123"). NOTE: Plain passwords are not allowed on DareNET.
+
    <span class="comment">/* privileges: (optional) you can specify privileges an oper will be
 +
    * explicitly granted (or denied) upon opering. Any privileges defined
 +
    * will override any privilege settings that may be present in the class
 +
    * block specified above, and the default setting for those privileges.
 +
    */</span>
 +
    local = no;    routing = yes;    routeinfo = yes;
 +
};
 +
</pre></html>
-
A SSL client certificate fingerprint can be used in place of a password. To use this method, specify the fingerprint as the password, and add the S flag to the blocks oper flag string. This will allow the oper to simply use "/OPER opername" to oper, provided they are connected using SSL and have a matching certificate fingerprint.
+
The <code>name</code> and <code>password</code> fields match the parameters of the <code>OPER</code> command. To authenticate as an IRC operator, a client must match one of the <code>host</code> fields, which may be a resolved hostname or IP address.
-
If you want to use a even more secure password authentication system then generate a 1024bit RSA key, specify the path to the key as the password and add R as the oper flag. This will use the /CHALLENGE system instead of /OPER. See doc/challenge.txt for more information.
+
To use an unencrypted password, prefix the password with '$PLAIN', e.g., "$PLAIN$aPpLe".
-
Note that the <connection class> is optional, but omitting it puts the oper in class "default". which usually only accepts one connection at a time. If you want users to be able to /OPER more than once per block, then use a connection class that allows more than one connection.
+
If you want to use a more secure password authentication system, generate a 1024bit RSA key, and specify the path to the key as the password (as shown in the example above), and add 'R' to the <code>flags</code> field. This will use the <code>/CHALLENGE</code> system instead of <code>/OPER</code>. See doc/challenge.txt for more details.
-
Once you /OPER, your connection class changes no matter where you are or what your previous connection class was. If the defined connections class is Opers for the Operator {} block, then your new connection class is Opers.
+
A client may also use their SSL client certificate fingerprint to authenticate as an IRC operator. To use this method, specify the client's certificate fingerprint as the password, and add 'S' to the <code>flags</code> field.
-
'''Privileges:'''
+
Only one password authentication method may be used at a time. That is, you cannot use <code>CHALLENGE</code> and SSL client certificate fingerprint at the same time.
-
Operator privileges may be specified within the Operator {} block itself. A privilege defined for a single operator will override any privilege settings that may be present in the specified Class {} block, and the default setting.
+
There are currently 9 different oper flags:
 +
* o - Local operator
 +
* O - Global operator
 +
* A - Server administrator
 +
* r - This operator block may be used from remote servers
 +
* W - Allowed to set user mode +W
 +
* I - Allowed to set user mode +I
 +
* n - Allowed to set user mode +n
 +
* F - Allowed to set user mode +F
 +
* S - Use SSL client certificate fingerprint to <code>/OPER</code>
 +
* R - Use <code>/CHALLENGE</code> password authentication system.
 +
* j - Allowed to use juped nicknames.
-
NOTE: On DareNET, adding privileges you have not been authorized to your operator block may result in it being removed during periodic audits and/or the server being juped.
+
The <code>class</code> field specifies the connection class the client will be placed in, regardless of their previous connection class. If not specified, the default class is used; see the Class block description for details.
-
For a list of all supported privileges, go [[Operator Privileges|here]].
+
There may be multiple Operator blocks.
-
'''Oper flags:'''
+
== UWorld block ==
-
There are currently 9 different oper flags:
+
{| class="simpletable" width="100%"
 +
|width="250px"|Requirement:
 +
|OPTIONAL
 +
|-
 +
|Old conf format equivalents:
 +
|<code>U:server:jupednicks:*</code>
 +
|}
-
* o - Local Operator
+
The Uworld block defines "U-lined" servers, which are allowed to do special network things. Used for network services.
-
* O - Global Operator
+
-
* A - Server Administrator
+
-
* r - Operator {} block an be used from remote servers
+
-
* W - Allowed to set user mode +W (whois notice)
+
-
* I - Allowed to set user mode +I (hide idle)
+
-
* n - Allowed to set user mode +n (hide channels)
+
-
* S - Use SSL client certificate fingerprint to /OPER
+
-
* R - Use /CHALLENGE instead of /OPER
+
-
* j - Allowed to use juped nicknames
+
-
* F - Allowed to set user mode +F (flood exempt)
+
-
Note that you need at least an o or O flag for your block. Additionally, you cannot specify <code>*@*</code> in the host field.  
+
<html><pre><strong>UWorld</strong> {
 +
    <span class="comment">/* name: the