Troubleshooting: linking servers

This article will help you troubleshoot problems when linking servers

Before you read on, three important things:

• We highly recommend the Linking servers tutorial that show secure best practices.
• 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:

-beta.test.net- *** Connect: Server alpha.test.net is not configured for linking

This means that in the unrealircd.conf of beta.test.net there is no link block for alpha.test.net. 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:

-beta.test.net- *** Notice -- Unable to resolve hostname 'x.y.z', when trying to connect to server alpha.test.net.

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

link alpha.test.net {
    outgoing {
        hostname x.y.z;
--etc--

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:

-alpha.test.net- *** LocOps -- Link denied for beta.test.net([email protected]) (No link block named 'beta.test.net') [@127.0.0.1.36514]

Then this means that on alpha.test.net there is no link block for beta.test.net.

If you have two servers, alpha.test.net and beta.test.net then in alpha.test.net's config you should have a link block like:

link beta.test.net
{
..many more options here..

And similarly, in beta.test.net's config:

link beta.test.net
{
..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:

-alpha.test.net- *** LocOps -- Link denied for beta.test.net([email protected]) (Link block 'beta.test.net' exists but has no link::incoming::mask) [@127.0.0.1.36514]

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

link beta.test.net
{
    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 1.2.3.4 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:

-beta.test.net- *** LocOps -- ERROR :from alpha.test.net[localhost] -- Closing Link: [127.0.0.1] (Link denied (Authentication failed))

And like this on the incoming side:

-alpha.test.net- *** LocOps -- Link denied for 'beta.test.net' (Authentication failed [Bad password?]) [@127.0.0.1.39234]

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 alpha.test.net {
--snip--
    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

-beta.test.net- *** Connecting to alpha.test.net[1.2.3.4].

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

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 alpha.test.net 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 beta.test.net (in our example) go to your link block, it will look like this:

link alpha.test.net {
    outgoing {
        hostname x.y.z;
        port 6900;
--etc--

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 (alpha.test.net 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 alpha.test.net in our example. It's also possible that another firewall in-between is blocking the connection (eg: your ISP) or that beta.test.net is blocking outgoing connects (unusual, but perfectly possible)