[X2serv-cvs] CVS: x2/doc routing.dat.txt,NONE,1.1

[Alex S. <ru...@us...>]

Update of /cvsroot/x2serv/x2/doc
In directory usw-pr-cvs1:/tmp/cvs-serv24654/doc

Added Files:
	routing.dat.txt 
Log Message:
Added a txt file explaining the routing.dat format.


--- NEW FILE ---
The routing.dat file is the input file for the VERY powerfull
automated routing control system in X2. In order to work
right though its important to have an understanding of 
the syntax of the file, and its proper use.

Universal ircd has a "no loops" tree type of structure. That is,
no server can link back into the same network twice. Said another
way, theres only one path between any two servers.

Internally, X2 stores the servers as a simple list, containing
the name of a server (S) and its uplink (U). Using this data,
the whole map can be drawn internally.  Think about a /map:

Server.A
|-Server.B
|-Server.C
| |-Server.D
| `-Server.E
`-Server.F

Each server listed has an "uplink", that is, the server that it
connects to (going UP.. other servers may connect to it from below).

So in memory, x2 would know that Server A has no uplink, server B
has server A for an uplink, server D has server C for an uplink, etc:

Server.A --> none
Server.B --> A
Server.C --> A
Server.D --> C
Server.E --> E
Server.F --> A

Now, depending where you are on the network, the map might rotate.. 
above the map is shown from the perspective or "root" of server A.
If you were doing /map from server E, the map would look like this:

Server.E
`-Server.C
  |-Server.D
  `-Server.A
    |-Server.B
    `-Server.F

Note that the two maps shown are EXACTLY the same. Only the perspective
has changed.

Because X2 connects to different servers during its corse of running,
a mechanism has been built in to re-arange the map according to 
wherever X2 is linked currently.  This means that when your
describing a map to X2 in the routing.dat file, it doesnt matter
what you choose as the root, as long as you are consistant.

The Format:

The format of the routing.dat file is as follows:
(<> is a required paramiter, [] is an optional paramiter)

<Server> <port> [uplink] [secondary uplink]

Server - each server on your network should be listed, one per line. The
name must match EXACTLY the name in the M: line of that server (the
same name that shows in /map or /links).

Port - This is the port on which the listed server accepts server
 connections.  When X2 sends out /connect's it will spesify this port. 

Uplink - This is the server which this server should connect to. (as
seen above.. this is only the "up" server)

Secondary - This is another server to try to link to, if the main
uplink is missing from the network.


Note that uplink and secondary uplink are optional fields.
ONLY THE FIRST LINE SHOULD HAVE NO UPLINK SPESIFIED. The 
first server listed is the root (top) of the map. It does
not connect to anything above it.

All the rest of the servers listed should spesify as there uplink
a server which was already listed. This requirement is not the case
for secondary servers, which can list any server as long as it will
eventually be in the file (above OR below the current listed server).

Now for an example:

Please recall the /map we discussed above:

Server.E.yournet.org
`-Server.C.yournet.org
  |-Server.D.yournet.org
  `-Server.A.yournet.org
    |-Server.B.yournet.org
    `-Server.F.yournet.org


The routing.dat syntax for this (ignoring secondary for now) would be:
-----8<------8<------
Server.E.yournet.org 8888
Server.C.yournet.org 8888 Server.E.yournet.org
Server.D.yournet.org 8888 Server.C.yournet.org
Server.A.yournet.org 8888 Server.C.yournet.org
Server.B.yournet.org 8888 Server.A.yournet.org
Server.F.yournet.org 8888 Server.A.yournet.org
---------------------

Note of course that port 8888 would be the name of the port that
your network uses for server connections. (see ircd.conf)

Now a full blow "real" example from Loxxin, including the secondary
part:
------8<------8<-------
agora.loxxin.net 8888
typhoon.loxxin.net 8888 agora.loxxin.net osiris.loxxin.net
osiris.loxxin.net 8888 agora.loxxin.net typhoon.loxxin.net
plasma.loxxin.net 8888 agora.loxxin.net typhoon.loxxin.net
-----------------------

which draws the map:

agora
|-Typhoon
|-Osiris
`-Plasma


if agora were to go down, typehoon would connect to osiris, osiris would 
connect to typhoon, and plasma would connect to typhoon.  

So, there ya go, now you should be able to build a routing.dat file for 
your network.

 -Alex