Troubleshooting: linking servers

From UnrealIRCd documentation wiki
Jump to: navigation, search

This article will help you troubleshoot problems when linking servers

Before you read on, three important things:

  • Linking changed significantly in UnrealIRCd 4 and we have a good Linking servers tutorial that show secure best practices. If you're new or upgrading from 3.2.x to UnrealIRCd 4 we highly recommend you read it.
  • We highly recommend to have an IRCOp on both servers (the one you are linking from and the one you are linking to) to see the actual error from both servers' perspective. This is because the error on one side of the link is generally much more verbose than the other side!
  • As an IRCOp, type /CONNECT name.of.other.server now to ask UnrealIRCd to establish a link between this server and name.of.other.server. Watch the server notices and then lookup the error below.

Server .. is not configured for linking

If you see something like: *** Connect: Server is not configured for linking

This means that in the unrealircd.conf of there is no link block for Verify your configuration, verify you /REHASH'd the server and make sure you don't have any configuration warnings/errors when you REHASH. Also, you may want to check out out Linking servers tutorial and go through it one more time.

Unable to resolve hostname

If you see this: *** Notice -- Unable to resolve hostname 'x.y.z', when trying to connect to server

Then this means you have a link block in the unrealircd.conf of like this:

link {
    outgoing {
        hostname x.y.z;

What UnrealIRCd does is try to connect to this server by the hostname x.y.z. Apparently that hostname does not exist. Simply fix the hostname, use an IP, or fix your DNS.

Then /REHASH your server, make sure you don't see any configuration warnings/errors, and re-try linking.

No link block named '....'

If you get an error like this: *** LocOps -- Link denied for (No link block named '') [@]

Then this means that on there is no link block for

If you have two servers, and then in's config you should have a link block like:

..many more options here..

And similarly, in's config:

..many more options here..

Note that the server names stated here are the same names as in me::name on the other side. They can be completely fictional names that don't even exist on the internet (not in DNS) but the link block name must match with the me::name of the other side.

Once fixed, /REHASH the server(s) you just edited the configuration file(s) of and try linking again.

Link block '...' exists but has no link::incoming::mask

If you get an error like: *** LocOps -- Link denied for (Link block '' exists but has no link::incoming::mask) [@]

Then open up the configuration file on and jump to your link block for You need to add a link::incoming subsection if you want to accept an incoming link, like this:

    incoming {
        mask *;
    ...keep the rest of your options here...

Then /REHASH the server you just edited the configuration file of and try linking again.

NOTE: The mask * allows a server with any IP to link in. You can also add a more restrictive mask like or 1.2.* if the IP on the other side stays the same or is limited to a netblock. But before you do so, we recommend to try with a * mask first to see if the link works at all.

Link denied (Authentication failed)

The error looks like this on the outgoing side of a link: *** LocOps -- ERROR :from[localhost] -- Closing Link: [] (Link denied (Authentication failed))

And like this on the incoming side: *** LocOps -- Link denied for '' (Authentication failed [Bad password?]) [@]

This means the passwords (or actually authentication information) on both sides of the link don't match.

In our Linking servers tutorial we recommend to use SSL fingerprints as a password. If you don't use it already, we suggest you switch over to it now. In particular, refer to that tutorial (step 3 & 4) and make sure you are using the correct fingerprint on each side (eg: maybe you have them swapped?).

If you don't want to use SSL fingerprints then you can use a plaintext password like this:

link {
    password "something";

Make sure the password is the same on both sides. /REHASH both servers to ensure the new configuration file is loaded (watch out for any warnings or errors!). And then try linking again.

No error. Just "Connecting to..." and then nothing *** Connecting to[].

This means UnrealIRCd is trying to connect to the server with the link block and it has a link::outgoing::hostname that resolves to

If it then remains silent for a long time, then apparently this connect fails.

You could check on the other side of the link (on in this case) as an IRCOp (/OPER'ed up) to see if you get a more meaningful error on that side. Chances are you won't see any error at all, in that case you know the other side doesn't even see the link connecting in.

First, verify that the link::outgoing::hostname you use is correct. On (in our example) go to your link block, it will look like this:

link {
    outgoing {
        hostname x.y.z;
        port 6900;

Try connecting with your IRC client to x.y.z on port 6900. Does it connect at all?

Common causes

  • Router: if the other side ( in our example) is located behind a router then you can't just connect to it. You will have to set up port forwarding. Presumably you already have done so for port 6667 so IRC clients can connect, now you need to do the same for the server port as well (6900 in our example).
  • Firewall: a firewall is preventing the connection, most likely on in our example. It's also possible that another firewall in-between is blocking the connection (eg: your ISP) or that is blocking outgoing connects (unusual, but perfectly possible)