Things you need to know to get RCDS running

Servers:

Servers need to know two things to run, which are passed on the command line.

1. the name of the user file which contains user authorization information and credentials
2. the name of the authority file, which indicates which servers have authority over which domains

These are passed on the command line as follows:

rc_server -af authority_file -uf user_file

There is also a -create command-line flag, which instructs rc_server to create its data files if they do not exist. This should only be used during initial setup, and not when rc_server is started normally.

A production rc_server should normally be started from the system startup files when the host is bootstrapped. For Berkeley-ish systems, it suffices to put code like the following in /etc/rc.local:

if [ -f /rcds/adm/start_rcds ] ; then
        /bin/su rcds -c /rcds/adm/start_rcds && echo -n ' rcds'
fi

where /rcds/adm/start_rcds contains something like:

#!/bin/sh
cd /rcds/adm
./rc_server -af server_authority_file -uf server_user_file &

The authority file is in the following format:

domain:server

where domain is a domain that might appear in a URI, and server is the name of the RCDS server that serves that URI domain. This is so that the RCDS server won't accept updates for URIs for which it's not authoritative, and also so that the RCDS server can return redirects to queries for URIs for which it's not authoritative.

The user file has the following format:

username:user-id:permissions:authtype:secret

where

• username is the name that the client uses to authenticate itself,
• user-id is a unique integer id assigned to that user,
• permissions is a list of capabilities allowed to that user,
• authtype is the authentication type,
• secret contains information that the server needs to verify the client's credentials

The server re-reads its user file and authority file after receiving a SIGHUP signal. Therefore, after editing the user file or authority file, one should do a ``kill -HUP server_pid''.

Clients:

In order to write data to a server, a client must have credentials. The credentials are stored in a file and contain data that the client needs to authenticate itself to the server.

The command-line clients examine the environment variable RC_AUTH_INFO_FILE to learn the name of the file where the credentials are stored.

The client credentials are in the following format:

domain:server:port:username:authtype:secret

Where:

• domain is the domain that appears in a URN, URL, or LIFN.
  
  The client can potentially update information for URIs in any of several different domains. If the environment variable RC_SERVER is not set (more on that below), the client uses the credentials file to determine which server should be contacted for a particular domain.
  
• server is the domain name of the server to contact.
  
• port is the port number on which that server listens. If port 0 is specified, the default RCDS port of 9272 is used.
  
• username is the name that the client uses to authenticate itself to the server. It must match one of the user names in the server's user file. The username does not need to be the same as the username on the local host.
  
• authtype is the type of authentication used to contact the server. Currently the only kind of authentication is ``md5'', which authenticates itself to a server by computing md5(secret+nonce+request), and transmitting only the md5 result, nonce and request to the server. The server performs the same computation to verify that the client is actually in posession of the secret known to the server.
  
• secret is the shared secret used for authentication. This must match the secret used by the server. For the md5 authentication scheme, the secret is really a bit string, but is encoded as several short (4 or fewer letters) words to make it easier to cut-and-paste between systems.
  

Clients that write data to servers will examine the environment variable RC_SERVER. If this variable is set, the client will post all updates to that particular server, and ignore the domains listed in the client credentials file. However, the credentials for the server must still be listed in that file.

NOTE: The domain name specified in the RC_SERVER environment variable must exactly match a domain name listed in the client credentials file. If the RC_SERVER variable uses a different spelling of the domain name, the client code will not be able to find the appropriate credentials to authenticate itself to the server.

Clients that read data from servers will examine the environment variables RC_PROXY and RC_FALLBACK. Under normal circumstances, a client will consult DNS to determine the RCDS server(s) for a particular domain. However, if RC_PROXY is set to the name of a particular server, the client will forward all RCDS queries to the default RCDS port at that server. RC_FALLBACK is similar to RC_PROXY, except that the server named by RC_FALLBACK is only consulted if the initial DNS lookup fails to find a server.