Set block

From UnrealIRCd documentation wiki
Jump to navigation Jump to search
Other languages:

The set block is used to tweak and configure the server settings.


Sharing settings

If you (already) run multiple IRC servers then have a look at Sharing settings between servers to ease the burden when updating settings. The set block is an ideal candidate to be shared.

Syntax used in this documentation

As described in Configuration file syntax we will refer to settings like set::options::hide-ulines or set::auto-join. When we mention these we don't mean that you should really write set::options::hide-ulines as-is! It's just a shorthand. What we actually mean is you should write them out like this:

set {
        options {
        auto-join "#something";

Or you could put them in separate set blocks like this:

set {
        auto-join "#something";

set {
        options {

Or even just:

set { options { hide-ulines; }; };
set { auto-join "#something"; };

If the above is unclear, then maybe have another read at the Configuration file syntax article.

As you can see from above it's perfectly fine to have multiple set { } blocks! In fact it's quite normal to have one block with network-wide settings and one with server-specific settings. We generally don't recommend having much more separate set blocks as it's easy to loose track of them (and what settings is where), but it is perfectly possible.

Available settings


Syntax: set::kline-address <email-address>

The email address that K:line questions should be sent to. This value must be specified.


Syntax: set::gline-address <email-address>

The email address that G:line questions should be sent to.


Syntax: set::modes-on-connect <+modes>

The modes that will be set on a user at connection.


Syntax: set::snomask-on-connect <+modes>

The snomask that will be set on a user at connection.


Syntax: set::modes-on-oper <+modes>

The modes that will be set on a user when they /oper.


Syntax: set::snomask-on-oper <+modes>

The snomask that will be set on a user when they /oper.


Syntax: set::modes-on-join <+modes>

The modes that will be set on a channel when it is first created. Not all modes can be set using this command. +qaohvbeOAzlLk can NOT be set using this command.


Syntax: set::level-on-join <none|voice|halfop|op|protect|owner>

The mode that a user will get when he's the first to join a channel. The default is 'op' (channel operator).


Syntax: set::restrict-usermodes <modes>

Restrict users to set/unset the modes listed here (don't use + or -). For example you can set +G in modes-on-connect and G in restrict-usermodes, that way you can force all users to be +G and unable to do -G.


Syntax: set::restrict-channelmodes <modes>

Restrict users to set/unset the channelmodes listed here (don't use + or -). For example you can set +G in modes-on-join and G in restrict-channelmodes, that way you can force all (new) channels to be +G and unable to do -G. NOTE: it may still be possible to use these channelmodes through services by using MLOCK. Unfortunately we can't do much about that, you would have to ask the services coders to implement a restrict-channelmodes feature too.


Syntax: set::restrict-extendedbans <types|*>

Don't allow users to use any extended bans ("*") or disallow only certain ones (eg: "qc").


Syntax: set::auto-join <channels>

The channel(s) a user will be forced to join at connection. To specify more than one channel use a comma separated list. [Note: don't forget to add quotes, like: auto-join "#chan"]


Syntax: set::oper-auto-join <channels>

The channel(s) a user will be forced to join when they /oper. To specify more than one channel use a comma separated list. [Note: don't forget to add quotes, like: oper-auto-join "#chan"]


Syntax: set::anti-spam-quit-message-time <timevalue>

A time value specifying the length of time a user must be connected for before a /quit message will be displayed. Used to prevent spam. A time value is a numeric string with d meaning days, h meaning hours, m meaning minutes, and s meaning seconds, for example 1d2h3m means 1 day, 2 hours, 3 minutes.


Syntax: set::prefix-quit <text-to-prefix-quit>

Sets the text that will be used to prefix a quit message. If this value is set to 0 then the standard "Quit:" is used.


Syntax: set::static-quit <quit message>

Sets a static quit message that will be sent whenever a client logs off the network. This eliminates the need for anti-spam-quit-message-time, as well as the set::prefix-quit. It will NOT replace ERRORS with the static-quit message.


Syntax: set::static-part <no|yes|part message>

A value of 'yes' strips all part comments, a value of 'no' makes part just work as usual, anything else will be used as a part comment (eg: static-part "Bye!") but this can be quite annoying, so use with care.


Syntax: set::who-limit <limit>

Sets the limit for the maximum number of matches that will be returned for a /who. If this option is left out, no limit is enforced.


Syntax: set::silence-limit <limit>

Sets the limit on the maximum SILENCE list entries. If this directive is not specified, a limit of 15 is set.


Syntax: set::maxbans <limit>

Sets the limit on the maximum amount of bans (+b) allowed per channel. The default is 60. If you change this, be sure to also take a look at maxbanlength (see next)!


Syntax: set::maxbanlength <limit>

Similar to above, but sets the maximum amount of characters for all bans added up together, so basically this puts up a limit on the (semi-)maximum amount of memory all channel bans on a channel can take. The default is 2048 (bytes). With the default set::maxbans of 60 this allows 2048:60=34 characters per ban on average.


Syntax 1: set::oper-only-stats <stats-list-in-letters>
Syntax 2: set::oper-only-stats {<long-stats-flag1> <long-stats-flag2>}

Specifies a list of /STATS flags that only IRC Operators may see. The default is "*" which will prevent any regular user from using /STATS.

Be careful if you tweak this, some stats are not meant to be exposed to regular users and the information contained in them will often aid attackers / "bad guys".


Syntax: set::nick-length <length>

Specifies the maximum length of a nick name. This default and maximum is 30 (NICKLEN). This setting can only be used to impose a shorter nick length than that.


Syntax: set::maxchannelsperuser <amount-of-channels>

Specifies the number of channels a single user may be in at any one time.


Syntax: set::maxdccallow <amount-of-entries>

Specifies the maximum number of entries a user can have on his/her DCCALLOW list.


Syntax: set::channel-command-prefix <command-prefixes>

Specifies the prefix characters for services "in channel commands". Messages starting with any of the specified characters will still be sent even if the client is +d ("deaf"). The default value is "`!." which is normally a good setting.


Syntax: set::allowed-nickchars { <list> }

Character sets / languages to allow in nick names, see Nick Character Sets.


Syntax: set::allow-userhost-change [never|always|not-on-channels|force-rejoin]

Specifies what happens when the user@host changes (+x/-x/chghost/chgident/setident/vhost/etc). never disables all the commands, always does always allow it even when in channels (may cause client desyncs) [default], not-on-channels means it's only allowed when the user is not on any channel, force-rejoin will force a rejoin in all channels and re-op/voice/etc if needed.


Syntax: set::options::hide-ulines

If this is present, Ulined servers will be hidden in /MAP and /LINKS for regular users (non-ircops). This is a very common thing to do.


Syntax: set::options::flat-map

If this is present, all servers will appear as directly linked in /map and /links, thus you can no longer see which server is linked to which. This is a little help against (D)DoS attacks because evil people now no longer can easily see the 'weak points'.


Syntax: set::options::show-opermotd

If present the opermotd will be shown to users once they successfully /oper.


Syntax: set::options::identd-check

If present the presence of an identd server will be checked and the returned value will be used for the username. If no ident request is returned or the identd server doesn't exist, the user's specified username will be prefixed with a ~. If this value is omitted no such check is made.


Syntax: set::options::show-connect-info

If present notices showing "ident request", "hostname lookup", etc. will be displayed when a user connects.


Syntax: set::options::dont-resolve

If present hosts of incoming users are not resolved, can be useful if many of your users don't have a host to speed up connecting. Note that since no resolving is done you also can't have host based allow blocks.


Syntax: set::options::mkpasswd-for-everyone

Makes it so the /mkpasswd can be used by anyone instead of oper-only, usage of the command by non-opers is sent to the EYES snomask.


Syntax: set::options::allow-part-if-shunned

Allow shunned user to use /part.


Syntax: set::options::fail-oper-warn

If present, a user will be notified that his/her failed /oper attempt has been logged.


Syntax: set::options::allow-insane-bans

Allow insane broad bans like /GLINE *@*.xx. This makes it very easy to accidentally ban everyone on your network, so use with great care!


Syntax: set::options::disable-cap

Disable IRC Client Capabilities Extensions (CAP). Note that this makes SASL and various other features unavailable or harder for clients to use.


Syntax: set::nopost::ban-action (requires m_nopost)

Action to take on a user if he tries to perform an HTTP POST command. The allowed values are: kill, gline, gzline, kline, zline, shun, and tempshun. The default value is kill. If you use a *line value or shun, then note that if gullible user who is tricked into visiting a website exhibiting the XPS IRC spamming attack will experience the shun or *line on his existing connections. The default value of kill protects against such user accidents, but use of *line and especially gzline may be needed in some situations.


Syntax: set::nopost::ban-reason (requires m_nopost)

The ban reason to set when m_nopost kills or bans a user.


Syntax: set::nopost::ban-time (requires m_nopost)

The duration for shuns, glines, gzlines, klines, and zlines set by m_nopost. Default is 4h.


Syntax: set::nopost::except-hosts (requires m_nopost)

A list of hostmasks to exempt from m_nopost's killing or *-lining. You should never need to place any hostmasks in this option.


Syntax: set::dns::bind-ip <ip>

Specifies the IP to bind to for the resolver, rarely ever needed.


Syntax: set::network-name <name-of-network>

Specifies the name of the network on which this server is run. This value should be exactly the same on all servers on a network.


Syntax: set::default-server <server-name>

Defines the name of the default server to tell users to connect to if this server is full.


Syntax: set::default-ipv6-clone-mask

The default IPv6 clone detection mask. See allow::ipv6-clone-mask. The default value for this setting is 64.


Syntax: set::services-server <server-name>

Specifies the name of the server that the services bots are connected to. Required, set it to something like if you don't have services.


Syntax: set::stats-server <server-name>

Sets the name of the server on which the stats bot is located. If stats are not run this value may be left out.


Syntax: set::sasl-server <server-name>

Sets the name of the server to which SASL authenticate messages should be sent.


Syntax: set::help-channel <network-help-channel>

Sets the name of the help channel for this network.


Syntax: set::cloak-method [ip|host]

This sets the method to use when cloaking a user. The default is host which will use hostname-based cloaking (and fallback to IP-based if no host is available). The alternative is to set this to ip which will make UnrealIRCd always do IP-based cloaking. This results in a XX.YY.ZZ.IP cloaked host which provides more anonymity. IRCOps can still see the real hostname of the user and GLINEs and such still work as well.


Syntax: set::cloak-keys { "key1"; "key2"; "key3"; }

UnrealIRCd has a feature called Cloaking. The keys you specify here are used to generate such a +x host. ALL servers on the same network must use the same keys and they must be kept secret.

Each key consists of 50-100 characters, the characters should contain a mixture of: lowercase (a-z), uppercase (A-Z) and digits.

On *NIX you can use ./unreal gencloak to generate 3 random keys.


/* This is just an example, don't actually use these keys yourself!! */
set {
    cloak-keys {

NOTE: If you use a different cloak module than the default, then the cloak-keys may have a different format as well!


Syntax: set::hiddenhost-prefix <prefix-value>

Defines the prefix that will be used on hiddenhosts (+x). This is usually three or four letters representing the network name. Linked servers must have the same hidden-host prefix for channel bans to function properly.


Syntax: set::ssl::certificate <filename>

Specifies the filename where the server's SSL certificate is located. The default is server.cert.pem.


Syntax: set::ssl::key <filename>

Specifies the filename where the server's SSL private key is located. The default is server.key.pem.


Syntax: set::ssl::trusted-ca-file <filename>

Specifies the filename where the certificates of the trusted CAs are located. The default is curl-ca-bundle.crt (shipped with UnrealIRCd)


Syntax: set::ssl::protocols <list-of-protocols>

Specifies which SSL/TLS protocols are permitted. Available options are: All, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3 (the latter when it becomes available). Prefix the protocol with a - (minus sign) to remove it.

Example: set { ssl { protocols "All,-TLSv1,-TLSv1.1"; /* permit only TLSv1.2 and up */ }; };

See SSL Ciphers and protocols for more information and suggestions on a good setting.


Syntax: set::ssl::ciphers <cipherlist>

NOTE: This setting was previously called set::ssl::server-cipher-list.

Specifies which ciphers to be allowed. See SSL Ciphers and protocols for more information and suggestions on a good setting.


Syntax: set::ssl::renegotiate-bytes <value>

Specifies after how many bytes an SSL session should be renegotiated (eg: 20m for 20 megabytes).


Syntax: set::ssl::renegotiate-timeout <timevalue>

Specifies after how much time an SSL session should be renegotiated (eg: 1h for 1 hour).


Syntax: set::ssl::options::fail-if-no-clientcert

Forces clients that do not have a certificate to be denied. This would be an unusual setting to enable.


Syntax: set::ssl::options::no-starttls

Disable STARTTLS. STARTTLS allows clients to use SSL/TLS on regular (non-SSL) ports, which is normally a good thing.


Syntax: set::ssl::sts-policy::port <portnumber>

Set the port number that STS-capable clients should use for SSL. The recommended value is 6697.


Syntax: set::ssl::sts-policy::duration

Set the time for the STS policy to persist. You may want to start with a small value like '1m' for 1 minute. After everything works fine you can expand to something like '1d' or '180d' (1 day and 180 days respectively).


Syntax: set::ssl::sts-policy::preload [yes|no]

This indicates that you are OK with being added to the IRC STS preload list. This is only useful if you apply to the STS preload list. At the time of writing this there is no known preload list where you can submit your entry.


The plaintext-policy block allows you to configure what UnrealIRCd should do with users/opers/server who are not connected via SSL/TLS.

set {
    plaintext-policy {
        user allow; /* must be one of: allow, warn, deny */
        oper allow; /* must be one of: allow, warn, deny */
        server warn; /* must be one of: allow, warn, deny */

An action of allow will allow the operation. The warn action will make the server send a warning notice. The deny action will reject the user/oper/server, in this case the user cannot connect, the ircop cannot /OPER and the server may not link.

The defaults as of UnrealIRCd 4.0.14 are very liberal. A safer choice would be to deny IRCOp's from /OPER'ing from insecure connections and doing the same for insecure server linking:

set {
    plaintext-policy {
        user allow;
        oper deny;
        server deny;

Optionally you can set a set::plaintext-policy::user-message and set::plaintext-policy::oper-message to change the default UnrealIRCd warn/deny text the user/ircop will receive.


Syntax: set::ident::connect-timeout <amount>

Amount of seconds after which to give up connecting to the ident server (default: 10s).


Syntax: set::ident::read-timeout <amount>

Amount of seconds after which to give up waiting for a reply (default: 30s).


Syntax: set::handshake-timeout <amount>

Amount of seconds that a connection may be in the "handshake state", that is: the period between a TCP/IP connection accept() and the user getting online after NICK/USER have been received and DNS and ident lookups have completed (if those are enabled).

The default is 30 which is a safe value for everyone. Be careful if drastically lower this. DNS lookups, ident lookups and the handshake may take more time than you may think in some cases. You can probably set this to a value like 20 if you like. However, if you set this setting too low then you risk locking everyone out when for example your DNS server is a little slow (eg: under attack).


Syntax: set::anti-flood::connect-flood <count>:<period>

Connection flood protection: limits the number of connection attempts from each IP to 'count' per 'period' seconds. Default is 3 per 60. This feature is also referred to as connection throttling.

Note that connection throttling is an important security measure. It provides primary and secondary protection against DoS, flood and brute force attacks, both for handshake and fully registered connections. If you disable it or set it very permissive (eg 6 per 60 seconds) then you severely degrade these protections.


Syntax: set::anti-flood::nick-flood <count>:<period>

Nickflood protection: limits nickchanges to 'count' per 'period' seconds. For example nick-flood 4:90 means 4 per 90 seconds, the default is 3 per 60.


Syntax: set::anti-flood::join-flood <count>:<period>

Join flood protection: limits joins (to the same channel) to 'count' per 'period' seconds. For example join-flood 4:90 means 4 per 90 seconds, the default is 3 per 90. Previously this was configured through channel mode +j.


Syntax: set::anti-flood::away-flood <count>:<period>

Away flood protection: limits /away to 'count' changes per 'period' seconds. Example: away-flood 5:60s means max 5 changes per 60 seconds.


Syntax: set::anti-flood::unknown-flood-amount <amount>

When we receive a connection from a user and this user sends more than <amount> kilobytes of data BEFORE actually coming online (a so called "unknown connection") then the user will be killed.


Syntax: set::anti-flood::unknown-flood-bantime <timevalue>

Specifies for how long an unknown connection flooder is banned (see also previous item).


Syntax: set::default-bantime

Default bantime when doing /KLINE, /GLINE, /ZLINE, GZLINE, /SHUN, etc without a time parameter (like /GLINE *@some.nasty.isp), the default is permanent (0). Example: default-bantime 90d


Syntax: set::modef-default-unsettime <value>

For channelmode +f you can specify a default unsettime, if you specify 10 for example then a /MODE #chan +f [5j]:15 will be transformed to [5j#i10]:15. The default is no default unsettime.


Syntax: set::modef-max-unsettime <value>

The maximum amount of minutes for a mode +f unsettime (in +f [5j#i


Syntax: set::ban-version-tkl-time <value>

If you specify an 'action' like zline/gline/etc in a Ban version block, then you can specify here how long the IP should be banned, the default is 86400 (1 day).


Syntax: set::spamfilter::ban-time <value>

Same as above but for *lines/shuns added by spamfilter


Syntax: set::spamfilter::ban-reason <reason>

Default reason to use for entries added by spamfilter


Syntax: set::spamfilter::virus-help-channel <channel>

The channel to use for the 'viruschan' action in spamfilter


Syntax: set::spamfilter::virus-help-channel-deny <yes|no>

If set to yes (or '1') it replies 'invite only' to any normal users that try to join the virus-help-channel. Only opers, people that match spamfilters and people that are /invite'd can join.


Syntax: set::spamfilter::except <target(s)>

These targets are exempt from spam filtering (no action will be taken), can be single target or comma separated list.. Ex: except "#help,#spamreport"


Syntax: set::spamfilter::detect-slow-warn <value>

If a spamfilter takes longer than this amount of milliseconds to execute (1000ms = 1 second), then a warning notice will be sent to all opers (default: 250). See also Spamfilter#Slow Spamfilter Detection


Syntax: set::spamfilter::detect-slow-fatal <value>

If a spamfilter takes longer than this amount of milliseconds to execute (1000ms = 1 second), then the spamfilter will be removed (default: 500). See also Spamfilter#Slow Spamfilter Detection


Syntax: set::check-target-nick-bans <yes|no>

Whenever the user changes his/her nick, check if the NEW nick would be banned. If so, do not allow the nickchange. Default is yes.


Syntax: set::timesynch::enabled <yes|no>

Enable or disable time synchronization on-boot. Default is yes.


Syntax: set::timesynch::server <IP>

Server(s) to synchronize time with. This can be up to 4 IP's separated by comma's. The servers must support NTP protocol version 4. The default is to use 3 time servers (US, EU, AU). Requests to these servers are sent in parallel, fastest reply wins.


Syntax: set::timesynch::timeout

Maximum time to wait for a time server reply. This is a value between 1 and 5, more is not possible because it causes too much inaccuracy. This setting is 3 by default and there's probably no good reason to change it.


Syntax: set::ping-cookie <yes|no>

When a client connects, send a "ping cookie" consisting of a random string that the client should respond with. All clients should cope with this and do so without bothering the user. Ping cookies are a security measure. It helps in preventing blind HTTP-POST attacks and similar security issues. It also helps against TCP spoofing on very old operating systems.

The default is yes (enabled).


Syntax: set::watch-away-notification <yes|no>

Allows you to enable/disable AWAY notification in WATCH. The default is yes (enabled).


Syntax: set::hide-ban-reason <yes|no>

This will hide the *LINE reason to anyone except the user being killed. This allows you to enter a personal message in commands like /GLINE that will not be publicly displayed.


Note that you need to load this module explicitly (it is not loaded by default):

loadmodule "antirandom";

set {
        antirandom {
                /* THRESHOLD:
                 * This is pretty much the most important setting of all.
                 * For every randomly looking ident the user gets a certain amount of
                 * 'points', if this value reaches 'threshold' then the appropriate
                 * action is taken (killed, *lined, see later on).
                 *  lower = more randomly looking users will be catched (but also more
                 *          innocent users)
                 * higher = less chance of innocent users getting killed, but also less
                 *          chance on bots getting catched.
                 * <2:  DON'T!!
                 *  4:  Works good, probably a few more innocent kills but if you got
                 *      quite a bot problem then this might be a useful setting.
                 *  5:  Works well with few innocent kills, probably good to begin with.
                 *  6:  If you want to be a tad more careful
                 * >6:  For the paranoid. Module can still be quite effective, though :)
                threshold 5;

                /* BAN-ACTION:
                 * Action to take whenever the user is catched as random, options:
                 * warn, kill, gline, gzline, kline, zline, shun, tempshun
                ban-action kill;

                /* BAN-TIME:
                 * Time to ban the user (irrelevant for tempshun/kill).
                 * Something between 1 hour and 2 days is recommended.
                 * If you set it higher than 3 or 4 days then you get quite a risk
                 * of catching innocent users due to dynamic IP, not to mention
                 * your *line list gets filled up... so choose it wisely.
                ban-time 4h;

                /* BAN-REASON:
                 * The ban (or kill) reason to use.
                 * You might want to put in an entry to a FAQ or an email address
                 * where users can mail if they have been catched and don't know what to do.
                 * NOTE: One of the various reasons that ""innocent users"" are catched is
                 *       if they just randomly type in info for their nick, ident, or realname.
                ban-reason "You look like a bot. Be sure to fill in your nick/ident/realname properly.";

                /* CONVERT-TO-LOWERCASE:
                 * Convert nicks, idents, and realnames to lowercase before doing random checks?
                 * This has not been tested extensively for false positives, but might be (very)
                 * helpful to catch GnStA5FYhiTH51TUkf style random nicks as random.
                 * Enabled by default.
                convert-to-lowercase yes;

                /* FULLSTATUS-ON-LOAD:
                 * If enabled, then upon loading it will check all users that are currently
                 * connected and give a status report about who it would have killed.
                 * Note that it doesn't actually kill any currently connected users, it is for
                 * informative purposes only.
                 * This can be (very) useful if you use the module for the first time.
                 * But you probably want to disable it after a while, since once the module
                 * is actively dealing with randomly looking persons, it shouldn't report any
                 * users anymore on load and then this check only eats useless CPU on /REHASH.
                 * Enabled by default.
                fullstatus-on-load yes;

                /* SHOW-FAILEDCONNECTS:
                 * This will send out a notice whenever a randomly looking user has been catched
                 * during connecting. Obviously this can be pretty noisy.
                 * Especially recommended to enable during the first few days you use this module.
                show-failedconnects yes;

                /* EXCEPT-HOSTS:
                 * Hostmasks on this list are matched against the IP and hostname of the connecting
                 * user. If it matches then we do not check if the nick/ident/realname is random.
                 * If you are using CGI:IRC on your network, then you probably want to put that
                 * IP/host here.
                 * NOTE: Use the REAL host or IP here, not any cloaked hosts!
                except-hosts {

This allows you to specify which channels should be hidden from list. Right now it only supports one option: deny-channel. This will hide channels that the user cannot join due to deny channel { } restrictions:

set { hide-list { deny-channel; }; };

Note that secret channels (channel mode +s) are always hidden and IRCOps always override restrictions (if they have sufficient access).


UnrealIRCd limits the number of connections per IP that are in an "unknown" state, that is: connections that are in a handshake. This is a security setting and it defaults to 3.

Only in very rare circumstances this may need to be adjusted. For example if you have hundreds of users coming from the same IP.

Example: set { max-unknown-connections-per-ip 3; };


By default UnrealIRCd will place bans from spamfilter (and other automatic bans) on *@ip. You can change this to have bans placed on user@ip. This can be useful if you have some unusual amount of trust in idents ;). Note that this doesn't help against zlines/gzlines since ident requests and handshakes (including receiving the username) don't take place for (G)ZLINE's.

Example (this is the default setting): set { ban-include-username no; };