Features

From UnrealIRCd documentation wiki
Jump to navigation Jump to search
This page contains changes which are not marked for translation.
Other languages:
English • ‎français • ‎中文(台灣)‎

If you were just looking for a small list of features then have a look at the About UnrealIRCd article instead.

Below we will explain a number of features in-depth. If you are still in the process of getting your UnrealIRCd server up and running then we recommend you to only quickly glance over them. Once your server is up and running you may want to read this section more in depth, or just use it as a reference when you want to find out more about a feature.

Modules[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

In UnrealIRCd most functionality is in modules (150+ of them!). Most channel modes, user modes and all extended bans are in modules.

Advantages:

  1. Makes it possible to fully customize what exact functionality you want to load
  2. For coders it's easier to see all the source code related to a specific feature
  3. Allows bugs to be fixed without needing to restart the IRCd. Just rehash to reload the module(s).

Loading modules[edit]

For more information on how to load modules, see the Loadmodule directive.

If you just want to load all available modules (and thus all functionality) contained in UnrealIRCd, then put this in your unrealircd.conf:

include "modules.default.conf";

Available modules[edit]

UnrealIRCd has over 150 modules. Which module to load to enable/disable a certain feature is mentioned in the appropriate article:

Additionally, you may want to take a look at modules.default.conf as well.

Third party modules[edit]

It is possible to expand UnrealIRCd's functionality by modules from others. We call these modules "third party modules" because they are made by a 3rd party (not the UnrealIRCd team).

Where to find (more) third party modules[edit]

Many can be found on the Modules (3rd party) forums

How to use 3rd party modules[edit]

See FAQ: How to install 3rd party modules?

Dangers of third party modules[edit]

Although 3rd party modules are a great way to extend UnrealIRCd's features there is also a risk: any (subtle) coding mistakes can cause UnrealIRCd to crash. In fact, 90% of the crashes reported to our bug tracker are not crashes caused by UnrealIRCd but by 3rd party modules (not our bugs).


Authentication[edit]

UnrealIRCd allows users to authenticate to their services account before they are online. This also means you can require authentication so unauthenticated users cannot enter the server. This can be done selectively (eg: only certain IP addresses, only TOR proxy users, etc.) or simply for everyone (if you want a closed chat server).

Read more on authentication here

SSL/TLS[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

When you use SSL/TLS on IRC, all the network traffic is encrypted. Modern IRC servers and networks have SSL/TLS enabled & configured correctly and should encourage their users to use it.

UnrealIRCd has a long history of supporting and encouraging SSL/TLS, going all the way back to the year 2000.

What is SSL/TLS[edit]

SSL stands for Secure Socket Layer. Later versions have been named TLS (Transport Layer Security). In UnrealIRCd documentation we usually call it SSL/TLS because people use both terms to mean the same thing.

When you use SSL/TLS on a connection then all the traffic between the two hosts is encrypted. Nobody can see/sniff/snoop the data. This is important as IRC traffic often includes things like passwords and other sensitive information.

You probably see https:// sites on the internet all the time. HTTPS is simply HTTP with SSL and it's used for banking, e-commerce sites and nowadays a lot of regular sites as well. The same technology (SSL) can be used for IRC.

How to use SSL/TLS[edit]

Nearly all IRC clients support SSL/TLS. To use it you need to connect to a port which has listen::options::tls enabled, by default this is port 6697 (not 6667!).

In your IRC client you need to connect to the SSL-only port in a special way:

  • mIRC: /server name.of.server.net +6697. The + (plus sign) instructs mIRC to use SSL/TLS.
  • irssi: /connect -tls name.of.server 6697. The -tls option says to use SSL/TLS

On other clients it is usually a matter of using a plus sign before the port (+6697) or adding a SSL or TLS option or ticking such a box in the graphical interface.

Be sure to read next section on SSL certificates, especially if your client refuses to connect or complains about an untrusted or invalid certificate.

SSL certificate[edit]

By default, UnrealIRCd has created a self-signed certificate for you. However, most clients (rightfully) complain that this cannot be trusted. Some clients will give you a popup or option to accept the certificate (yes/no). Other clients will refuse to connect at all.

We recommend you to get a real certificate for free by Using Let's Encrypt with UnrealIRCd. Note that this does mean you have some labor to do. But after that, your server is really fully setup for SSL/TLS and your users can use IRC in a more secure manner!

Configuration[edit]

Global settings[edit]

Global SSL/TLS settings can be configured via set::tls. For most users the defaults are fine.

Per-port settings[edit]

If you want port-specific SSL setting then these can be configured in the Listen block.
NOTE: Doing so is very rare, most people would not change these at all or change the global SSL/TLS options in set::tls instead.

SNI[edit]

UnrealIRCd also support SNI, multiple certificates with different names, which you configure using the Sni block. This is not used much.

Strict Transport Security[edit]

"Strict Transport Security" is an IRCv3 specification. If you use it it will:

  1. redirect users with capable clients to the appropriate SSL/TLS port automatically
  2. ensure that these users won't use insecure connections for a specified period of time

To enable this you need to configure two important things:

Step 1: Get a real certificate[edit]

You need a 'real' SSL/TLS certificate, not the default / self-signed certificate that many people use. So: get one for free via Let's Encrypt (tutorial) or buy one.

IMPORTANT: Your users must connect to the server with the same hostname as the hostname in the certificate. So if users use /SERVER irc.example.com then your server shouldn't serve a certificate for irc2.example.com. Possible solutions for this are wildcard certificates (this too is possible via Let's Encrypt) or using multiple certificates with a Sni block (rarely used).

It is important for the certificate (and naming) to be correct. Without STS such a misconfiguration will 'only' trigger a certificate warning on the client but with STS the clients will be unable to connect. It is a hard error that clients cannot easily bypass.

Step 2: Configure the set::tls::sts-policy block[edit]

The following will configure a STS policy, redirecting capable clients to port 6697 (which must be SSL/TLS):

set {
    tls {
        sts-policy {
            port 6697;
            duration 5m; /* you can always increase this later */
        };
    };
};

Note that while you can remove the set::tls::sts-policy block at any time, clients will cache the setting for up to set::tls::sts-policy::duration time. So when deploying sts-policy, and when picking a (final) setting, be sure to provide SSL/TLS support for an extended amount of time. This shouldn't be any problem with UnrealIRCd but just to reiterate: only deploy STS if you are serious about offering SSL/TLS to your clients!

You should gradually raise the set::tls::sts-policy::duration time. This to prevent you inadvertently locking users out due to a misconfiguration:

  • Begin with 5 minutes (5m) during testing.
  • After a week, consider raising it to a day (1d).
  • After a month, consider raising it to it's final setting, such as half a year (180d)

Be sure to enforce the same STS policy on all servers on your network (unless you are only testing).


IPv6[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

IPv6 is Internet Protocol version 6. It is the successor to version 4 (IPv4). Currently the Internet consists of a mix of IPv4 and IPv6. For more information in general, see the Wikipedia article on IPv6.

UnrealIRCd makes use of the "dual IP stack" of your system, meaning it can listen on both IPv4 and IPv6 addresses. UnrealIRCd is always built with IPv6 support. To actually use IPv6 you'll need an IPv6 address on your machine and an ISP that does IPv6 routing (unless you want to tunnel, but this is outside of the scope of this article).


Anti-flood features[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

Set block[edit]

In the configuration file in the set block you can configure a lot of the anti flood features. Note that UnrealIRCd already ships with good defaults, but you can change them if you wish.

There are many settings available in the set::anti-flood block. For example, set::anti-flood::connect-flood to only allow X connections per YY seconds from the same IP. Other X per Y time settings are: nick-flood, join-flood, away-flood, invite-flood and knock-flood.

The option set::anti-flood::unknown-flood-amount is used to limit the amount of data in the handshake (rarely changed, default is a few KB's).

set::anti-flood::max-concurrent-conversations limits the number of concurrent conversions a user can have, which is another anti-flood feature so a user cannot /MSG tens of users at the same time.

set::max-targets-per-command limits the number of targets the user can specify in a command (eg: JOIN 3 channels at the same time via JOIN #a,#b,#c).

Again, the default settings are probably fine for you already, as we focus on security and do our best to have tight but good defaults.

DNS Blacklists[edit]

While technically not an anti-flood feature, it definitely helps against unwanted bots/drones/users. By using one or more blacklist blocks you can have UnrealIRCd check a DNSBL service to see if an IP was blacklisted due to abuse. This is highly recommended for a server on the internet. See the example section there.

Connthrottle[edit]

This module is highly effective against bot/drone attacks. It will reject most "bad" connections, while still allowing most of your regular users in.

When the connthrottle module in UnrealIRCd detects a high number of users connecting from IP addresses that have not been seen before, then connections from new IP's are rejected above the set rate. For example at 10:60 only 10 users per minute can connect that have not been seen before. Known IP addresses (so: your regular users) can always get in, regardless of the set rate. Same for users who login using SASL.

AntiRandom[edit]

With the antirandom module you can block random nicks like 'fhdshfdhf'.This module is not enabled by default because it may catch innocent users for non-English languages, especially for non-Western-European languages.

Simple channel modes[edit]

There are also some easy to use channel modes which can be quite effective against floods:

  • N: no nick changes
  • C: no CTCP's
  • M: only registered users may talk
  • K: no /KNOCK allowed

You can set these channel modes permanently. But you can also use the very advanced channel mode +f to set these restrictions only when needed (and more), see next.

Channel mode f[edit]

Instead of using scripts and bots to protect against channel floods it is build into the ircd. An example +f mode is:

*** Blah sets mode: +f [10j]:15

This means 10 joins per 15 seconds are allowed in the channel, if the limit is hit, the channel will be set +i (Invite only) automatically.

The following floodtypes are available:

Type Name Default action Other actions Comments
c CTCPs Set channel mode +C (block all CTCP's) m, M
j joins Set channel mode +i (invite only) R
k knocks Set channel mode +K (no /knock's)
m messages/notices Set channel mode +m (regular users cannot speak) M, d
n nick changes Set channel mode +N (no nick-changes permitted)
t text Kick the user b, d Per-user message/notice limit. Action is to kick or kick+ban the user, or to drop the message.
r repeat Kick the user b, d Per-user repeat limit. Action is to kick or kick+ban the user, or to drop the message.

Example:

*** ChanOp sets mode: +f [20j,50m,7n]:15
<ChanOp> lalala
*** Evil1 (~fdsdsfddf@Clk-17B4D84B.blah.net) has joined #test
*** Evil2 (~jcvibhcih@Clk-3472A942.xx.someispcom) has joined #test
*** Evil3 (~toijhlihs@Clk-38D374A3.aol.com) has joined #test
*** Evil4 (~eihjifihi@Clk-5387B42F.dfdfd.blablalba.be) has joined #test
-- snip XX lines --
*** Evil21 (~jiovoihew@Clk-48D826C3.e.something.org) has joined #test
-server1.test.net:#test *** Channel joinflood detected (limit is 20 per 15 seconds), putting +i
*** server1.test.net sets mode: +i
<Evil2> fsdjfdshfdkjfdkjfdsgdskjgsdjgsdsdfsfdujsflkhsfdl
<Evil12> fsdjfdshfdkjfdkjfdsgdskjgsdjgsdsdfsfdujsflkhsfdl
<Evil15> fsdjfdshfdkjfdkjfdsgdskjgsdjgsdsdfsfdujsflkhsfdl
<Evil10> fsdjfdshfdkjfdkjfdsgdskjgsdjgsdsdfsfdujsflkhsfdl
<Evil8> fsdjfdshfdkjfdkjfdsgdskjgsdjgsdsdfsfdujsflkhsfdl
-- snip XX lines --
-server1.test.net:#test *** Channel msg/noticeflood detected (limit is 50 per 15 seconds), putting +m
*** server1.test.net sets mode: +m
*** Evil1 is now known as Hmmm1
*** Evil2 is now known as Hmmm2
*** Evil3 is now known as Hmmm3
*** Evil4 is now known as Hmmm4
*** Evil5 is now known as Hmmm5
*** Evil6 is now known as Hmmm6
*** Evil7 is now known as Hmmm7
*** Evil8 is now known as Hmmm8
-server1.test.net:#test *** Channel nickflood detected (limit is 7 per 15 seconds), putting +N
*** server1.test.net sets mode: +N

In fact, it can get even more advanced/complicated:
Instead of the default action, you can for some floodtypes specify another one, for example: +f [20j#R,50m#M]:15
This will set the channel +R if the joinlimit is reached (>20 joins in 15 seconds), and will set the channel +M if the msg limit is reached (>50 messages in 15 seconds).

There's also a "remove mode after X minutes" feature: +f [20j#R5]:15 will set the channel +R if the limit is reached and will set -R after 5 minutes.
A server can have a default unsettime (set::modef-default-unsettime), so if you type +f [20j]:15 it could get transformed into +f [20j#i10]:15, it's just a default, you can still set [20j#i2]:15 or something like that, and you can also disable the remove-chanmode completely by doing a +f [20j#i0]:15 (an explicit 0).

What the best +f mode is heavily depends on the channel... how many users does it have? do you have a game that makes users msg a lot (eg: trivia) or do users often use popups? is it some kind of mainchannel or in auto-join? etc..

There's no perfect channelmode +f that is good for all channels, but to get you started have a look at the next example and modify it to suit your needs:
+f [30j#i10,40m#m10,7c#C15,10n#N15,30k#K10]:15

  • 30 joins per 15 seconds, if limit is reached set channel +i for 10 minutes
  • 40 messages per 15 seconds, if limit is reached set channel +m for 10 minutes
  • 7 ctcps per 15 seconds, if limit is reached set channel +C for 15 minutes
  • 10 nickchanges per 15 seconds, if limit is reached set channel +N for 15 minutes
  • 30 knocks per 15 seconds, if limit is reached set channel +K for 10 minutes

If it's some kind of large user channel (>75 users?) you will want to increase the join sensitivity (to eg: 50) and the message limit as well (to eg: 60 or 75).
Especially the remove-mode times are a matter of taste.. you should think like.. what if no op is available to handle the situation, do I want to have the channel locked for like 15 minutes (=not nice for users) or 5 minutes (=likely the flooders will just wait 5m and flood again). It also depends on the floodtype, users unable to join (+i) or speak (+m) is worse than having them unable to change their nick (+N) or send ctcps to the channel (+C) so you might want to use different removal times.


Cloaking[edit]

Cloaking is a security feature which hides the IP address and hostname of users on IRC.

With cloaking turned off, a join on IRC looks like this:

*** User (~none@d5142341.example.net) has joined #test

With cloaking turned on, users will see:

*** User (~none@rox-2DCA3201.example.net) has joined #test

The first part of the host is partially hidden or "cloaked". Other people won't see your real hostname or IP address. This security feature is useful to prevent users from flooding/attacking each other.

For a more detailed explanation and the possible settings, see Cloaking.

Remote includes[edit]

Remote includes are a great way of sharing your configuration settings between servers, ideal for multi-server IRC networks. You simply put your (shared) configuration files on a secure location, like a trusted web server and IRC servers will load it from there when they startup or /REHASH. Remote includes support https and many other protocols.

Read more on remote includes here

Spamfilter[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

Spamfilter is a highly advanced system to fight spam, advertising, worms and other bad things on IRC. Spamfilters can be added through the /SPAMFILTER command or through spamfilter { } blocks in the configuration file.

SPAMFILTER command[edit]

On IRC spamfilters are added via the /SPAMFILTER command which uses the following syntax:
/spamfilter [add|del] [match-type] [target] [action] [tkltime] [reason] [match string]

Item Explanation & possible options
add / del Indicates if you want to add or remove a spamfilter
match-type The type of match string you're going to use (see also the examples later on). There are two choices:
  • -simple means simple matching with ? and * wildcard support
  • -regex uses regular expressions (more on that later)
target specifies the target type, the targets this spamfilter will look into:
Character Config item Description
c channel Channel message
p private Private message (from user->user)
n private-notice Private notice
N channel-notice Channel notice
P part Part reason
q quit Quit reason
d dcc DCC filename
a away Away message
t topic Setting a topic
u user User ban, will be matched against nick!user@host:realname

You can (and often will) specify multiple targets, like: cpNn

action specifies the action to be taken, such as kline. See Actions for a list of all possible actions.
tkltime The duration of the *line/shun added by the filter. Use '-' to use the default or to skip (eg: if action is 'block')
reason Block/*line/shun reason.. you CANNOT use spaces in this, but underscores ('_') will be translated into spaces at runtime. And double underscore ('__') gets an underscore ('_'). Again, use '-' to use the default reason.
match-string This is the actual string that should be blocked or that we should perform the specified action on. The syntax of this string depends on the match-type. See also examples below.

Scroll down for examples of the /SPAMFILTER command.

Spamfilter block[edit]

You can also put spamfilters in your configuration file, see the Spamfilter block. For information about each of the fields see above.

Examples[edit]

Block simple spam[edit]

Say, you see a user mass-spamming in channels and in PM (Private Message). In each case, the user is saying: Hey <NICK>, come watch me on my webcam! connect to http://1.2.3.4:80/. It looks always like that, except for a varying IP/URL. You want any user who says this to be immediately GLINEd for 1 day.

On IRC:

/SPAMFILTER add -simple pc gline 1d You_are_spamming_or_you_have_a_virus! *Hey*come watch me on my webcam*

Or in the configuration file:

spamfilter {
        match-type simple;
        target { private; channel; };
        action gline;
        ban-time 1d;
        reason "You are spamming or you have a virus!";
        match "*Hey*come watch me on my webcam*";
};

Regex to block mIRC exploit[edit]

Regular expressions (regex) are much more powerful than the simple method. Several years ago mIRC had a bug: you could crash any mIRC v6.12 by sending a DCC SEND message with a filename of 225 (or more) characters. With the simple method from above you can't block this, with regex you can. For regex this is even an easy case.

On IRC:

/SPAMFILTER add -regex pc kill - Possible_mIRC_exploit_attempt \x01DCC (SEND|RESUME).{225}

Or in the configuration file:

spamfilter {
        match-type regex;
        target { private; channel; };
        action kill;
        reason "Possible mIRC exploit attempt";
        match "\x01DCC (SEND|RESUME).{225}";
};

To learn more about regex, see Introduction to regex (PCRE).

Slow Spamfilter Detection[edit]

Spamfilters often consist of complex regular expressions. There is a very small chance that if a regular expression is too complex that it would slow down the IRCd too much, causing issues with responsiveness.

Slow spamfilters are very exceptional but they are possible, so UnrealIRCd has a safety mechanism for this. They are set::spamfilter::detect-slow-warn and set::spamfilter::detect-slow-fatal. If a single spamfilter takes longer than detect-slow-warn then the IRC Server will warn about this spamfilter to IRCOps. If it takes longer than detect-slow-fatal it will remove the spamfilter. The default values for these are 250ms and 500ms respectively (so a quarter of a second and half a second).

Target of spamfilter bans[edit]

When a spamfilter is hit by a user, it will by default place ban on *@ip if the ban type is a *LINE (of course not for other actions such as warn). This should be fine for most people. You can, however, change this via the set::automatic-ban-target setting.

Exempting users from spamfilters[edit]

IRCOps will not trigger spamfilters by default (they are exempt). That is, if they use an operclass with the immune:server-ban:spamfilter permission.

You can also exempt specific targets by name, such as channels or nicks, via set::spamfilter::except.


WebSocket Support[edit]

UnrealIRCd 4.0.10 and later support the WebSocket protocol (ws:// and wss://). This allows Javascript (internet browsers) to connect directly to IRC, without the need of intermediate 'gateways'. (Read more)

WebIRC Support[edit]

UnrealIRCd supports the WEBIRC / CGIIRC protocol. Similarly to WebSocket support (see above) this allows users to use an internet browser rather than a "real" IRC client and still make them show up on IRC with their real IP. If you want your users to be able to use Mibbit or IRCCloud then you need to configure this. (Read more)

Authentication types[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

At various places in the configuration file, for example the Oper block, Vhost block, Link block and Allow block you can authenticate clients by password or other means. You can specify the password as plaintext, but you can also specify an "authentication type".

Available auth-types[edit]

The following auth-types are available:

Auth-type Description Security level How to generate
none Plaintext / cleartext password Bad Plaintext password directly in the config. Not recommended.
md5 MD5 with salt Deprecated Deprecated. Do not use.
sha1 SHA1 with salt Deprecated Deprecated. Do not use.
ripemd160 RIPEMD160 with salt Deprecated Deprecated. Do not use.
crypt UNIX crypt. The exact hashing algorithm depends on the type of crypt, therefore the security can range from bad to reasonable. Bad or reasonable Not recommended.
bcrypt Blowfish crypt with salt and many rounds [1] Reasonable On IRC: /MKPASSWD bcrypt <password>

On *NIX shell: ./unrealircd mkpasswd bcrypt

argon2 Argon2 hashing algorithm. Many rounds, anti-GPU cracking measures, etc. [2]
Good On IRC: /MKPASSWD argon2 <password>

On *NIX shell: /unrealircd mkpasswd argon2

cert SSL/TLS Client certificate

Note that most people use certfp or spkifp instead.

Excellent Path to a public SSL/TLS certificate (.pem file)
certfp SSL/TLS Client certificate fingerprint (SHA256) Excellent For a given SSL/TLS certificate such as client.pem, run:

openssl x509 -in client.pem -sha256 -noout -fingerprint
and copy the AA:BB:CC:DD:etc... fingerprint.

spkifp SPKI Fingerprint. This is similar to an SSL/TLS Client certificate fingerprint but is usually only used for server linking.

The benefit of spkifp over certfp is that the spkifp stays the same as long as the key stays the same.

Excellent For a given SSL/TLS certificate:

./unrealircd spkifp conf/ssl/server.cert.pem
Or, alternatively, these openssl commands

The auth-type argon2 is the best one if you want to authenticate using a password. It's slow to crack.

The types cert and certfp require a bit more work and expertise, as the user must generate their own SSL/TLS Certificate and then use it to connect to the server via SSL/TLS. We suggest to use this auth-type for /OPER (in the Oper block), see the 2nd example below. Finally the type spkifp is usually only used for linking servers.

Example 1: argon2 password in vhost block[edit]

Say, you want to use the password test and want to use argon2 hashed passwords (the best password hashing method available).

  • As IRCOp run:
/MKPASSWD argon2 test

or on the *NIX command line run:

irc@system:~/unrealircd$ ./unrealircd mkpasswd
Enter password to hash:
Encrypted password is: $argon2id$v=19$m=8192,t=3,p=2$hDpgvcBOUVAJMQcJITTLnQ$fL5lg/3tZ0VgTXn61EQ6Rnxhl5j+MvESBBGpg1mZqWM
  • You should get back a string that starts with $ followed by a lot of characters.
  • Put this string in your vhost block (or any other block) like this:
vhost {
    vhost I.love.Tux;
    mask *@*;
    login Tux;
    password "$argon2id$v=19$m=8192,t=3,p=2$hDpgvcBOUVAJMQcJITTLnQ$fL5lg/3tZ0VgTXn61EQ6Rnxhl5j+MvESBBGpg1mZqWM";
};
  • /REHASH your IRCd server configuration (Execute /REHASH as an IRCop on IRC)
  • Try to use the new vhost by typing /VHOST Tux test

Example 2: Oper by SSL/TLS Client certificates[edit]

cert and certfp are exceptional auth-types which can be used to authenticate SSL/TLS users by their client certificate. With these authentication methods you can be sure the user is using SSL/TLS and is using the specified client certificate. It's very secure but is a slightly advanced feature.

Here's an example of how to use it for the oper block:

  • Create an SSL/TLS client certificate if you don't have one already. Search the web for irc client certificate if you don't know how to do this.
  • Connect to IRC with your client, using your client certificate (consult your IRC client documentation)
  • On IRC simply /WHOIS yourself and you will see a line like:
FriendlyOper has client certificate fingerprint e74d46f19ff468f5e8e349cc285df96585ba4f16b64902e334e6e76afe76a798

If you do not see a line stating a "client certificate fingerprint", then your IRC client is not configured correctly to use the SSL/TLS client certificate. Consult your IRC client documentation.

  • In the server configuration file (eg: unrealircd.conf), set the password to the certificate fingerprint you saw on IRC. For example:
oper test {
     password "e74d46f19ff468f5e8e349cc285df96585ba4f16b64902e334e6e76afe76a798" { certfp; };
[..]
};
  • Rehash your server
  • Now oper up through /OPER test. When you try this, make sure that you are not already an IRCOp.
  • You should now have IRC Operator rights.
  • Congratulations, you are now using the most secure authentication method available in UnrealIRCd!

Example 3: SSL/TLS Client certificates when linking servers[edit]

When you are linking servers via the Link block we highly suggest you follow the Tutorial: Linking servers as it uses the SSL/TLS client certificate fingerprint authentication type.

Aliases[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

With aliases you can configure server-side alias commands. You can for example let /NS IDENTIFY blah be forwarded to NickServ. UnrealIRCd will then convert that command to be like /MSG NickServ IDENTIFY blah. You can even make more complex aliases: for example have the /REGISTER command forward the message to ChanServ if the first parameter begins with a # and forwarded it to NickServ if it doesn't.

Aliases are configured in the Alias block.

Note that UnrealIRCd comes with a decent set of default aliases for anope, atheme and other IRC Services. See the Commonly included files section.


IRCOp access control[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

In UnrealIRCd you can very precisely specify which rights you want to grant or deny to an IRCOp. You do this via a combination of the Operclass block and the Oper block.


Snomasks[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

Snomasks are server notice masks. It's a special type of user mode that controls which server notices you will receive. Only IRCOps can set snomasks.

It can be set by: /MODE yournick +s SNOMASK, for example: /MODE yournick +s +cF. To remove certain snomasks, use something like: /MODE yournick +s -c, or to remove all snomasks use /MODE yournick -s.

The available snomasks are:

Snomask Module Description
b blacklist Messages from the DNS blacklist module
c built-in Local connects
D snomasks/dccreject Rejected DCC's due to Deny dcc blocks
F built-in Far connects (from other servers, except from U-lines like Services)
f built-in flood notices
k built-in kill notices
e built-in 'eyes' notices - a bit verbose (?)
j built-in Junk notices (noisy, possibly harmless things, mostly for debugging)
v built-in VHOST usage
G built-in GLINE and SHUN usage
n built-in Local nick changes
N built-in Remote nick change notices
q built-in Deny nick (QLINE) rejection notices
s built-in Receives server notices (includes the most important messages)
S built-in Spamfilter hits
o built-in Oper-up notices (/OPER usage)

You can control which snomasks IRCOps receive by default via set::snomask-on-oper, or in specific oper blocks via oper::snomask.


IRCOp commands[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

UnrealIRCd comes with a lot of commands for IRCOp's to combat security threats, abusive users and manage things. They are listed under User & Oper commands in this wiki or you can see a list on IRC via the Helpop system by executing /HELPOP OPERCMDS.


Extended bans[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

Extended Bans are a special type of bans (+b), exempts (+e) and invite exceptions (+I) providing "extended" functionality.

These bans start with a tilde, followed by a letter denoting the extban type. For example +b ~q denotes a quiet extban. UnrealIRCd comes with a number of built-in extbans (loaded through Modules). 3rd party modules may introduce even more types.

The following ban type can be used in front of any (ext)ban:

Extban Module Explanation Example
t extbans/timedban Timed ban that will make a ban unset after the specified number of minutes. +b ~t:3:*!*@hostname

The following ban types specify which actions (join, nick-change or speaking) are affected by a ban:

Extban Module Explanation Example
q extbans/quiet People matching these bans can join but are unable to speak, unless they have +v or higher. +b ~q:*!*@*.blah.com
n extbans/nickchange People matching these bans cannot change nicks, unless they have +v or higher. +b ~n:*!*@*.aol.com
j extbans/join When a user matches this (s)he may not join the channel but if already in the channel then all activities are permitted such as speaking or changing the nick. This can be useful to ban an entire ISP and then manually /INVITE people to the channel so once joined they can behave as normal. +b ~j:*!*@*.aol.com
f chanmodes/link Forward user to another channel if matching mask. +b ~f:#badispchannel:*!*@*.isp.com
m extbans/msgbypass Bypass message restrictions. This extended ban is only available as +e and not as +b. Syntax: +e ~m:type:mask.

Valid types are: external (bypass +n), moderated (bypass +m/+M), censor (bypass +G), color (bypass +S/+c) and notice (bypass +T).

+e ~m:moderated:*!*@192.168.*

+e ~m:external:*!*@192.168.*
+e ~m:color:~a:ColorBot

These bantypes introduce new criteria which can be used:

Extban Module Explanation Example
a extbans/account If a user is logged in to services with this account name, then this ban will match. This is slightly different than ~R, in the sense that a user with nick ABC may be logged in under account XYZ. Not all services packages support this, in which case you will have to use ~R instead. +e ~a:SomeAccount

+I ~a:SomeAccount

c extbans/inchannel If the user is in this channel then (s)he is unable to join. A prefix can also be specified (+/%/@/&/~) which means that it will only match if the user has that rights or higher on the specified channel. +b ~c:#lamers

+e ~c:@#trustedops

G extbans/securitygroup If the user matches this security group then (s)he is unable to join. +b ~G:unknown-users
O extbans/operclass If the user is an IRCOp and the oper::operclass matches this name then the ban/invex will match. You can use this to for example create *admin* only channels. +iI ~O:*admin*
r extbans/realname If the realname (gecos) of a user matches this then (s)he is unable to join. Since real names may contain spaces you can use a underscore to match a space (and underscore) +b ~r:*Stupid_bot_script*
S extbans/certfp When a user is using SSL/TLS with a client certificate then you can match the user by his/her SSL fingerprint (the one you see in /WHOIS). Useful for ban exemptions (+e) and invite exceptions (+I). +e ~S:0000000etc

+I ~S:0000000etc

T extbans/textban Channel-specific text filtering. Supports two actions: 'censor' and 'block', see examples on the right. +b ~T:censor:*badword*

+b ~T:block:*something*

You may also stack extended bans from the 2nd group with the 3rd group. For example: +b ~q:~c:#lamers would quiet all users who have joined #lamers.

Ban types from the 3rd group can be used in invite exceptions (+I). For example you can put the channel +i and then use +I ~c:@#trusted and/or +I ~a:accountname.


User modes[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

This is the list of all user modes that can be set on a user. You can only set user modes on yourself and not on other users. Use the command: MODE yournick +modeshere.

User mode Module Description Restrictions
B usermodes/bot Marks you as being a bot. This will add a line to /WHOIS so people can easily recognize bots.
d built-in Makes it so you can not receive channel PRIVMSG's, except for messages prefixed with a set::channel-command-prefix character. Could be used by bots to reduce traffic so they only see !somecmd type of things.
D usermodes/privdeaf Makes it so you can not receive private messages (PM's) from anyone except IRCOps, servers and services.
G usermodes/censor Swear filter: filters out all the "bad words" configured in the Badword block
H built-in Hide IRCop status. Regular users using /WHOIS or other commands will not see that you are an IRC Operator. IRCOp-only
I built-in Hide online time in /WHOIS. see set block for more details: set::hide-idle-time
i built-in Makes you so called 'invisible'. A confusing term to mean that you're just hidden from /WHO and /NAMES if queried by someone outside the channel. Normally set by default through set::modes-on-connect and often by the users' IRC client as well.
o built-in IRC Operator Set by server
p usermodes/privacy Hide channels you are in from /WHOIS, for extra privacy.
q usermodes/nokick Unkickable (only by U:lines, eg: services) IRCOp-only (but not all)
r built-in Indicates this is a "registered nick" Set by services
R usermodes/regonlymsg Only receive private messages from users who are "registered users" (authenticated by Services)
S usermodes/servicebot User is a services bot (gives some extra protection) Services-only
s built-in Server notices for IRCOps, see Snomasks IRCOp-only
T usermodes/noctcp Prevents you from receiving CTCP's.
t built-in Indicates you are using a /VHOST Set by server upon /VHOST, /OPER, /*HOST, ..
W usermodes/showwhois Lets you see when people do a /WHOIS on you. IRCOp-only
w built-in Can listen to wallops messages (/WALLOPS from IRCOps')
x built-in Gives you a hidden / cloaked hostname.
Z usermodes/secureonlymsg Allows only users on a secure connection to send you private messages/notices/CTCPs. Conversely, you can't send any such messages to non-secure users either.
z built-in Indicates you are connected via SSL/TLS Set by server


Channel modes[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

These are all channel modes that can be set. Use the command: MODE #channel +modeshere.

Normally you need channel operator status (+o, or some other level such as +h/+a/+q) if you want to change channel modes. However, IRCOp's with OperOverride privileges may bypass these restrictions. And similarly for IRCOps with access to the SAMODE command.

Access levels[edit]

These are the modes that grant a certain 'level' to a user.

Channel mode Module Description Restrictions
v built-in Voice. This makes the user able to speak in +m/+M channels. User can also still speak if banned. May be set by +hoaq users
h built-in Half-Op. Gives some of the usual channel operator rights, but not all. They are basically a light version of channel ops. May be set by +oaq users
o built-in Channel Op. This is the channel operator privilege everyone knows about, allows the user to do almost all administrative tasks in a channel such as /KICK, /MODE, etc.. May be set by +oaq users
a built-in Channel Admin. A level above channel ops but with no special extra privileges except for one: people below chanadmin (so +h/+o) cannot KICK +a people. May be set by +q users
q built-in Channel Owner. The highest level. Channel owners can't be kicked by any level below. Usually there's only one person with +q and the mode is set by services. Normal users can't set this

Note that often Services are used to manage +vhoaq lists in so called "access lists" or AOP/HOP/etc. Consult your services documentation.

List modes[edit]

These are so called 'list modes'.

Channel mode Module Description Restrictions
b built-in Ban. Prevents a user from joining the channel. Requires +h or higher
e built-in Ban exception. When a user is banned (due to +b) and they are on this +e list then they may still join the channel. Requires +h or higher
I built-in Invite exception. When the channel is +i (invite only) then people on this list may still join the channel. Requires +h or higher

All these modes take a nick!user@host parameter, like: +b *!*@*.isp.com. See also Extended bans for other syntaxes (eg: +e ~c:@#channel).

Channel settings[edit]

These are channel modes that configure channel settings.

Channel mode Module Description Restrictions
c chanmodes/nocolor No color allowed in the channel. Will block ANSI and mIRC color codes. Requires +o or higher
C chanmodes/noctcp No CTCP's allowed in the channel. Requires +o or higher
D chanmodes/delayjoin Delays someone's JOIN message until that person speaks. Chanops and higher, opers and ulines/services are exempt. Requires +o or higher
d chanmodes/delayjoin When unsetting +D, Unreal needs to process all remaining delayed users (i.e. invisible in the channel to regular users) to make them JOIN. +d is an intermediate/temporary mode to facilitate this and will be unset once all users are properly "joined". Set by server
f chanmodes/floodprot Flood protection. This is a highly advanced feature, see channel mode +f. Requires +o or higher
G chanmodes/censor Filter out bad words configured in Badword block Requires +o or higher
H chanmodes/history Turns on Channel History. requires UnrealIRCD 5.x, and modern IRC clients. For more information how to use this see Channel history Requires +o or higher
i built-in Invite only. Requires people to be /INVITE'd to the channel or be on the +I (Invite Exceptions) list (for that latter, see the List modes section above) Requires +o or higher
k built-in Require users to specify a channel key in order to join (/JOIN #chan key). Example: +k secret Requires +h or higher
K chanmodes/noknock /KNOCK command is not allowed. Requires +o or higher
L built-in Channel link. If the +l user limit (see below) is reached then users will automatically be redirected to this channel. Example: +L #something Requires +o or higher
l built-in Limit the amount of users that may be in the channel. If the limit is reached then any new JOIN's are rejected (see also +L above). Requires +o or higher
m built-in Moderated channel. Only people with +v or higher (+vhoaq) may speak. Requires +h or higher
M chanmodes/regonlyspeak Must be authenticated to services or have +v or higher to speak. Requires +o or higher
N chanmodes/nonickchange No nick-changes permitted. Normally not set, only during a a nick-flood flood attack. Requires +o or higher
n built-in No external messages. If you don't set +n then users outside the channel may still send messages to it. Thus, almost everyone will set their channel +n. Requires +h or higher
O chanmodes/operonly IRC Operator only channel IRCOp-only
P chanmodes/permanent Permanent channel. After all users leave a channel it is normally destroyed. If you set +P then this won't happen and all settings are preserved.

In addition to that, in UnrealIRCd 5 all channel settings (modes, bans, topic, etc.) are saved in a database and restored on startup via the channeldb module.

IRCOp-only
p built-in Private channel. Partially conceals the existence of the channel. Users cannot see this channel name unless they are a member of it. For example, if you /WHOIS a user who is on a +p channel, this channel is omitted from the response - unless you are on the same channel. IRC Operators will always see +p channels and its members. Requires +o or higher
Q chanmodes/nokick No /KICK allowed. Can be used to force all chanops to use Services for kicking. Unusual, but possible. Requires +o or higher
R chanmodes/regonly Only registered users may join the channel. Registered users are users authenticated to Services. Requires +o or higher
r built-in Channel is registered at Services Set by services
s built-in Secret channel. Extends the functionality of +p (above), but in addition to this, it will act as if the channel does not exist at all for queries like /TOPIC, /LIST and /NAMES. One exception to this is that it will always respond to the /MODE command. IRC Operators will always see +s channels and its members. Requires +o or higher
S chanmodes/stripcolor Strip color codes. This removes any mIRC or ANSI color codes by converting it to regular text. Requires +o or higher
T chanmodes/nonotice Channel notices are not permitted (/NOTICE #chan hi!). On many clients a beeping sound will happen on notices, hence why this mode is sometimes set. Requires +o or higher
t built-in Restricts /TOPIC to +h or higher. Without +t anyone in the channel may set the topic. Most channels are +t. Requires +h or higher
V chanmodes/noinvite /INVITE is not permitted. Requires +o or higher
z chanmodes/secureonly Only clients which are connected through SSL/TLS may join the channel Requires +o or higher
Z chanmodes/issecure Indicates that only people who are using SSL/TLS are on the channel. This channel mode is (only) set by the server when the channel is also +z and everyone on the channel is connected via SSL. Set by server


CIDR[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

UnrealIRCd supports the CIDR notation when allowing/disallowing IP's. This can be used in bans, allow blocks, oper::mask, etc. etc. If you prefer to use CIDR, you can use it.

An example of CIDR would be 127.0.0.0/8 which matches 127.0.0.0 through 127.255.255.255. In this example we could just as easily have written 127.*.

For more information see Wikipedia - CIDR.


Nick Character Sets[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

In UnrealIRCd you can specify which "character sets" or languages should be allowed in nicknames. You do this in set::allowed-nickchars.

Available UTF8 character sets[edit]

UnrealIRCd 4.0.17 adds experimental support for UTF8 character encoding.

Note that many Services packages do not permit registration with such characters. See also #Important notes.

The following languages are available:

Name Description Script/Alphabet Allowed extra characters (other than the default)
hebrew-utf8 hebrew characters Hebrew script אבגדהוזחטיךכלםמןנסעףפץצקרשת
latin-utf8 latin characters Latin script ÀÁÂÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÖØÙÚÛÜÝÞßàáâäåæçèéêëìíîïðñòóôöøùúûüýþÿĂ㥹ĆćČčĎďĘęĚěĹ弾ŁłŃńŇňŐőŔŕŘřŚśŞşŠšŢţŤťŮůŰűŹźŻżŽž
french-utf8 french characters Latin script ÀÂÇÈÉÊËÎÏÔÙÛÜàâçèéêëîïôùûüÿ
slovak-utf8 slovak characters Latin script ÁÄÉÍáäéíóôúýČčĎďĹ弾ňŔ੹ŤťŽž
icelandic-utf8 icelandic characters Latin script ÁÆÍÐÓÖÚÝÞáæíðóöúýþ
danish-utf8 danish characters Latin script ÅÆØåæø
swedish-utf8 swedish characters Latin script ÄÅÖäåö
catalan-utf8 catalan characters Latin script ÀÇÈÉÍÏÒÓÚÜàçèéíïòóú
italian-utf8 italian characters Latin script ÀÈÉÌÍÒÓÙÚàèéìíòóùú
spanish-utf8 spanish characters Latin script ÁÉÍÑÓÚÜáéíñóúü
hungarian-utf8 hungarian characters Latin script ÁÉÍÓÖÚÜáéíóöúüŐőŰű
czech-utf8 czech characters Latin script ÁÉÍÓÚÝáéíóúýČčĎďĚěŇňŘřŠšŤťŮůŽž
romanian-utf8 romanian characters Latin script ÂÎâîĂ㪺Ţţ
swiss-german-utf8 swiss-german characters Latin script ÄÖÜäöü
german-utf8 german characters Latin script ÄÖÜßäöü
turkish-utf8 turkish characters Latin script ÇÖÜçöüĞğıŞş
dutch-utf8 dutch characters Latin script èéëïöü
polish-utf8 polish characters Latin script ÓóĄąĆćĘꣳŃńŚśŹźŻż
latvian-utf8 latvian characters (5.0.7+) Latin script
estonian-utf8 estonian characters (5.0.7+) Latin script
lithuanian-utf8 lithuanian characters (5.0.7+) Latin script
greek-utf8 greek characters Greek script ΆΈΉΊΌΎΏΐΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩΪΫάέήίΰαβγδεζηθικλμνξοπρςστ
ukrainian-utf8 ukrainian characters Cyrillic script ЄІЇАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЮЯабвгдежзийклмнопрстуфхцчшщьюяєіїҐґ
russian-utf8 russian characters Cyrillic script ЁАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЪЫЬЭЮЯабвгдежзийклмнопрстуфхцчшщъыьэюяё
cyrillic-utf8 cyrillic characters Cyrillic script ЁЄІЇЎАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЪЫЬЭЮЯабвгдежзийклмнопрстуфхцчшщъыьэюяёєіїўҐґ
belarussian-utf8 belarussian characters Cyrillic script ЁІЎАБВГДЕЖЗЙКЛМНОПРСТУФХЦЧШЫЬЭЮЯабвгдежзйклмнопрстуфхцчшыьэюяёіў

Available non-utf8 character sets[edit]

Table of all available "old" character sets (not using UTF8):

Name Description Character set / encoding
catalan Catalan characters iso8859-1 (latin1)
danish Danish characters iso8859-1 (latin1)
dutch Dutch characters iso8859-1 (latin1)
french French characters iso8859-1 (latin1)
german German characters iso8859-1 (latin1)
swiss-german Swiss-German characters (no es-zett) iso8859-1 (latin1)
icelandic Icelandic characters iso8859-1 (latin1)
italian Italian characters iso8859-1 (latin1)
spanish Spanish characters iso8859-1 (latin1)
swedish Swedish characters iso8859-1 (latin1)
latin1 catalan, danish, dutch, french, german, swiss-german, spanish, icelandic, italian, swedish iso8859-1 (latin1)
hungarian Hungarian characters iso8859-2 (latin2), windows-1250
polish-iso Polish characters (note that polish-w1250 is more common!) iso8859-2 (latin2)
romanian Romanian characters iso8859-2 (latin2), windows-1250, iso8859-16
latin2 hungarian, polish-iso, romanian iso8859-2 (latin2)
polish-w1250 Polish characters, windows variant windows-1250
slovak-w1250 Slovak characters, windows variant windows-1250
czech-w1250 Czech characters, windows variant windows-1250
windows-1250 polish-w1250, slovak-w1250, czech-w1250, hungarian, romanian windows-1250
greek Greek characters iso8859-7
turkish Turkish characters iso8859-9
russian-w1251 Russian characters windows-1251
belarussian-w1251 Belarussian characters windows-1251
ukrainian-w1251 Ukrainian characters windows-1251
windows-1251 russian-w1251, belarussian-w1251, ukrainian-w1251 windows-1251
hebrew Hebrew characters iso8859-8-I/windows-1255
chinese-simp Simplified Chinese Multibyte: GBK/GB2312
chinese-trad Tradditional Chinese Multibyte: GBK
chinese-ja Japanese Hiragana/Pinyin Multibyte: GBK
chinese chinese-* Multibyte: GBK
gbk chinese-* Multibyte: GBK

Important notes[edit]

A few notes:

  • The following basic nick characters are always allowed/included: a-z A-Z 0-9 [ \ ] ^ _ - { | }
  • Some combinations can cause problems and will cause an error. For example, combining latin* and chinese-* can not be properly handled by the IRCd and UnrealIRCd will refuse it. Mixing of other charsets might cause display problems. UnrealIRCd will print out a warning if you try to mix latin1/latin2/greek/other incompatible groups.
  • Most Services do not permit registration of UTF8 nicks
  • Casemapping (if a certain lowercase character belongs to an upper one) is done according to US-ASCII, this means that characters like ö and Ö are not recognized as 'the same' and hence someone can have a nick with álpha and someone else Álpha at the same time. This is a limitation of the current system and IRCd standards. Work is underway at the IRCv3 working group to solve this. People should be aware of this limitation. Note that this limitation already existed in channels (in which nearly any characters have always been available for use, and casemapping was also always performed in US-ASCII).
  • There is also no "similar looking character" or "identical looking character" checking. In particular if you enable cyrillic script (eg: russian-utf8) then characters such as cyrillic A and latin A will look the same. This could be abused to impersonate another user by using the identical looking character.

Examples[edit]

Western languages[edit]

For people in Europe and other Latin language countries (requires UnrealIRCd 4.0.17 and above):

set { allowed-nickchars { latin-utf8; }; };

Or, to use the old latin1 characters in western europe:

set { allowed-nickchars { latin1; }; };

Chinese language[edit]

This allows nick names to contain both Simplified Chinese and Traditional Chinese characters (GBK encoding):

set { allowed-nickchars { chinese-simp; chinese-trad; }; };


Helpop[edit]

Other languages:
English • ‎français • ‎中文(台灣)‎

UnrealIRCd has a built-in help system which can be used on IRC. It is intended as a quick-reference for commands and user and channel modes. It's configured through the Help block.

For example when you type /HELPOP CHMODES on IRC you will get an overview of all channel modes UnrealIRCd has. To see the index of all help commands run /HELPOP without parameters.