An IceBox server internally creates an object called the service manager that is responsible for loading and initializing the configured services. You can optionally expose this object to remote clients, such as the IceBox and IceGrid administrative utilities, so that they can execute certain administrative tasks.
On this page:
IceBox Administrative Slice Interfaces
The Slice definitions shown below comprise the IceBox administrative interface:
ServiceManager interface provides access to the service manager object of an IceBox server. It defines the following operations:
Returns a dictionary of checksums that allows a client to verify that it is using the same Slice definitions as the server.
Starts a pre-configured service that is currently inactive. This operation cannot be used to add new services at run time, nor will it cause an inactive service's implementation to be reloaded. If no matching service is found, the operation raises
NoSuchServiceException. If the service is already active, the operation raises
Stops an active service but does not unload its implementation. The operation raises
NoSuchServiceExceptionif no matching service is found, and
AlreadyStoppedExceptionif the service is stopped at the time
Adds an observer that is called when IceBox services are started or stopped. The service manager ignores operations that supply a null proxy, or a proxy that has already been registered.
Terminates the services and shuts down the IceBox server.
An administrative client that is interested in receiving callbacks when IceBox services are started or stopped must implement the
ServiceObserver interface and register the callback object's proxy with the service manager using its
addObserver operation. The
ServiceObserver interface defines two operations:
Invoked immediately upon registration to supply the current list of active services, and thereafter each time a service is started.
Invoked whenever a service is stopped, and when the IceBox server is shutting down.
The IceBox server unregisters an observer if the invocation of either operation causes an exception.
Our discussion of IceGrid includes an example that demonstrates how to register a
ServiceObserver callback with an IceBox server deployed with IceGrid.
Enabling the Service Manager
IceBox's administrative functionality is disabled by default. You can enable it using the Ice administrative facility by defining endpoints for the
Ice.Admin object adapter with the property
Ice.Admin object adapter is enabled automatically in an IceBox server that is deployed by IceGrid.
With the administrative facility enabled, IceBox registers an administrative facet with the name
IceBox.ServiceManager. We discuss the identity of the
admin object below.
Exposing the service manager makes an IceBox server vulnerable to denial-of-service attacks from malicious clients. Consequently, you should choose the endpoints and transports carefully.
IceBox Admin Facets
When you enable the service manager, IceBox adds it as a facet of the server's
admin object. As a result, the identity of the service manager is the same as that of the
admin object, and the name of its facet is
The identity of the
admin object uses either a UUID or a statically-configured value for its category, and the value
admin for its name. For example, consider the following property definitions:
In this case, the identity of the
admin object is
IceBox also creates in each service communicator (shared communicator and per-service communicator) all the built-in facets enabled on its main communicator, and adds all these facets, except the
Process facet, to its admin object. These facets are named
IceBox.Service.service-name.facet-name, where service-name corresponds to the service name (for example
IceStorm), and facet-name is the name of the built-in facet (for example
You can instruct IceBox to skip the admin facets for a specific service by setting the property
Ice.Admin.Enabled to a numeric value (typically 0) in the configuration for that service.
IceBox Administrative Client Configuration
A client requiring administrative access to the service manager must first obtain (or be able to construct) a proxy for the
admin object. The default identity of the
admin object uses a UUID for its category, which means the client cannot predict the identity and therefore will be unable to construct the proxy itself. If the IceBox server is deployed with IceGrid, the client can use the technique described in our discussion of IceGrid to access its
In the absence of IceGrid, the IceBox server should set the
Ice.Admin.InstanceName property if remote administration is required. In so doing, the identity of the
admin object becomes well-known, and a client can construct the proxy on its own. For example, let's assume that the IceBox server defines the following property:
A client can define the proxy for the
admin object in a configuration property as follows:
The proxy option
-f IceBox.ServiceManager specifies the name of the service manager's administrative facet.
IceBox Administrative Utility
IceBox includes C++ and Java implementations of an administrative utility. The utilities have the same usage:
The C++ utility is named
iceboxadmin. The Java utility is represented by the class
com.zeroc.IceBox.Admin and the Java Compat utility is
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.
stop command stops the requested service but does not cause the IceBox server to unload the service's implementation.
shutdown command stops all active services and shuts down the IceBox server.
The C++ and Java utilities obtain the service manager's proxy from the property
IceBoxAdmin.ServiceManager.Proxy, therefore this proxy must be defined in the program's configuration file or on the command line, and the proxy's contents of depend on the server's configuration. If the IceBox server is deployed with IceGrid, we recommend using the IceGrid administrative utilities instead, which provide equivalent commands for administering an IceBox server. Otherwise, the proxy should have the endpoints and identity configured for the server.