doc/connecting-servers.rst

   1 Connecting servers
   2 ==================
   3
   4 Servers can be connected together to improve redundancy, distribute bandwidth,
   5 lower latency, and connect network services.
   6
   7 This document is an introduction to connecting servers. It assumes you are
   8 already somewhat familiar with Solanum's configuration (if not, read
   9 :file:`ircd.conf.example`, and set up your own server by editing it
  10 and running Solanum).
  11
  12 Solanum uses the TS6 protocol, and can only be connected with other servers
  13 using this protocol. We recommend you only connect Solanum with other Solanum
  14 instances.
  15
  16 Unlike some other IRCd implementations, all connections are reciprocal in
  17 Solanum, which means a single configuration block is used for both incoming
  18 and outgoing connections.
  19 Additionally, the same ports are used for server and client connections.
  20
  21 Creating servers
  22 ----------------
  23
  24 If you already have a server running, copy its configuration to a new machine,
  25 and edit ``serverinfo`` for the new server. In particular, you must change the
  26 ``name`` and ``sid``, but keep the same ``network_name``.
  27 We recommend you keep both configurations in sync using some external
  28 configuration management systems, so server configurations do not drift apart
  29 over time, as you change them.
  30
  31 For each of the two servers, you must create a ``connect`` block to represent
  32 the connection with the other server. For example, if you have servers A and B
  33 respectively at a.example.org and b.example.org, use respectively::
  34
  35    serverinfo {
  36            name = "a.example.org";
  37            // ...
  38    };
  39
  40    connect "b.example.org" {
  41            host = "203.0.113.2";
  42            port = 6666;
  43
  44            send_password = "password";
  45            accept_password = "anotherpassword";
  46
  47            flags = topicburst, autoconn;
  48
  49            class = "server";
  50    };
  51
  52 and::
  53
  54    serverinfo {
  55            name = "b.example.org";
  56            // ...
  57    };
  58
  59    connect "a.example.org" {
  60            host = "203.0.113.1";
  61            port = 6666;
  62
  63            send_password = "anotherpassword";
  64            accept_password = "password";
  65
  66            flags = topicburst, autoconn;
  67
  68            class = "server";
  69    };
  70
  71 Note the reversed passwords.
  72
  73 The ports should be any of the ports defined in a ``listen {}`` block of the
  74 other server.
  75
  76 The ``autoconn`` flag indicates a server should automatically connect using
  77 this ``connect {}`` block. At least one of the two servers should have it,
  78 or the servers won't try to connect.
  79
  80 If you are connecting servers over an unencrypted link, you should use SSL/TLS
  81 for the connection; see :file:`reference.conf`.
  82
  83
  84 Connecting services
  85 -------------------
  86
  87 In addition to regular servers, you can also connect service packages such
  88 as atheme-services.
  89
  90 These services typically do not accept incoming connections, and connect to
  91 one of the existing servers of the network.
  92
  93 To allow connections from such a service server, you should create
  94 a new ``connect {}`` block for this package, on the server the services
  95 will connect to::
  96
  97    connect "services.example.org" {
  98            host = "localhost";
  99            port = 6666;
 100
 101            send_password = "password";
 102            accept_password = "anotherpassword";
 103
 104            flags = topicburst;  // No autoconn, services don't accept incoming connections
 105
 106            class = "server";
 107    };
 108
 109 And create the appropriate config in your services' configuration so that
 110 they connect to your server on the configured port, and from the configured
 111 hostname.
 112
 113 For example, with atheme::
 114
 115    loadmodule "modules/protocol/solanum";
 116
 117    uplink "a.example.org" {
 118            host = "localhost";
 119            port = 6666;
 120            send_password = "anotherpassword";
 121            receive_password = "password"
 122    };
 123
 124 Finally, you must configure all servers in your network to recognize the
 125 services server::
 126
 127    service {
 128            name = "services.example.org";
 129    };