In order to get UnrealIRCD up and running, you need to create a configuration file. First of all: Creating your first unrealircd.conf will take time (say, 15-60 minutes). Creating a good unrealircd.conf will take even more time. You should not rush to get the IRCd booted, but rather go through things step-by-step. If you have any problems, check your syntax, check this manual and check the FAQ before asking for help/reporting a bug.
There is a good example configuration file in the docs-Directory of the Unreal4 source. But we recommend you to read this manual through entireley before starting the configuration. In fact we will eventually refuse to give you support, if you ask questions that could be answered easily by consulting the documentation.
Configuration of UnrealIRCd takes place by editting a configuration file unrealircd.conf, which is to be located in the configuration directory you specified during running configure. You can copy the example configuration file from docs/unrealircd.conf.example to there and start editing.
The new system uses a block-based format. Each entry, or block, in the new format has a specific format. The format works like:
<block-name> <block-value> {
<block-directive> <directive-value>;
};
<block-name> is the type of block, such as me, or admin. <block-value> sometimes specifies a value, such as /oper login, but other times it will be a sub-type such as in ban user.
<block-directive> is an individual variable specific to the block, and <directive-value> is the Associated value. If <directive-value> contains spaces, or characters that represents a comment it must be contained in double quotes. If you want to use a quote character inside a quoted string use \” and it will be understood as a quote character.
A <block-directive> can have directives within it, if that’s the case it will have it's own set of curly braces surrounding it. Some blocks do not have directives and are specified just by <block-value>, such as include. Also note that there is no set format, meaning the whole block can appear on one line or over multiple lines. The format above is what is normally used (and what will be used in this file) because it is easy to read.
Note: the configuration file is currently case sensitive so BLOCK-NAME is not the same as block-name. There is a special notation used to talk about entries in the config file. For example, to talk about <directive-name> in the example above, you'd say <block-name>::<block-directive>, and if that directive has a sub block you want to reference, you would add another :: and the name of the sub directive.
To talk about an unnamed directive you would do <block-name>:: which would in this case mean <block-value>, or it could be an entry in a sub block that has no name.
Three types of comments are supported:
# One line comment
// One line comment
/* Multi line
comment */
Syntax:
server {
name "irc.TestNET.local";
description "a meefy irc server";
network "TestNET";
networkemail "email@that.is.used.on.k-lines.etc.com";
};
This tag indicates the servername of your server, a description for your server, and your network name. The network name will be given to clients when they connect, and is used by clients such as mIRC to determine which 'perform' should be run. You may only have one server:: tag.
Syntax:
admin {
name "Johnny English";
nick "JohnnyE";
email "JohnnyE@TestNET.org";
};
This tag is used to specify the administrative details of your server, shown when the /ADMIN command is typed by a user.
Syntax:
bind {
address "12.45.67.89";
port "6667-6669,7000";
type "(servers|clients)";
transport "";
};
The bind:: tag indicates the ports which your server should listen on.
Indicates what IP the following ports should be bound to. This must not be a hostname. If this is an IPv4-only server, leaving this blank will let UnrealIRCD use all available IPv4 interfaces. In case you enabled IPv6 during configure, it will instead bind to all available IPv6 interfaces and you will need to specify every IPv4 address by hand.
Indicates what Ports should be bound. Otherwise it is valid to specify single ports or port ranges like this:
bind {
...
port "6667,6668,6669";
...
};
or like this:
bind {
...
port "6669-7001";
...
};
Specifies if this port may accept connections from servers and/or clients. If this option is ommitted it is assumed that both classes may be allowed to connect. Otherwise only the specified class, either servers or clients, is allowed to use the specified bind - configuration.
The bind configuration can make use of encrypted and compressed communication. You may specify one of the following values to this option:
Please note that if you specify one of these options and your counterpart does not support it, then you will not be able to establish a connection.
If you have built UnrealIRCd to support IPV6 connections, you may bind either of an IPV4 or an IPV6 address here by specifying it as the address. Note that if your server is built as an IPV6 server then if you leave the address blank, all IPV6 addresses on your server will be bound, but no IPV4 addresses will be bound. If you do this you must then manually specify any IPV4 addresses you also want to bind to.
Syntax:
power {
diepass "blub";
restartpass "blub";
pause 2;
};
This tag specifies the passwords needed for /DIE and /RESTART. The pause variable indicates how many seconds to wait after the 'server is shutting down' notice to wait before actually terminating the server. You may have only one of these tags, and this tag is non-optional. By default in some configurations (including Win32) this is commented by default as leaving a default value is a security risk. Please ensure you set this tag appropriately.
It is possible to include other files in the configuration file.
Syntax:
include "filename";
Syntax:
connect {
allow "1.2.3.0/24";
password "blahblah";
timeout "10";
flood "5";
threshold "8";
pingfreq "120";
sendq "99999";
revcq "696969";
localmax "3";
globalmax "3";
port "6660";
};
These block indicates that you wish to allow or deny clients from connecting to your irc server. The default, if none of these are defined, is to deny access to everyone.
Important note: Please note that connect tags are read from top to bottom, the earier tags having precedence over the later ones, so if you deny a wide mask first, this takes precedence over a later tag which may allow the users.
Either allow or deny is required. Must not be used together. The value of this is used to define an ip mask that is allowed or denied to connect. IP masks may be specified in CIDR-notation (e.g. 192.168.2.0/24) or in wildcard format (192.168.2.*). You cannot use hostnames in the allow or deny setting, as the state is applied before the user's DNS has been resolved.
Used to specify an optional password, to indicate the users should be allowed access but only if they specify the correct server password when connecting.
The timeout variable indicates how long the server will wait for the user to register when they connect. If there is no registration within timeout seconds, the connection is dropped, which stops malicious users holding open connections to your server which they do not intend to use. This is seperate from PING checks.
The flood variable indicates how many lines may build up in the users sendq in connect::treshould seconds, before they are disconnected for flooding.
You may optionally include the pingfreq variable as shown above, which indicates how often connections to this group are pinged to check their state. If you do not include this variable, the default of 120 seconds is used.
Used to specify the maximum sendq/recvq size (Recommended: See Whats SendQ/RecvQ) in bytes. It is recommended, although not enforced, that you should never set your sendq size to less than 8k. Send Queues are dynamically allocated and can grow as needed up to the maximum size specified.
The optional recvq value is the maximum size which users in this group may grow their receive queue to. This is recommended to be kept pretty low compared to the sendq, as users will always receive more than they send in normal circumstances. The default if not specified is 4096.
Attempting to receive more than “sendq” bytes or sending more then “recvq” bytes from/to the server results in being disconnected from the ircd.
The localmax and globalmax values can be used to enforce local and global session limits on connections. The session limits are counted against all users, but applied only to users within the class. For example, if you had a class 'A' which has a session limit of 3, and a class 'B' which has a session limit of 5, and somehow, two users managed to get into class B which also match class A, there is only one connection left for this IP now in A, but if they can connect again to B, there are three. You get the idea (i hope). #
The optional port value determines which port the connect tag is handling. If left out the connect tag covers all bound ports else only incoming connections on the specified port will match.
You may want to read Defining Opers first, which is a comprehensive introduction to the new Oper definition model.
Syntax:
class {
name "RestartCommands";
commands "DIE RESTART";
};
The class - Block is used to define classes, which is a named group of one or more commands which may be used to build an oper type. The commands you place in these classes are arbitary, you are not forced to place for example all your services commands together, or group kline with kill, in short, you can create any grouping you wish. You may have as many of these tags as you want. Instead of placing command you can place a '*' (without the quotes) which covers all possible commands (Use with care!).
Example:
class {
name "Everything";
commands "*";
};
Syntax:
type {
name "NetAdmin";
classes "Restart HostCloak Admin";
host "netadmin.TestNET.local";
};
These defines a type - Block, which is a named group of one or more classes. When this type of oper successfully gains their permissions, they will gain the hostname specified by the host variable (if defined – if this field is not defined, the host will be unchanged on oper-up), and will have access to all the commands given in all of their classes. You may have as many of these tags as you want.
Type names can not include a space. If you wish for an type name to display with a space use a _ in the configuration.
Syntax:
oper "name" {
password "pass";
host "hostmask@of.oper"
fingerprint "hexsequenc";
type "oper type";
};
These defines actual opers. Each oper may have only one oper type defined by the type variable. You may enter the same tag twice with different hosts, to make an oper with more than one hostname, or, you may seperate multiple hostnames with spaces
Example for multiple hosts:
oper "testoper" {
password "somepassword";
host "foo@bar.local test@localhost";
fingerprint "hexseqenc";
type "Netadmin";
};
Defines the password for the operator. It must be in plaintext, unless you load either the m_md5 module or the m_sha256 module (see Modules along with m_oper_hash. You can use mkpasswd to create the hash.
Defines one or more hostnames that should be able to use this login. Multiple hostnames can be seperated with spaces.
ToDo
This must correspond to a defined type. Please note that type IS case sensitive, if you fail to correctly set this, your oper command WILL fail.
Syntax:
files {
motd "/path/to/motd";
rules "/path/to/rules";
};
This tag, which you must not be defined more then once in your config file, specifies the pathname to the message of the day file (which is just a plain text file) and to the rules file displayed when /RULES is typed. The path may be specified relative to the configuration directory, or it may be a full pathname from the root of the filesystem.
Syntax:
loadmodule "m_foo.so";
Modules are a very important part of unrealircd. In fact you may need to load some of them in order to get an ircd as you used to have in unrealircd3. You may have a look at the provided example configuration, cause it contains a list of module that are typical for an unrealircd installation. There may be as many of these directives as you wish, and all modules will be looked for in the modules directory you specified when running ./configure.
Syntax:
options {
prefixquit "Quit: ";
loglevel "debug";
netbuffersize "10240";
maxwho "32";
noservices "no";
allowhalfop "yes";
moduledir "/path/to/modules";
somaxconn "128";
userstats "oclgk";
customversion "";
maxtargets "20";
hidesplits "no";
hidewhois "";
flatlinks "no";
hideulines "no";
nouserdns "no";
syntaxhints "no";
cyclehosts "yes";
ircumsgprefix "no";
announcets "yes";
hostintopic "yes";
announceinvites "yes";
quietbursts "no";
hidekills "no";
exemptchanops "";
morronbanner "";
};
The prefixquit value is a value which is placed before every quit message. It has multiple uses, the primary one being to prevent spoofing of kill messages.
The loglevel tag specifies the logging level. The usual setting is default. Only use verbose or debug if you are debugging a module. verbose and debug can disclose sensitive information and also generate very huge logs, and should never be used on a production network. The loglevel sparse and none which are below default log less details to the log, which you might find useful if you are low on disk space or quota.
ToDo: Describe the order of the loglevel (which one logs the less, which one the most? which exactly do exist?)
The netbuffersize variable defines the size of the buffer which receives data from clients. This is in complement to the per-connect-group flood limits. If you for example set this to 10240 (10k) then if a user sends more than 10k at once, and the server receives more than 10k of data in one recv() call, the user will be disconnected from the server for flooding. Increasing the netbuffersize increases performance, but takes more memory.
The loglevel tag specifies the logging level. The usual setting is default. Only use verbose or debug if you are debugging a module. verbose and debug can disclose sensitive information and also generate very huge logs, and should never be used on a production network. The loglevel sparse and none which are below default log less details to the log, which you might find useful if you are low on disk space or quota.
The noservices variable is used on networks which do not have services and will never have services. If you set this variable to 'yes', the first user into every channel is transparently given +q, if the m_chanprotect module is loaded, in the same way the first user into a channel is transparently given +o. This means that founders exist to give out +a etc, when the correct modules are loaded, without needing services to grant the initial +q. Please note that in this situation there may only ever be one channel founder, and when the channel empties and its channel record is destroyed, record of who the founder is is lost as well. This is suited well for networks whose policies do not account for channel or nickname ownership. If you set this variable to 'no', the ircd will operate in the same manner as unrealircd or bahamut, only giving +q when a server sends an SAMODE for it.
This option when set to on, provides users with the modes +q or +a the prefixes ~ or & used in unreal. If off, the prefixes will not be shown. This is only useful on networks running the m_chanprotect module.
When this options is on, users with the +q or +a have the option to remove the mode from themselves. The default setting is to not enable this feature as it allows even the founder to take away their founder status without using services.
This defines the maximum number of sockets that may be waiting in the accept queue. This usually allows the ircd to soak up more connections in a shorter space of time when increased but please be aware there is a system defined maximum value to this as for the maximum number of file descriptors. Some systems may only allow this to be up to 5 while others such as FreeBSD will default to a much nicer 128. If this value is omitted, the system defined SOMAXCONN is used in its place.
This allows a defined softlimit to be set on the server. This can not be higher than the ./configure limit, but may be changed during runtime and put in effect by a rehash. This is useful for keeping a soft limit of fd's lower than the ./configure value keeping a reserve for emergency use and releasing them by raising the softlimit
ToDo: A softlimit for what exactly?
The userstats field specifies which stats characters in /STATS may be requested by non-operators. Stats characters in this field are case sensitive.
If this is set then when an IRC operator uses /WHOIS on a user they will see all channels, even ones if channels are secret (+s), private (+p) or if the target user is invisible +i.
If this is not set to an empty value, then when a user does a /VERSION command on the ircd, this string will be displayed as the second portion of the output, replacing the system 'uname', compile flags and socket engine/dns engine names. You may use this to enhance security, or simply for vanity.
It indicates the maximum number of multiple targets which may be given to commands such as PRIVMSG, KICK etc. Default is 20.
If set to 'yes', 'true' or '1', the optional hidesplits field will hide split server names from non-opers. This is similar (practically identical) to how ircu handles netsplits, showing normal users only '*.net *.split' instead of the real server names as a security measure. The actual security benifits of this feature are debated in great length on some networks, but you can decide for yourself if you want this feature or not.
When set to 'yes', will hide gline, kline, zline and qline quit messages from non-opers. For example, user A who is not an oper will just see (G-Lined) while user B who is an oper will see the text (G-Lined: Reason here) instead.
This will change the temporary location modules are copied to before loading them. This may be important if /tmp is mounted with the noexec option on your system.
ToDo: What happens if this is the case? Will module not be functional?
The optional hidewhois field can be set to any arbitary text, and if defined, will replace the users server in any WHOIS performed by a non-oper. Most networks which enable this will probably set it to, for example, *.network.net. As with the hidesplits option above, the actual security benefits of such a feature are greatly debated, and there are many opinions as to wether this actually improves security or not.
If set to 'true', 'yes' or '1' while m_spanningtree is loaded, will cause /MAP and /LINKS to be flattened for non-opers.
hideulines, when specified, and you are using m_spanningtree.so, will conceal U-lined servers in /LINKS and /MAP for non opers. Please be aware that this will also hide any leaf servers of a U-lined server, e.g. jupes.
When users connect to your server it will try and resolve the users hostname using the specified dns server in the <dns> tag. This can consume alot of CPU and bandwith for very busy irc servers. Turn this option on and no user dns lookups will be performed for connecting users. Do beware that no users will resolve and this may not be suitable for all irc servers, it is recommended to run a local nameserver when possible to minimize dns load.
Set this option to 'true', 'yes' or '1' to give users not providing enough parameters for a command, a syntax hint using the RPL_TEXT numeric as well as the standard ERR_NEEDMOREPARAMS.
When a user's hostname changes this option will make it appear as if the user quit and then rejoins with their new host. This prevents clients from becoming confused by host changes, especially in the case of bots, and it is recommended that this option is enabled.
Provides undernet style of prefixed channel NOTICEs and PRIVMSGs. With this option turned on the outgoing text will be prefixed with the used prefix. Eg. 'NOTICE @#test :@ this is a test' as opposed to the standard 'NOTICE @#test :this is a test'.
When this option is enabled, then if a channel's timestamp is updated the users on the channel will be informed of the change via a server notice to the channel with the old and new TS values in the timestamp.
The allowhalfop variable enables or disables halfop support (channel mode +h).
This specifies the path to read modules from. If this is not defined, the value specified at compile time is defaulted to (which is normally the modules/ directory within your installation).
If this value is set to yes (which is the default from 1.1.2 onwards) then the full nick!user@host information is stored for any topic changes. Note that if one server has this enabled and another doesnt, the server without the feature enabled will still accept the full nick!user@host but will only send out the nick for any local changes.
If this option is set to yes (the default), then invites are announced to the channel when a user invites annother user. If you consider this to be unnecessary noise, explicitly set this to no.
If this option is set to no (the default), then when there is a link made from another server the bursts will be announced as joins to opers with the correct snomasks, if you consider this to be unncecessary noise, explicitly set this to yes.
If this option is set, the string it is set to will be used as the prefix for all KILL messages, masking the original sender of the KILL. i.e.:
[01:59:57] * w00t2 (viroteck@test-d57df912.karoo.KCOM.COM) Quit (Killed (*.lol.hax (Drone!)))
instead of:
[01:59:57] * w00t2 (viroteck@test-d57df912.karoo.KCOM.COM) Quit (Killed (SomeOper (Drone!)))
Exempt Channel ops from the effects of channel modes. A valid configuration for this setting is in the format exemptchanops=“modeshere” or blank for the default behavior of no exemptions. (currently only modes SfgNc are supported)
The NOTICE to show to users who are glined, zlined, klined or qlined when they are disconnected. This is totally freeform, you may place any text here you wish.