From 5c914e40fac54051fdaccba490bcebfa6d0f5b7b Mon Sep 17 00:00:00 2001 From: Valentin Lorentz Date: Sun, 27 Jun 2021 19:20:16 +0200 Subject: [PATCH] Add a tutorial for connecting servers and services. --- doc/connecting-servers.rst | 129 +++++++++++++++++++++++++++++++++++++ doc/ircd.conf.example | 2 + doc/reference.conf | 4 +- 3 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 doc/connecting-servers.rst diff --git a/doc/connecting-servers.rst b/doc/connecting-servers.rst new file mode 100644 index 00000000..c97b6176 --- /dev/null +++ b/doc/connecting-servers.rst @@ -0,0 +1,129 @@ +Connecting servers +================== + +Servers can be connected together to improve redundancy, distribute bandwidth, +lower latency, and connect network services. + +This document is an introduction to connecting servers. It assumes you are +already somewhat familiar with Solanum's configuration (if not, read +:file:`ircd.conf.example`, and set up your own server by editing it +and running Solanum). + +Solanum uses the TS6 protocol, and can only be connected with other servers +using this protocol. We recommend you only connect Solanum with other Solanum +instances. + +Unlike some other IRCd implementations, all connections are reciprocal in +Solanum, which means a single configuration block is used for both incoming +and outgoing connections. +Additionally, the same ports are used for server and client connections. + +Creating servers +---------------- + +If you already have a server running, copy its configuration to a new machine, +and edit ``serverinfo`` for the new server. In particular, you must change the +``name`` and ``sid``, but keep the same ``network_name``. +We recommend you keep both configurations in sync using some external +configuration management systems, so server configurations do not drift apart +over time, as you change them. + +For each of the two servers, you must create a ``connect`` block to represent +the connection with the other server. For example, if you have servers A and B +respectively at a.example.org and b.example.org, use respectively:: + + serverinfo { + name = "a.example.org"; + // ... + }; + + connect "b.example.org" { + host = "203.0.113.2"; + port = 6666; + + send_password = "password"; + accept_password = "anotherpassword"; + + flags = topicburst, autoconn; + + class = "server"; + }; + +and:: + + serverinfo { + name = "b.example.org"; + // ... + }; + + connect "a.example.org" { + host = "203.0.113.1"; + port = 6666; + + send_password = "anotherpassword"; + accept_password = "password"; + + flags = topicburst, autoconn; + + class = "server"; + }; + +Note the reversed passwords. + +The ports should be any of the ports defined in a ``listen {}`` block of the +other server. + +The ``autoconn`` flag indicates a server should automatically connect using +this ``connect {}`` block. At least one of the two servers should have it, +or the servers won't try to connect. + +If you are connecting servers over an unencrypted link, you should use SSL/TLS +for the connection; see :file:`reference.conf`. + + +Connecting services +------------------- + +In addition to regular servers, you can also connect service packages such +as atheme-services. + +These services typically do not accept incoming connections, and connect to +one of the existing servers of the network. + +To allow connections from such a service server, you should create +a new ``connect {}`` block for this package, on the server the services +will connect to:: + + connect "services.example.org" { + host = "localhost"; + port = 6666; + + send_password = "password"; + accept_password = "anotherpassword"; + + flags = topicburst; // No autoconn, services don't accept incoming connections + + class = "server"; + }; + +And create the appropriate config in your services' configuration so that +they connect to your server on the configured port, and from the configured +hostname. + +For example, with atheme:: + + loadmodule "modules/protocol/charybdis"; + + uplink "a.example.org" { + host = "localhost"; + port = 6666; + send_password = "anotherpassword"; + receive_password = "password" + }; + +Finally, you must configure all servers in your network to recognize the +services server:: + + service { + name = "services.example.org"; + }; diff --git a/doc/ircd.conf.example b/doc/ircd.conf.example index 2c04a0a5..19475b93 100644 --- a/doc/ircd.conf.example +++ b/doc/ircd.conf.example @@ -306,6 +306,8 @@ operator "god" { privset = "admin"; }; +// See connecting-servers.rst for an introduction to using these files. + connect "irc.uplink.com" { host = "203.0.113.3"; send_password = "password"; diff --git a/doc/reference.conf b/doc/reference.conf index ac826308..b2ea6c49 100644 --- a/doc/reference.conf +++ b/doc/reference.conf @@ -548,7 +548,9 @@ operator "god" { /* connect {}: controls servers we connect to (OLD C:, N:, H:, L:) */ connect "irc.uplink.com" { - /* the name must go above */ + /* the name of the other server must go above. It should match the + * other server's name in its serverinfo {} block, and does not + * need to be an actual hostname. */ /* host: the host or IP to connect to. If a hostname is used it * must match the reverse dns of the server.