44.3 The Service Manager

In addition to the objects supported by application services, an IceBox server supports an administrative object that implements the IceBox::ServiceManager interface (see the online Slice API Reference). This object is responsible for loading and initializing the services, as well as performing administrative actions requested by clients. An object adapter is created for this object so that its endpoint(s) can be secured against unauthorized access.

The ServiceManager interface is shown below:

module IceBox {
exception AlreadyStartedException {};
exception AlreadyStoppedException {};
exception NoSuchServiceException {};

interface ServiceManager {
    Ice::SliceChecksumDict getSliceChecksums();
    void startService(string service)
        throws AlreadyStartedException, NoSuchServiceException;
    void stopService(string service)
        throws AlreadyStoppedException, NoSuchServiceException;
    void shutdown();
};
};

The getSliceChecksums operation returns Slice checksums of the IceBox definitions (see Section 4.20 for more information). The startService and stopService operations control the lifetime of configured services. The shutdown operation terminates the services and shuts down the IceBox server. Additional administrative features may be added in a future release.

44.3.1 Endpoint Configuration

The endpoints for the service manager’s object adapter are defined using the IceBox.ServiceManager.Endpoints configuration property:

IceBox.ServiceManager.Endpoints=tcp ‑p 10000

Since a malicious client could make a denial-of-service attack against the service manager, it is advisable to use SSL endpoints (see Chapter 42), or to secure these endpoints with the proper firewall configuration, or both.

44.3.2 Client Configuration

A client requiring administrative access to the service manager can create a proxy using the endpoints defined by the property described in Section 44.3.1. The default identity of the service manager object is IceBox/ServiceManager, but this can be changed using the IceBox.InstanceName property (see Section 44.3.4). Therefore, a proxy using the default identity and the endpoint from Section 44.3.1 would be constructed as follows:

ServiceManager.Proxy=IceBox/ServiceManager:tcp ‑p 10000

44.3.3 Administrative Utility

IceBox includes C++ and Java implementations of an administrative utility. The utilities have the same usage:

Usage: iceboxadmin [options] [command...]
Options:
‑h, ‑‑help           Show this message.
‑v, ‑‑version        Display the Ice version.

Commands:
start SERVICE        Start a service.
stop SERVICE         Stop a service.
shutdown             Shutdown the server.

The C++ utility is named iceboxadmin, while the Java utility is represented by the class IceBox.Admin.

The start command is equivalent to invoking startService on the service manager interface. Its purpose is to start a pre-configured service; it cannot be used to add new services at run time. Note that this command does not cause the service’s implementation to be reloaded.

Similarly, the stop command stops the requested service but does not cause the IceBox server to unload the service’s implementation.

The shutdown command stops all active services and shuts down the IceBox server.

The C++ and Java utilities compose the service manager’s proxy in the same way:

1. Obtain the identity from the property IceBox.InstanceName (see Section 44.3.4).

2. If the Ice.Default.Locator property is defined (see Section 39.4.3), the identity is combined with the value of the property
IceBox.ServiceManager.AdapterId.

3. If Ice.Default.Locator is not defined, the identity is combined with the endpoints supplied by the property
IceBox.ServiceManager.Endpoints (see Section 44.3.1).

Typically, the utility is started using the same configuration file as the IceBox server (see Section 44.5), but that is not mandatory.

44.3.4 Object Identities

An IceBox service hosts one well-known object, which implements the IceBox::ServiceManager interface and has the default identity IceBox/ServiceManager. If an application requires the use of multiple IceBox services, it is a good idea to assign unique identities to the well-known objects by configuring the servers with different values for the IceBox.InstanceName property, as shown in the following example:

IceBox.InstanceName=IceBox1

This property changes the category of the object’s identity, which becomes IceBox1/ServiceManager. The client’s configuration must also be changed to reflect the new identity:

ServiceManager.Proxy=IceBox1/ServiceManager:tcp ‑p 10000