IRCOp guide

From UnrealIRCd documentation wiki
Jump to navigation Jump to search
Other languages:
English • ‎français

This is a guide for everyone who has their IRC server up and running and now needs to understand how to do server administration. In other words: how to perform IRCOp tasks.

Before you read this[edit]

This guide assumes you have basic understanding of IRC. You are familiar with concepts like nicks, channels, user modes and channel modes.

What is an IRCOp?[edit]

On IRC people with special server privileges are called "IRC Operators", often shortened to "IRCOps" or "opers".

How to become an IRCOp[edit]

When setting up your server you should have added an Oper block. Then on IRC, you can type /OPER name-in-operblock password to become IRCOp. Note that both the name and password are case sEnSiTiVe.

If you have problems /OPER'ing up, see: FAQ: How to become IRCOp / administrator

There are various levels of IRCOp's. The operclass directive in the oper block will set this level. The highest is netadmin (which is in the default example configuration file), or netadmin-with-override (more about that later).

NOTE: The sections below will assume you managed to become an IRCOp.


IRCOps have a lot of power. There are different ways to deal with this power. Let's introduce the two most popular principles / codes of conduct. It's up to you to decide which one you favor more. Of course, the options aren't as black/white as outlined below:

IRCOps control everything[edit]

IRCOps are permitted to join any channel, become a channel operator everywhere and reserve the right to do so whenever they deem fit. IRCOps "outrank" channel ops/owners and they are free to use that power with no restrictions.

This is often the idea someone has when setting up his/her first server. It also fits a centrally managed server where all channels are only managed by server staff.

IRCOps don't interfere with channel matters[edit]

This view is quite different than the previous one:
When there is a problem in a channel that can be resolved by the channel owners / channel operators, it is up to the channel staff to resolve the situation. Channel ops/owners can kick or ban a user, there's no need for an IRCOp to interfere. IRCOps will only take actions when security is at stake or users are harassed/spammed via private messages (PM).

This is the most popular principle for more established servers. It allows more freedom to users.

Killing and banning users from the server[edit]

Killing a user (KILL)[edit]

You can forcefully disconnect a user by issuing a KILL. You do this with /KILL nickname reason. The user can still reconnect.

You can also ban a user for a specified amount of time (or permanently). This comes in a few flavors:

Banning a user from the server (KLINE)[edit]

To ban a user from the server you can use /KLINE user@host duration reason. The duration is in seconds or a time expression such as 1h or 1d. Use a duration of 0 (zero) for a permanent ban.
Example: /KLINE * 3600 please go away for at least an hour
This will ban all users with the host for 3600 seconds (one hour).

Note that if you have a network that consists of multiple linked servers then a KLINE is generally not that useful since the user can just reconnect to another server of the IRC network. You'll want to use a GLINE instead, see next.

Banning a user from the network (GLINE)[edit]

To ban a user on the IRC network (so also on other linked servers), use /GLINE user@host duration reason.
Example: /GLINE * 7200 please go away for at least two hours


In short: only use ZLINE or GZLINE if you understand the downsides, it's better to use KLINE or GLINE for normal bans, as already explained above. Read below for the long detailed version:

In addition to KLINE (local ban) and GLINE (network ban) there is also ZLINE and GZLINE. These are special, in the sense that users matching (G)ZLINE's are killed immediately when they attempt to connect to the server. In contrast, KLINE/GLINE which let's the user perform a hanshake. There are pro's and con's to this:

Because (G)ZLINE bans are enforced immediately they cause very little load on the server, they are very efficient. On the other hand there are no DNS lookups done, no ident lookups, no nickname or username is known, SSL/TLS connections are never established. In short: it has a lot of downsides too, but it can be used if your server is under attack by a lot of clones.

In general our advice is not to use (G)ZLINE but to use KLINE/GLINE instead. Only use (G)ZLINE against drone attacks.

If you do want to use (G)ZLINE the syntax is: /GZLINE *@ip duration reason. Note that ZLINE is for local bans and GZLINE for network-wide.
Example: /GZLINE *@ 900 Have a 15 minute timeout
As mentioned above, you need to specify an IP address and cannot use an hostname because DNS lookups are not done.

Advanced bans[edit]

Instead of banning on user@host or user@ip, it is also possible to use Extended server bans to ban on other user properties, such as account names, real name (gecos) and certificate fingerprints.

Ban exceptions[edit]

Once you start banning users you may want to add ban exceptions. For example you may want to add an exception so you don't accidentally end up banning yourself.

On IRC you can do this via the ELINE command. For example /ELINE *@ kGzZ 0 Trusted user would exempt that IP address from klines, glines, zlines and gzlines. Just type /ELINE to see the syntax and possible options.

You can also use the configuration file to exempt IP addresses (and hosts) from bans. You do this by adding an Except ban block. Add this to your unrealircd.conf file and rehash:

except ban {
	mask *@;
	type all;

Removing bans[edit]

To remove a ban created with an IRC command, use the same command and prefix - to the hostmask, with no duration or reason. For example: /KLINE -user@host.

To remove a ban created via the configuration file, remove it from the configuration and rehash.

Getting information[edit]

As an IRCOp you can gather a lot of information about the server, users and channels. Below are the most common examples.

Server notices (Snomasks)[edit]

As an IRCOp you will see notices in your status window such as users connecting/disconnecting:

*** Client connecting: The_User ( [] {clients} [secure ECDHE-RSA-AES256-GCM-SHA384]

The type of messages you receive are controlled via Snomasks.

User list (WHO)[edit]

As an IRCOp you can use /WHO without parameters to see ALL users on the network. (Non-IRCOps will only see users that are "visible", such as in the same channel).

There are some useful parameters that you can use as IRCOp such as /WHO +R to see all real hosts, and /WHO +I to see all IP addresses.

User details (WHOIS)[edit]

You are (hopefully) already familiar with the /WHOIS nickname command. As an IRCOp you can use this same command but you will see additional information, such as: the IP address of the user, all the channels the user in (even if they are secret), the user modes that are set and the current reputation score.

Channel list (LIST)[edit]

All users can use /LIST but if you issue this command as an IRCOp you will be able to see all channels, even if they are secret.

Channel mode querying (MODE)[edit]

You can see the modes of a channel without joining via /MODE #channel. Similarly you can see the banlist via /MODE #channel b.

Topic querying (TOPIC)[edit]

You can see the topic of a channel without joining, by using /TOPIC #channel.

See channel members (NAMES, WHO)[edit]

As an IRCOp you can see who is inside a channel, without joining the channel. Simply issue /NAMES #channel or /WHO #channel

Taking control of channels (Override)[edit]

As an IRCOp you can (with sufficient privileges) join a channel and do the same tasks as a channel operator of that channel. Note that it is highly debated matter whether this is 'good' or 'bad'. See also #Principles earlier.

In UnrealIRCd we call this "overriding", since you override the normal channel rules and behave like a chanop.

IMPORTANT: If you want to use this then you need to use the -with-override operclasses. For example if your Oper block has operclass netadmin you won't be able to override, you need to use operclass netadmin-with-override (and rehash of course).

Joining a channel even if you normally cannot[edit]

Say, you have a channel #drones you want to join because you suspect this to be a channel with troublemakers. If you try to /JOIN you will see a message like Channel is invite only (+i).

You can still join the channel (=override) by inviting yourself and retrying the join:

/INVITE myself #drones
/JOIN #drones

Note: if this doesn't work then read previous block about operclass.

An alternative is to use SAJOIN. This is not available for all operclasses but is available with netadmin-with-override:

/SAJOIN myself #drones

Both the INVITE+JOIN and SAJOIN allow you to bypass all channel modes and all bans.

Changing modes (MODE, SAMODE)[edit]

If you have override privileges you can simply use a MODE command like /MODE #channel -i. You can set the modes even if you don't have channel operator status.

There is also the command /SAMODE #channel -i. This will make the MODE appear from the server:

*** sets mode: -i

Kicking users (KICK, SAPART)[edit]

If you have override privileges you can simply kick users like /KICK #channel nickname reason

There is also a command to forcefully part someone, in which case most clients won't auto-rejoin the user. This is /SAPART nick #channel

Making yourself unkickable[edit]

If you have sufficient privileges you can set user mode +q on yourself like this:

/MODE yournick +q

This makes it so you cannot be kicked by anyone in any channel.

This is naturally highly abusive. Sometimes it is necessary, though, such as when you join a channel with troublemakers and they refuse any form of communication and keep kicking you.


Most networks will run "Services". These are usually visible via the (pseudo) users "NickServ" and "ChanServ". Users can register their nick names and channels at services to claim "ownership" of their nicks/channels. This also helps with preserving settings between server restarts. If you want this you will have to install additional software. See Services.

Note: Setting up services takes at least an hour for most people. It's worth the effort, but be prepared to take some time for it. If you only just set up your first IRC server, then play around a little first before you setup Services another day.

Linking servers[edit]

If you want to run a multi-server IRC network then you will have to "link" multiple servers. Basically you set up 2 or more servers first and then "link" them together. The users on server A will then also be visible on server B and vice-versa. The same is true for channels and global bans such as GLINES. See Tutorial: Linking servers.

NOTE: Linking is by many beginners considered to be a complex topic so if you are just setting up your first server you may want to hold off until you have at least a couple of users before you set up a 2nd server and try to link them together.

Fighting spam and drones[edit]

Once your servers gets more popular you may have to deal with users spamming other users/channels and perhaps a drone attack as well.

Use blacklists[edit]

To fight troublemakers you should add one or more Blacklist blocks. The blacklists under Example in that article are a good start.

What this does is query an external service for each and every connecting user. If the user is on the blacklist (eg: known proxy or known troublemaker on multiple IRC networks), the user is banned.

Use connthrottle[edit]

During a drone attack, when hundreds of bots/drones connect to your server in a short time, the connthrottle module will rate-limit those new connections, while still allowing (almost) all your regular users in.

The connthrottle module is already loaded and enabled by default. See the Connthrottle page for more information.

Use antirandom[edit]

Antirandom is a module that will automatically ban users that have a nickname/username/realname that looks "too random". Note that this may not work very well for non-English/non-Western languages.

To use this, have a look at conf/modules.optional.conf and copy-paste the entire section involving antirandom to your unrealircd.conf.

Use spamfilter[edit]

UnrealIRCd has a very effective, but also slightly complex, tool called Spamfilter. It allows you for example to automatically GLINE anyone saying "Hi plz download:" in a channel. It can react on private messages, channel messages, dcc's and more. You can use simple matching but also regular expressions. See the Spamfilter article for full information.

Other measures[edit]

A very effective anti-flood feature that you should definitely deploy is Channel Mode +f.

Preserving settings between restarts[edit]

In the past, all settings that you changed dynamically (settings that are not in the configuration file) were lost after a server restart. However, nowadays with UnrealIRCd 5 this is less of an issue:

  • Channel settings are normally lost. However, if you set the channel mode +P (permanent), then all modes, topic, bans, etc. are preserved. The channel settings of all +P channels are written every few minutes to a database file (data/channel.db) and restored when the server boots.
  • KLINEs, GLINEs, SPAMFILTERs are all stored in a database (data/tkl.db) and are preserved.

Of course, when a server restarts then it will start with having 0 users online. All channels will have 0 users as well. For users to regain channel operator status (ops) and manage channels you normally use Services.