View source for Linking To Other Servers

{{NeedUpdate}}
= Linking InspIRCd Servers And Services Servers Together =

Most people running an IRC server will want to link it to other IRC servers to form a network. At the very least, you will probably want to run services, or some other pseudo-server to provide some value-added service to your users.

This guide will instruct you on how to get InspIRCd to link servers together, and is valid for any 1.1 version of InspIRCd.

== Getting Started ==

Firstly, you must ensure you have the very latest InspIRCd servers. In the case of services etc, you need the required modules loaded for whichever services you are using. 

Untar and configure all of your programs and build them.

=== Configuration Of InspIRCd For Linking ===

When you configure your InspIRCd servers, the oper configuration (<class> and <type> tags) on every server must be '''identical'''! You must also make sure you load the same modules (maybe even in the same order) on '''all''' servers.

'''IF YOU DO NOT FOLLOW THE INSTRUCTIONS ABOVE EXACTLY, YOU MIGHT GET DESYNCS ON YOUR NETWORK!'''

You will also need to load ''m_spanningtree.so''. The module m_spanningtree.so provides all of the linking features for inspircd, without it, you cannot link servers. Not at all. You can load it by putting the following in your configuration file (''which is not in there by default''):

 <module name="m_spanningtree.so">

When it is loaded, the following types of tag are supported in the configuration file:

 <bind address="" port="7777" type="servers">

Without ''m_spanningtree.so'', the ''servers'' type of port will not be bound and cannot be used. For the sake of this guide, we will assume that you are linking servers on port 7777, but you may change this to whatever you like.

Each server must also have a <link> tag, which allows servers matching that <link> tag to connect. For example, imagine you have two servers, ''server.a'' (with the IP address 4.3.2.1) and ''server.b'' (with the IP address 1.2.3.4), in the configuration of ''server.a'', you would have:

 <link name="server.b"
       ipaddr="1.2.3.4"
       port="7777"
       sendpass="password1"
       recvpass="password2">

...and in the configuration of ''server.b'', you would have:

 <link name="server.a"
       ipaddr="4.3.2.1"
       port="7777"
       sendpass="password2"
       recvpass="password1">

'''NB''': It is also worth pointing out that even though the field in the <link> tag for your server's address is called 'ipaddr', you '''can''' put hostnames here. You probably shouldnt though, as it will take a little longer to connect if it has to resolve a hostname.

==== Advanced Configuration ====

===== Autoconnecting Servers =====

The linking configuration given above will work, however, for more complex situations, you need more advanced settings. The first problem is, with the configuration given above, if there is a connectivity issue and you get a netsplit, the servers will remain split, until an oper comes along and /CONNECT's them again. To alleviate this problem, we can add an ''autoconnect'' tag for the server:

    <autoconnect period="60" server="server.b">

This will cause ''server.a'' to auto connect to ''server.b'' every 60 seconds.

===== Failover Connections =====

Failover connections allow you to automatically connect to a backup server if the server you are trying to link to is down. Also, as part of the failover system, if the backup server is currently up, the server you are trying to link to will never be auto-connected. This allows you to have your network automatically re-route itself around issues. You may configure multiple servers to failover from each other in a chain if you wish, so long as they dont failover in a loop. The syntax for this is:

    <autoconnect period="60" server="server.b server.c">

With this configuration, when you link server.b, if the connection is unsuccessful, then InspIRCd will instantly attempt to link server.c instead. If server.c is unsuccessful, any of its failover settings (if any) are followed. Note that when using failover links, only errors which occur before a connection is accepted are considered to be candidates for a failover. For example, 'Connection refused' or 'Connection timed out' will cause a failover, but 'invalid password' will not. This is because if the server is up and accepts the connection, it is running and just wrongly configured and failover should not occur.

===== Encrypted Server Connections =====

If you want to secure the connection between your servers with encryption, you can enable encryption on the link. To do so, you must ensure that one of m_ssl_openssl.so or m_ssl_gnutls.so is loaded '''before m_spanningtree.so in your configuration file''', as shown below;

 <module name="m_ssl_gnutls.so">
 <module name="m_spanningtree.so">

You may use identical modules on both ends of the link, or you may have one end using openssl and one end using gnutls -- it will still work. You should then update your bind tags, so that the port you accept server connections on is ssl enabled. Use the value 'openssl' if you are using m_ssl_openssl.so, and the value 'gnutls' if you are using the m_ssl_gnutls.so module.

 <bind ipaddr="4.3.2.1" type="servers" ssl="gnutls">

You must now also update your link tag to have a ssl value. Use the same value you used in your <bind> tag;

 <link name="server.b"
       ipaddr="1.2.3.4"
       port="7777"
       autoconnect="60"
       sendpass="password1"
       recvpass="password2"
       ssl="gnutls">

When you link the servers together, they will now be encrypted. When the servers connect, the encryption provider you are using will be shown:

  *** LINK: Verified server connection inbound from 127.0.0.1 (Server Description)
  *** LINK: Bursting to foo.example.com (Authentication: plaintext password).
  *** LINK: Finished bursting to foo.example.com.
  *** LINK: Received end of netburst from foo.example.com (burst time: 44 msecs)

===== U-Lines =====

Services and various other pseudo-servers (such as [http://www.ircdefender.org Defender]) must be [[U lined]]. A U lined server has extra privileges which allow the server to perform such parlour tricks as opping users from outside a channel, or executing commands which are not in the <class> they are using.

If a server must be [[U lined]], then it must be U lined on '''all servers''' (you must not forget one, or that server will attempt to stop mode changes and it all gets desynced), using the following configuration tag:

 <uline server="server.s">

This assumes that we want to uline ''server.s''. If you want to U line several servers, you must have several tags (''do not put several addresses into one tag, this will not work'').

== Linking The Servers ==

On IRC, once you are opered, and the configuration laid out above is in place correctly, you may now link your servers. For the sake of this example, we will assume that you are opered and connected to the ficticious server ''server.a''. You would type this:

 /CONNECT server.b

And, if everything is set up correctly and all goes to plan, you will see text like this in your notices window of your client:

 [15:14] --- *** CONNECT: Connecting to server: '''server.b''' (1.2.3.4:7777)
 [15:14] --- *** Connection to server.b[1.2.3.4] established.
 [15:14] --- *** Bursting to '''server.b'''
 [15:14] --- *** Finished bursting to '''server.b'''

If you had an oper also sitting on ''server.b'', they would in turn see the following:

 [15:14] --- *** Verified incoming server connection from '''server.a'''[4.3.2.1] (Other server)
 [15:14] --- *** Bursting to '''server.a.'''
 [15:14] --- *** Finished bursting to '''server.a.'''

Users will join, servers will merge, and we're done! That's all there is to it!

=== Remote connecting ===

If you want to connect server.b and you are not currently on server.a, you can use the RCONNECT command:

 /RCONNECT server.a server.b

You may use wildcards in either of these fields. All servers matching the wildcard in the first parameter will answer, so if you want to make all servers try to connect to server.b for example, you can issue a command like this:

 /RCONNECT * server.b

Note that in most cases this is not useful, except for when you are trying to relink your network after a particularly large split.

== Taking down Server Links ==

To remove a server which is linked in InspIRCd, connect to the server, and use /SQUIT. For example if you are on ''server.a'' and you want to quit ''server.b'', issue the following command:

 /SQUIT server.b

This will cause ''server.a'' to close its connection to ''server.b''.

=== Remote SQUIT ===

You can use /RSQUIT (which takes one or two parameters) if you want to disconnect a remote server (one youre not directly connected to):

 /RSQUIT server.c server.b

This tells server.b to disconnect its link to server.c.

Optionally, you can issue the command:

 /RSQUIT server.c

Which will tell whichever server has server.c to disconnect it, without explicitly stating where it is.