DareNET IRCd Configuration

Revision as of 21:05, 5 May 2009

IRCds of ircd-darenet 1.2.x's generation have an annoying configuration file format where every line has a prefix that identifies what it's for and then a fixed number of fields that the configuration options need to be crammed into. This is hard to read, very unnatural, and can be difficult to extend. Starting with ircd-darenet 1.3.x, we will begin to utilize a bind-style configuration format that looks more like:

BlockName
{
  setting = number;
  setting2 = "string";
  setting3 = yes;
};

Comments will continue to start with a hash(#) and go to the end of the line. Whitespace(space, tab or carriage return/linefeed) are ignored and may be used to make the configuration more readable. In fact, we recommend you use utilizie whitespace -- don't cram everything together, as you only make it more difficult for others to read/edit.

Note: Configuration file crash bug:

This new configuration file format also 'fixes' a known bug with early ircu versions, and consequently ircd-darenet pre 1.3.x, as detailed here.

Order of blocks:

When the ircd puts the configuration lines into practice, it parses them backwards. That is, it uses the blocks exactly in reverse than how they are listed in the configuration file. This means that you should start with Client {} blocks with the "fall through", most vanilla and end with the most detailed.

Other notes:

There is a difference between the "hostname" and "server name" of the machine that the ircd is run on. For example, the host can have an FQDN of "deviant.nitemare.name", and "deviant.ca.us.darenet.org" as its server name. A "server mask" is something like "*.us.darenet.org", which would be matched by "deviant.ca.us.darenet.org" but not by "technologic.uk.eu.darenet.org".

General Block

The General {} block defines some information about the server itself.

General 
{
  name = "servername";
  vhost = "ipv4vhost";
  description = "description";
  numeric = numericnumber;
};

<virtual host> must contain either a * or a valid IPv4 address in dotted quad notation (e.g. 127.0.0.1). The address MUST be the address of a physical interface on the host. This address is used for outgoing connections only; see Port {} blocks for listener virtual hosting. If in doubt what to put here, use the IP of your primary interface here.

Note that <server numeric> must be unique on the network the server is running, and may be between 0 and 4095. It is not updated on a rehash. If linking to DareNET, you should use the numeric assigned to you by the Server Management team.

Example block:

<source lang="perl">General {

 name = "servername.area.zone.darenet.org";
 description = "DareNET Client Server";
 vhost = "127.0.0.1";
 numeric = 10;

};</source>

Admin Block

The Admin {} block defines information that can be retrieved with the /ADMIN command.

Admin 
{
  Location = "string 1 here";
  Location = "string 2 here";
  Contact = "string 3 here";
};

Example block:

<source lang="perl">Admin {

 Location = "DareNET";
 Location = "Server Management Team";
 Contact = "<routing@darenet.org>";

};</source>

Class Block

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.

Class
{
  name = "<class>";
  pingfreq = time;
  connectfreq = time;
  maxlinks = number;
  sendq = size;
  usermode = "+modes";
};

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.

<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.

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.

Example blocks:

Uplinks you are not a hub for: <source lang="perl">Class {

 name = "Server"
 pingfreq = 1 minutes 30 seconds;
 connectfreq = 5 minutes;
 maxlinks = 1;
 sendq = 9000000;

};</source> Leaf servers you hub for: <source lang="perl">Class {

 name = "Leaf Server"
 pingfreq = 1 minutes 30 seconds;
 connectfreq = 5 minutes;
 maxlinks = 0;
 sendq = 9000000;

};</source> All clients: <source lang="perl">Class {

 name = "Users"
 pingfreq = 1 minutes 30 seconds;
 sendq = 60000;
 usermode = "+iw";

};</source> Opers: <source lang="perl">Class {

 name = "Opers"
 pingfreq = 1 minutes 30 seconds;
 sendq = 60000;
 whox = yes;

};</source>

Client Block

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."

Client 
{
  host = "host";
  ip = "127.0.0.0/8";
  password = "password";
  class = "classname";
  maxlinks = number;
};

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.

Technical Description:

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.

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:

002 Your host is 2.darenet.org[jolan.ppro], running version ...

In this example, "jolan.ppro" is the name used for matching. Therefore, UNIX domain sockets, and connections to localhost, would match this block:

host = "*@jolan.ppro";

Example blocks:

Prevent unresolved clients from connecting: <source lang="perl">Client {

 host = "*@*";
 class = "Users";
 maxlinks = 5;

};</source>

Only accept two connections from dial up accounts that have "dial??.*" as host mask: <source lang="perl">Client {

 host = "*@dial??.*";
 class = "Users";
 maxlinks = 2;

};</source>

Allow anyone to connect: <source lang="perl">Client {

 host = "*@*";
 ip = "*@*";
 class = "Other";
 maxlinks = 5;

};</source>

motd Block

It is possible to show a different Message of the Day (MOTD) to a connecting client depending on its origin.

motd
{
  host = "Users";
  file = "path/to/motd/file";
};

More than one host = "mask"; 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.

Example block:

<source lang="perl">motd {

 host = "*@*.jp";
 file = "japanese.motd";

};</source>

Connect Block

Connect {} blocks define what servers the server may connect to, and which servers are allowed to connect.

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.

Connect
{
  name = "servername";
  host = "hostnameORip";
  password = "passwd";
  port = portno;
  class = "classname";
  maxhops = 2;
  hub;
  leaf = no;
  autoconnect = no;
};

The "port" field defines the default port the server tries to connect to if an operator uses /CONNECT without specifying a port. This is also the port used when the server attempts to auto-connect to the remote server. You may tell ircd-darenet to not automatically connect to a server by adding "autoconnect = no;"; the default is to auto connect.

The maxhops field causes an SQUIT if a hub tries to introduce servers farther away than that; the element 'leaf;' is an aliad for a maxhops of 0. The hub field limits the names of servers that may be introduced by a hub; the element 'hub;' is an alias for hub = "*";.

Example block:

Our primary uplink: <source lang="perl">Connect {

 name = "servername.hub.darenet.org";
 host = "1.2.3.4";
 password = "passwd";
 port = 7325;
 class = "Server";
 hub;

};</source>

CRULE Block

For an advanced, real-time rule-based routing decision making system, you can use the crule {} blocks. For more information, see doc/readme.crules. If more than one server mask is present in a single rule, the rule applies to all servers.

Using all = yes; makes the rule always apply; otherwise, it only applies to auto connects.

CRULE 
{
  server = "servermask";
  rule = "connectrule";
  all = yes;
};

Example blocks:

<source lang="perl">CRULE {

 server = "*.use.darenet.org";
 rule = "connected(*.us.darenet.org)";

};</source>

Recommended for all leafs: <source lang="perl">CRULE {

 server = "*";
 rule = "directcon(*)";

};</source>

Operator Block

Inevitably, you have reached the part about "IRC Operators." 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.

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.

Operator
{
  host = "host/IP mask";
  name = "opername";
  password = "encryptedpass";
  flags = "oper flags";
  class = "classname";
};

You can also set any operator privilege 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.

By default, the password is hashed using the system's native crypt() function. Other password mechanisms are available; the umkpasswd utility from 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 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.

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.

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.

There are currently 8 types of flags:

• o - Local Operator
• O - Global Operator
• A - Server Administrator
• r - O:Line can 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)
• R - Use /CHALLENGE instead of /OPER

Note that you cannot use the o, O and A flags at the same time. You may only specify one of the three. Additionally, you cannot specify *@* in the host field.

Example block: <source lang="perl">Operator {

 name = "JoeOper";
 host = "*joe@*.uu.net";
 password = "/home/irc/keys/joeoper.key";
 flags = "OrWInR";
 class = "Opers";
 local = no;
 kill = yes;

};</source>

UWorld Block

UWorld {} blocks allow a server to broadcast any mode change (without regard to TimeStamps), among other things.

UWorld 
{
  name = "relservername";
};

You may have have more than one name listed in each block.

Note, these lines must be the same on every single server; otherwise, results may be disastrous.

Example block:

<source lang="perl">UWorld {

 name = "services.darenet.org";
 name = "statistics.darenet.org";

};</source>

NickJupe Block

It is possible to "jupe" nicknames, so that users may not use them. This also prevents opers from using them. You may also specify wildcards of * and ?.

NickJupe
{
  nick = "comma separated list of nicks";
};

Example block:

<source lang="perl">NickJupe {

 nick = "A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z,{,|,},~,-,_,`";
 nick = "login,darenet,protocol,pass,newpass";
 nick = "ChanS?rv,NickS?rv,MemoS?rv,HelpS?rv,OperS?rv,BotS?rv,RootS?rv,StatS?rv,SpamS?rv";
 nick = "oper,operator,admin,administrator,network,global,staff";

};</source>

Kill Block

While running your server, you will most probably encounter individuals or groups of person that you do not want to have access to your server. For this purpose, ircd-darenet understands Kill {} blocks. There are also known as K-lines, by virtue of the former config file format.

Kill
{
  host = "user@host";
  reason = "The reason the user will see";
  klineprompt;
  name = "mark";
};

If klineprompt; is present, users may bypass the ban by using Login-on-Connect (LOC). You can also mark clients by using name = "mark here";

Kill
{
  realname = "realname here";
  reason = "The reason the user will see";
};

It is also possible to ban based on username.

Kill
{
  username = "username here";
  reason = "The reason the user will see";
};

It is also possible to use a file as comment for the ban, using.

Kill
{
  host = "user@host";
  file = "path/to/file/with/reason/to/show";
};

The file can contain for example, a reason, a link to the server rules and a contact address. Also, note the combination of username and host in the host field. IP-based Kill {} blocks apply to all hosts, even if an IP address has a properly resolving host name.

Additionally, you may specify a hostmask prefixed with $V to indicate a match should be performed against the CTCP version of the user rather han the host/IP.

Kill
{
  version = "string";
  reason = "reason here";
};

Example blocks:

<source lang="perl">Kill {

 host = "*@*.aol.com";
 reason = "Due to abuse, AOL users must login with their DareNET account to connect.";
 klineprompt;

};</source>

<source lang="perl">Kill {

 host = "192.168.*";
 reason = "Monkeys.";

};</source>

<source lang="perl">Kill {

 username = "sub7";
 realname = "s*7*";
 reason = "You are infected with a Trojan";

};</source>

<source lang="perl">Kill {

 username = "sub7";
 realname = "s*7*";
 reason = "You are infected with a Trojan";

};</source>

Except Block

Except {} blocks can be used to exempt a user from Kill {} blocks, GLINEs, ZLINEs, SHUNs, spam filters, IDENT_CHALLENGE and LIST delays.

Except
{
  mask = "<mask>";
  flags = "<flags>";
};

<mask> is an ident@ip/host/cidr mask that is to match the user to exempted. <flags> is one or more of the following flags to specify what the exempt is to match.

• k - Except affects Kill {} blocks.
• g - Except affects GLINEs.
• z - Except affects ZLINEs.
• s - Except affects SHUNs.
• S - Except affects spam filters.
• L - Except affects LIST delays.
• i - Except affects ident challenges (see IDENT_CHALLENGE feature).

Example block:

<source lang="perl">Except {

 host = "*@*.darenet.org";
 flags = "kgzsL";

};</source>

Command Block

Command {} blocks aim to improve the generic IRC users ability to use network services. Each block sets up a /<service> alias so that users may type that instead of a full /msg command. Some might argue this is a bit more secure as well :)

Command
{
  cmd = "<alias name>";
  service = "<target>";
  prefix = "<anything to prepend to the message>";
};

If prefix = ""; is given, then ircd-darenet will prefix the specified string to whatever the user inputs before sending it to the service.

Example blocks:

<source lang="perl">Command {

 cmd = "AUTH";
 service = "NickServ@services.darenet.org";
 prefix = "AUTH";

};</source>

<source lang="perl">Command {

 cmd = "NICKSERV";
 service = "NickServ@services.darenet.org";

};</source>

Forward Block

Forward {} blocks enable the server to forward any messages which are prefixed and specific with a Forward {} block. This allows users to use Services' fantasy commands without a service client being in the channel (provided the channel is registered). This also removes the need for ChanServ to monitor channel traffic (e.g. allowing the use of umode +d).

Forward
{
  "<prefix" = "<server>";
};

Example block:

<source lang="perl">Forward {

 "." = "services.darenet.org";
 "?" = "services.darenet.org";

};</source>