The Berkeley Service Discovery Service
Configuring and running a SDS server
[Homepage] [System overview] [Clients] [Services] [Servers] [Config options]

Background

This tutorial will give you some basic background about running your own SDS server. You might ask yourself, why would I want to run my own SDS server? Well, in some cases, you might want to run your own production SDS servers to keep track of services in a certain area, such as your own office. However, this doesn't work well yet, since currently SDS servers don't cooperate together to route queries, so your server will be independent. (i.e., after a query misses on the SDS server in your office, it won't be able to find the main departmental SDS server that could have your service.. This will be fixed soon.)

Often, you'll want to run your own SDS server just for testing and development. That's a fine thing to do. It'll give you a chance to create services and run client queries against a server that you can feel free to screw up.

So, what goes into running a SDS server? Mainly, it's just a matter of running the correct iSpace services and getting the configuration options correct. There are a lot of options that affect how the SDS server runs, so you should be aware of them.

What the SDS server does...

Before we get into the options that matter for the SDS server, let's describe at a high level what the SDS server does. If you actually just want to skip all the descriptive information, feel free to skip down to the "Running the SDS server" and "Important parameters" section.

Server Announcements

Probably, the most important function of the SDS server is the sending of SDS server announcements. These announcements are published on the SDS server announcement multicast channel, which is a global, well known address. These announcements will be scoped so that they aren't sent all across the network, but rather, just far enough for the computers the SDS server is servicing to hear them. These announcements are sent by an SDS server in a periodic manner to advertise the existence of the server. All contact information and parameters for that SDS server are contained in the announcement.

The address of this channel is very important, since it is really the first level of indirection for the SDS server. Once this parameter value is agreed upon, all other parameters are obtained through the SDS server announcements that are heard. All clients and services that want to use the SDS server must also know what multicast address it is sending its announcements on. Normally, this would be a fixed address for all production servers, but you could change it so that your own SDS servers and your own clients, services use a different one, so that you are independent of the production SDS servers.

The SDS server announcements are periodic, and the rate is set by the person running the SDS server. You should take care in setting this parameter, since setting it too low will cause a the server to spend a lot of time spending the announcement, yet if it is set too high, it will take longer for clients and services to notice the SDS server has gone down. (If it sends once every 2 hours, then the clients and services won't start to worry until 3-4 announcements have been missed, which would take 6-8 hours.)

Service Announcements

Each SDS server that is running picks a unique multicast address on which to listen for service announcements. This address is passed in the SDS server announcement. Choosing this address is up to the person configuring the SDS server, and should be picked so that it is different than all nearby SDS servers.

Once the services hear obtain this multicast address from the server announcement, they will begin sending their service descriptions on it. They will actually send them encrypted, using the SDS server's encryption key, which was created by the SDS server, and stored in the local CapabilityDistributor. Normally, you don't have to worry about the encryption key, since it's generation is automatic.

The SDS server will receive these service announcements, decrypt them, verify that they are signed properly, and then store them to be used for subsequent client search requests.

The service announcements are also periodic, and the rate at which they should be sent is given in the server announcement, and is set by the person running the SDS server. Again, this rate should not be set too low and not too high. The SDS server will assume a service has died if 3 consecutive service announcements have been missed.

Client requests

Client requests are sent via authenticated RMI, and contain both the client's capabilities along with the specification of the service they are looking for. This functionality is pretty straight forward, and nothing really has to be done to configure it.

CapabilityDistributor

The SDS server actually requires a couple of other services to be run to functional properly. One of those is the ninja.sds.CapabilityDistributor service. It is responsible for tracking which principals are authorized to get which capabilities, and also creating and distributing those capabilities. We should also note that this service keeps track of the encryption key used by the SDS server.

When running this service, you will have to configure which certificate represents the capability signer. This is very similar to who is the certificate authority. The SDS server and the CapabilityDistributor have to agree on who is the proper capability signer, which shouldn't normally be a problem if the configuration is done correctly.

Normally, the ninja.sds.CapabilityDistributor service is run in the same iSpace as the SDS server, but this can be modified through the configuration options.

CertificateRegistry

The ninja.ispace.services.auth.CertificateRegistry is another service that is required to run the SDS server. Typically, you can run this in the same iSpace as the SDS server, but again, you can change this so that you use another CertificateRegistry on another machine.

The CertificateRegistry is used just to distribute certificates, most importantly, the certificates of the SDS server and the services it is keeping track of.

Insecure SDS server

The ninja.sds.SDSinsecureServer is an optional service that can be run in the same iSpace as the regular SDS server. If you want to allow for unauthenticated clients to make queries for unathenticated, unprotected services, that you must run this wrapper service. Unlike the SDS server which can only be contacted via authenticate RMI, the SDSinsecureServer can be contacted using normal RMI, thus decreasing the computation required to interact with the SDS server.

We should also point out that the SDSinsecureServer can only be run in the same iSpace as a real SDS server, since it is just a wrapper service that uses some static references to pass the unauthenticated queries to the underlying SDS server.

Important parameters

Now for the parameters that matter most for the operation of the SDS server. These parameters are also described in the parameters page, but we've pulled out a few of the more important ones and put them here for convenience. The first five options, sds.server.Signer , sds.server.SignerPrivateKey , sds.serverServerCoverage, sds.server.ServiceAnnounceChannel, and sds.server.ServiceAnnouncePort, will have to be set for each new SDS server that is run. The other options have default values that are probably appropriate for most cases.

Option name Description Example values
sds.server.Signer The name of the certicate to be used as the principal running the SDS server. "sds-admin@cs.berkeley.edu."
sds.server.SignerPrivateKey The file name of the private key associated with principal's certificate. /var/home/sds-admin/private-key
sds.server.ServerCoverage A list (comma separated) of network areas to be covered by this SDS server. Each "extent" is described by listing a base IP address and a mask to give which address should be used. 128.32.45.0/255.255.255.0, 128.64.56.0/255.255.255.0
sds.CapabilitySigner The certificate representing the valid capability signer capability@cs.berkeley.edu.
sds.server.ServiceAnnounceChannel The multicast address on which this SDS server will listen for service announcements. 226.125.6.85
sds.server.ServiceAnnouncePort The port on which the SDS server will listen for service announcements. 6778
sds.ServerAnnounceChannel The global multicast channel on which SDS servers will announce their existence. Change this to create independent SDS areas. This parameter is used by both the SDS server and SDS clients, services. 226.125.6.87
sds.ServerAnnouncePort The port on which SDS servers will announce their existence. 6687
sds.server.CertificateAuthority The URL of certificate registry for the SDS server to use. ninjarmi://localhost/ninja.ispace.auth.CertificateRegistry
sds.server.CapabilityDistributor The URL of the capability distributor for the SDS server to use. ninjarmi://localhost/ninja.sds.CapabilityDistributor
sds.server.ServiceAnnounceRate The number of milliseconds between service announcements. Changing this option won't affect services, since services only use the value that's in the SDS server announcement. 20000
sds.server.ServerAnnounceRate The number of milliseconds between server announcements. 60000

Running the SDS server

To run a SDS server, you simply have to make sure you have the above options set correctly in your configuration file (see configuration tutorial), and run the appropriate services in your iSpace. For example, if you are going to be running all your own services, then the following would be the list of services you run:

      ninja.sds.ServiceDiscoveryServer
      ninja.sds.SDSinsecureServer
      ninja.ispace.auth.CertificateRegistry
      ninja.sds.CapabilityDistributor signer-cert-name signer-private-key

Be sure to put in the appropriate names for both the capability signer certificate name, and the file name of the corresponding private key.