Index servers have the role of indexing all the nodes in an Offset network. Upon request, an Index server can return routes between nodes with a requested amount of credit capacity.
Anyone can run an index server instance. However, index servers are only useful if they share information with each other. We say that the index servers form a federation.
In the current implementation of Offset, every node reports his current status to only one index server. This index server than forwards the information about this node to all the other index servers he knows about.
If you run your own index server but do not register it with other index servers, your index server will only have partial information about the nodes in the network, and therefore your index server will not be useful for finding routes between any pair of nodes.
Index servers only share data if they were configured to do so. For two index servers A and B to share data, the following must hold:
A registered B as a trusted index server
B registered A as a trusted index server
This document describes how to set up an index server on your desktop computer. You can use the same instructions to run your index server in the cloud.
Recommended prior reading:
Running your own index server¶
We begin by presenting all the commands required to configure and run an index server:
# Public facing index server's address INDEX_ADDRESS="www.myindex.com" # Public facing index server's port, used by nodes INDEX_PORT_CLIENT=3456 # Public facing index server's port, used to federate with other index # servers INDEX_PORT_SERVER=6543 # Create a directory for the index server's data mkdir index # Create a directory for trusted index servers. mkdir index/trusted # Create an identity for the index server stmgr gen-ident --output index/index.ident # Generate index ticket to be used by nodes stmgr index-ticket \ --address $INDEX_ADDRESS:$INDEX_PORT_CLIENT \ --idfile index/index.ident \ --output index/index_client.index # Generate index ticket to be used by other index servers stmgr index-ticket \ --address $INDEX_ADDRESS:$INDEX_PORT_SERVER \ --idfile index/index.ident \ --output index/index_server.index # Register other trusted index servers # Note that those servers also have to register # our index server tickets as # trusted cp other_index1.index index/trusted/ cp other_index2.index index/trusted/ # Start index server stindex --idfile index/index.ident \ --lclient $INDEX_ADDRESS:$INDEX_PORT_CLIENT \ --lserver $INDEX_ADDRESS:$INDEX_PORT_SERVER \ --trusted index/trusted &
To be able to federate with another index server, you and the other index
server’s operator should exchange index servers tickets. Your ticket is found
Assuming that you received the file
other_index1.index from the other index
server operator, you should copy this file to your
It is crucial that both you and the other index server operator add each
other’s ticket to the
To configure nodes to use your index server, provide them with index server
ticket for node clients:
index/index_client.index. This file can also be
added using the Offset app.
Index commands explained¶
Selecting public listening address and ports:
INDEX_ADDRESS="www.myindex.com" INDEX_PORT_CLIENT=3456 INDEX_PORT_SERVER=6543
INDEX_ADDRESS is the index server’s public address. You may use either IP
address or a domain name. If you choose to use a domain name, note that you do
not need to register a certificate, as Offset has its own authentication
INDEX_PORT_CLIENT is the index’s public listening port for clients. In
other words, nodes will connect to
INDEX_ADDRESS:INDEX_PORT_CLIENT. You can
pick any port number that you want that is at least 1024 1.
INDEX_PORT_SERVER is the index’s publick listening port for servers. This
means other index servers federating with this index server will connect to
Next, we create directories to store the data required for the index server. We
also create a subdirectory called
trusted to keep a list of trusted index
servers that this index server will federate with:
mkdir index mkdir index/trusted
We generate a identity for the index server:
stmgr gen-ident --output index/index.ident
An identity is a key pair: A private key and a public key. The identity is used for authentication during communication with other nodes and other index servers.
We then create two tickets for this index server. A ticket contains the index’s public address and public key. The first ticket will be used by nodes to connect to this index server:
stmgr index-ticket \ --address $INDEX_ADDRESS:$INDEX_PORT_CLIENT \ --idfile index/index.ident \ --output index/index_client.index
The second ticket will be used by other index servers to connect to this index server:
stmgr index-ticket \ --address $INDEX_ADDRESS:$INDEX_PORT_SERVER \ --idfile index/index.ident \ --output index/index_server.index
The next step is to set up trusted index servers for this index server. In the snippet below, we add two index servers tickets to our trusted directory:
cp other_index1.index index/trusted/ cp other_index2.index index/trusted/
To make federation work, we also have to provide our index server’s ticket to the owners of those index servers. Federation between index servers only works if both index servers configured it.
Finally, we start the index server:
stindex --idfile index/index.ident \ --lclient $INDEX_ADDRESS:$INDEX_PORT_CLIENT \ --lserver $INDEX_ADDRESS:$INDEX_PORT_SERVER \ --trusted index/trusted &
The & sign at the end of the command means that the command will run at the background. If this is not what you want, you may omit the sign.
In most operating systems, ports below 1024 are usually reserved, and require administrator priviledges to use.