Welcome

Navigation: »No topics above this level«

Welcome

 Print this Topic Return to chapter overview

Welcome to the IceGrid Admin Online Help

IceGrid Admin is the graphical administration tool for [image] IceGrid, the server-deployment and monitoring service for Ice.

These pages describe how to use the IceGrid Admin tool, and assume some familiarity with both Ice and IceGrid.

Getting Started with Ice and IceGrid

Ice and IceGrid are described in detail in the [image] Ice manual.

For a quick overview of IceGrid, please read [image] "Teach Yourself IceGrid in 10 Minutes" in issue 19 of the [image] Connections newsletter.

Need Help?

If you have trouble with IceGrid Admin or any other Ice component, we recommend to browse the [image] Ice user forums and post your questions there.

ZeroC also offers commercial support by e-mail and by phone. Please contact sales@zeroc.com for details.


Introduction

Navigation: »No topics above this level«

Introduction

 Print this Topic Return to chapter overview

Everything you need to deploy IceGrid applications

IceGrid Admin is a comprehensive administration tool for IceGrid. With IceGrid Admin, you can:

· Manage a live IceGrid deployment: browse the nodes and servers in your deployment, view status information, start/stop these processes, and much more.
· Create all the definitions necessary to deploy an IceGrid application. You can start from scratch or retrieve existing definitions directly from a live IceGrid deployment or from an IceGrid XML file.

Other Tools

Although all IceGrid features are available through IceGrid Admin, it is not the only way to interact with an IceGrid deployment. Sometimes, it can be more convenient to use icegridadmin, a simple command-line tool. icegridadmin provides most IceGrid Admin features, in particular, you can use icegridadmin to add or update application definitions (described using IceGrid XML files) to an IceGrid registry.

If you are writing Python or Ruby scripts, another option is to use directly the IceGrid API, and make remote Ice invocations using Ice-for-Python or Ice-for-Ruby.


System Requirements

Navigation: Introduction >

System Requirements

 Print this Topic Return to chapter overview

IceGrid Admin is a JavaTM application supported a wide range of platforms including Windows XP, MacOS X and Linux.

In order to run IceGrid Admin you need:

· the IceGridGUI.jar file, usually installed in the bin or lib directory of your Ice installation. If you are using a Linux RPM installation, IceGridGUI.jar is installed in /usr/share/java/Ice-3.3.1.
· a Java Runtime Environment (JRE) v1.5.0 or later. For Windows, Linux and Solaris, we recommend using a Sun JRE or JDK, available [image] here.

If you want to read IceGrid XML files from IceGrid Admin, you also need to have the icegridadmin command-line utility (version 3.3.1) in your PATH.


Starting IceGrid Admin

Navigation: Introduction >

Starting IceGrid Admin

 Print this Topic Return to chapter overview

In some environments, IceGrid Admin can be started by simply double-clicking on the IceGridGUI.jar file.

On all platforms, you can start IceGrid Admin from a terminal by typing:

java -jar path-to-IceGridGUI.jar

For example on Solaris, HP-UX or Mac OS X:

$ java -jar /opt/Ice-3.3.1/lib/IceGridGUI.jar

On Linux with a RPM installation, you can also use the icegridgui script installer in /usr/bin:

$ icegridgui


Command-Line Arguments

Navigation: Introduction >

Command-Line Arguments

 Print this Topic Return to chapter overview

IceGrid Admin can be configured using Ice properties, and like with most Ice applications, these properties can be set using command-line arguments or a configuration file (or both).

Since IceGrid Admin is an Ice application (a client to the IceGrid registry), setting regular Ice properties can be useful as well. For example, you can set the Ice.Trace.Network property to get detailed information about network communications sent to stderr.

$ icegridgui --Ice.Trace.Network=2

Ice properties are described in detail in the [image] Ice manual.

The following table shows properties specific to IceGrid Admin itself:

Name | Description
IceGridAdmin.AuthenticateUsingSSL | By default, when logging into an IceGrid registry, IceGrid Admin offers you to use username/password for user authentication. Setting this property to a value > 0 instructs IceGrid Admin to offer SSL authentication by default. See Login for details.
IceGridAdmin.Username | The default username when authenticating with a username/password. See Login for details.
IceGridAdmin.Password | The default password when authenticating with a username/password . See Login for details.
IceGridAdmin.Trace.Observers | When set to a value > 0, IceGrid Admin writes a log message (to stderr) each time it receives information from the IceGrid registry. This is typically used to debug problems in IceGrid Admin.
IceGridAdmin.Trace.SaveToRegistry | When set to a value > 0, IceGrid Admin logs information (to stderr) about all save activities directed to the IceGrid registry. This is typically used to debug problems in IceGrid Admin.

If you need to set many properties, it is a good idea to write a configuration file and use the --Ice.Config command-line argument to specify the location of this file. For example:

> java -jar C:\Ice-3.3.1\bin\IceGridGUI.jar --Ice.Config=icegridadmin.conf


Main Window

Navigation: »No topics above this level«

Main Window

 Print this Topic Return to chapter overview

The main IceGrid Admin window allows to navigate between your live deployment and the definitions of several applications.

Tabs

The main IceGrid Admin window shows one or more tabs:

· The Live Deployment tab ( [image] ) displays information about an IceGrid deployment you have logged into. There is always one and only one Live Deployment tab. When you are not connected to an IceGrid deployment, the corresponding pane is empty.
· A Live Application tab ( [image] ) displays application definitions retrieved from the IceGrid registry you are connected to. As long as you do not change anything in the associated pane, IceGrid Admin will keep the information up-to-date. For example if another administrator adds a new server definition in this application definition, it will appear automatically and immediately in this pane.
· A File-Based Application tab ( [image] ) displays application definitions retrieved from an IceGrid XML file.
· An icon-less tab displays the definitions of an application that is not bound to an IceGrid registry or to a file, such as a brand new application. A live application with unsaved modifications also becomes icon-less if the connection to its IceGrid registry is lost.

IceGrid Admin may show any number of application tabs, including none at all.

Status Bar

The status bar at the bottom of the main window shows information about operations performed by IceGrid Admin, or messages received from the IceGrid registry.


Live Deployment

Navigation: »No topics above this level«

Live Deployment

 Print this Topic Return to chapter overview

The Live Deployment pane shows the runtime status and configuration of an existing IceGrid deployment, and allows you to perform various administrative tasks on this deployment, such as:

· start or stop a server
· enable or disable a server
· send signal to a server
· retrieve the log files of a server
· patch an entire application
· register a new "well-known" object with the IceGrid registry
· undeploy a deployed application


Login

Navigation: Live Deployment >

Login

 Print this Topic Return to chapter overview

The Login dialog allows you to connect to an IceGrid registry and retrieve information about the nodes and servers associated with this registry. Use File > Login... or press the [image] button to open the Login dialog:

Direct Connection

Select the Direct tab to connect directly to the IceGrid registry, that is, without going through an intermediary Glacier2 router. This is the most common type of login.

An IceGrid registry can support two forms of authentication:

Username and Password

The IceGrid registry authenticates IceGrid Admin using the provided username and password.

SSL Authentication

When you check Use SSL for authentication, the IceGrid registry uses SSL credentials to authenticate IceGrid Admin. The username and password are not used for this form of login.

The other fields in the Direct panel are:

Enable IceSSL

When checked, IceGrid Admin loads the IceSSL plugin. You need to load the IceSSL plugin in order to use "ssl" endpoints.

IceGrid Instance Name

The name of your IceGrid instance. This corresponds to the value of the IceGrid.InstanceName property of your IceGrid registry.

IceGrid Registry Endpoint(s)

The client endpoint(s) of your IceGrid registry, or registries if your deployment has several registry replicas. This corresponds to the value of the IceGrid.Registry.Client.Endpoints property (or IceGrid.Registry.Client.PublishedEndpoints, if set) of your IceGrid registry (or registries).

Connect to Master Registry

If you have a non-replicated IceGrid registry, checking or unchecking this box makes no difference.

When you have several IceGrid registry replicas, you may want to connect to a specific registry replica or to the Master registry. If you want to connect to a specific replica, enter the endpoint(s) of this specific replica in the IceGrid Registry Endpoint(s) field and leave this box unchecked. If you want to connect to the Master registry, enter the endpoint(s) of any replica in the IceGrid Registry Endpoint(s) field and check this box. Note that you can only update application definitions when you are connected to the Master registry.

Routed Connection

Select the Routed tab to connect to an IceGrid registry through a Glacier2 router. The fields are similar to the fields in the Direct tab, but an important difference: the target is a Glacier2 router, not an IceGrid registry.

A Glacier2 router can support two forms of authentication:

Username and Password

The router authenticates IceGrid Admin using the provided username and password.

SSL Authentication

When you check Use SSL for authentication, the router uses SSL credentials to authenticate IceGrid Admin. The username and password are not used for this form of login.

The other fields in the Routed panel are:

Enable IceSSL

When checked, IceGrid Admin loads the IceSSL plugin. You need to load the IceSSL plugin in order to use ssl endpoints.

Glacier2 Instance Name

The name of your Glacier2 instance. This corresponds to the value of the Glacier2.InstanceName property of your Glacier2 router.

Glacier2 Router Endpoint(s)

The client endpoint(s) of your router. This corresponds to the value of the Glacier2.Client.Endpoints property (or Glacier2.Client.PublishedEndpoints, if set) of your Glacier2 router.

A Glacier2 router can only give access to a specific IceGrid registry instance, even when this instance is part of set of replicated IceGrid registries. As a result, there is nothing equivalent to the Connect to Master Registry check-box in the Routed pane.


SSL Configuration

Navigation: Live Deployment > Login >

SSL Configuration

 Print this Topic Return to chapter overview

When you check Enable IceSSL in the Direct or Routed pane of the Login dialog, you need to configure the Ice-for-Java IceSSL plugin.

Basic SSL Configuration

The Basic pane shows the mininum configuration required by IceSSL: the location of a Java Keystore file, and a password to unlock the keys in this keystore. This corresponds to the IceSSL.Keystore and IceSSL.Password properties.

Advanced SSL Configuration

The Advanced SSL configuration pane allows you to specify a few more properties:

Keystore Integrity Password

An optional password used to check the integrity of the Keystore file. This corresponds to the IceSSL.KeystorePassword property.

Alias

Selects a particular certificate from the keystore file. This corresponds to the IceSSL.Alias property.

Truststore File

Specifies a keystore file that contains the certificates of trusted certificate authorities. This corresponds to the IceSSL.Truststore property.

Truststore Integrity Password

An optional password used to check the integrity of the truststore file. This corresponds to the IceSSL.TruststorePassword property.

Even more IceSSL Configuration

You can provide additional IceSSL configuration by passing command-line arguments to IceGrid Admin. See Command-Line Arguments for details.


Logout

Navigation: Live Deployment >

Logout

 Print this Topic Return to chapter overview

Use File > Logout or press the [image] button to disconnect from an IceGrid registry. This clears all information in the Live Deployment pane.


Runtime Components

Navigation: Live Deployment >

Runtime Components

 Print this Topic Return to chapter overview

IceGrid Admin shows the following runtime components:

· Registry ( [image] )
Represents the IceGrid registry process with which IceGrid Admin communicates
· Slave Registry ( [image] )
Represents a slave registry process, when you have several replicated IceGrid registries
· Node ( [image] )
Represents an IceGrid node process
· Regular Server ( [image] )
Represents a regular server process, started and monitored by an IceGrid node
· IceBox Server ( [image] )
Represents an IceBox server process, started and monitored by an IceGrid node
· Adapter ( [image] )
Represents an Ice indirect object adapter, deployed within a server or a service.
· Database Environment ( [image] )
Represents a Freeze/Berkeley DB Database Environment, deployed within a server or a service.
· IceBox Service ( [image] )
Represents an IceBox service, deployed on an IceBox server.

All actions on these components (through menus, buttons and keyboard short-cuts) affect directly and immediately the running IceGrid deployment.


Registry

Navigation: Live Deployment > Runtime Components >

Registry

 Print this Topic Return to chapter overview

The registry is the root node of the Runtime Components tree, and represents the IceGrid registry process administered by IceGrid Admin.

Actions

A registry provides the following actions, from its contextual menu and from the Tools > Registry menu:

Add Well-Known Object

Create a new dynamic well-known object in the IceGrid registry.

Retrieve stdout

Retrieve the stdout log file of the IceGrid registry into a Log File Dialog. This retrieval succeeds only when the registry stdout output has been redirected to a file using the Ice.StdOut property.

Retrieve stderr

Retrieve the stderr log file of the IceGrid registry into a Log File Dialog. This retrieval succeeds only when the registry stderr output has been redirected to a file using the Ice.StdErr property.

Shutdown

Shutdown the registry process.

You cannot restart an IceGrid registry from IceGrid Admin.

Properties

The Registry Properties panel shows:

Hostname

The name of the host on which the IceGrid registry process is running.

Deployed Applications

This table shows all the applications deployed on this IceGrid registry, along with the date and time of the last update of each application. A contextual menu allows you to:

· open the corresponding application descriptor
· patch the application, that is, instruct the IceGrid nodes to download the latest version of this application's files
· show additional details on this application in this registry
· remove (undeploy) the application from the registry

Dynamic Well-Known Objects

This table shows the well-known objects registry dynamically with the IceGrid registry: well-known objects defined using adapter and replica-group definitions are not included. A contextual menu allows you to add or remove entries from this table, and to show a given entry in its own dialog.

Dynamic Objects Adapters

This table shows the object adapters registered dynamically with the registry. It is typically empty. A registry allows dynamically registered adapters only when its IceGrid.Registry.DynamicRegistration property is set to a value greater than 0. A contextual menu allows you to remove entries from this table.

Children

A registry node can have two types of children:

· Slave Registry
· Node


Slave Registry

Navigation: Live Deployment > Runtime Components >

Slave Registry

 Print this Topic Return to chapter overview

An IceGrid deployment may use several IceGrid registry replicas, with one Master registry and a number of read-only Slave registries.

Actions

A slave registry provides the following actions, from its contextual menu and from the Tools > Registry menu:

Retrieve stdout

Retrieve the stdout log file of the IceGrid registry into a Log File Dialog. This retrieval succeeds only when this registry stdout output has been redirected to a file using the Ice.StdOut property.

Retrieve stderr

Retrieve the stderr log file of the IceGrid registry into a Log File Dialog. This retrieval succeeds only when this registry stderr output has been redirected to a file using the Ice.StdErr property.

Shutdown

Shutdown this registry process.

You cannot restart an IceGrid registry from IceGrid Admin.

Properties

The Registry Properties panel shows:

Hostname

The name of the host on which the IceGrid registry process is running.


Node

Navigation: Live Deployment > Runtime Components >

Node

 Print this Topic Return to chapter overview

A node represents an IceGrid node process registered with the IceGrid registry.

States

A node can be either up ( [image] ) or down ( [image] ). A "down" node is shown only when it is described by an application deployed on this IceGrid registry.

Actions

A node provides the following actions, from its contextual menu and from the Tools > Node menu:

Retrieve stdout

Retrieve the stdout log file of the IceGrid node into a Log File Dialog. This retrieval succeeds only when the node stdout output has been redirected to a file using the Ice.StdOut property.

Retrieve stderr

Retrieve the stderr log file of the IceGrid node into a Log File Dialog. This retrieval succeeds only when the node stderr output has been redirected to a file using the Ice.StdErr property.

Shutdown

Shutdown the IceGrid node process.

You cannot restart an IceGrid node from IceGrid Admin.

Properties

The Node Properties panel shows:

Hostname

The name of the host on which the IceGrid node process is running.

Operating System

The operating system name and version of the host on which the IceGrid node process is running.

Machine Type

The type of CPUs and the number of CPUs of the host on which the IceGrid node process is running.

CPU Usage (Windows) or Load Average (Linux/Unix)

On Windows, shows the percentage of CPU utilization in the past 1, 5, and 15 minutes. On Linux/Unix, shows the load-average in the past 1, 5 and 15 minutes. These values are retrieved when the Node Properties panel is displayed. Click on the Refresh button to retrieve the latest values.

Load Factor

Shows the load factor defined by each application using this node.

Children

A registry node can only have two types of children:

· Regular Server
· IceBox Server


Server

Navigation: Live Deployment > Runtime Components >

Server

 Print this Topic Return to chapter overview

A server represents an Ice server process. It can be either regular server (with typically a single Ice communicator) or an IceBox server hosting a number of IceBox services.

States

A server is always in one of the following states (the first icon is for regular servers, the second for IceBox servers):

· Unknown ( [image], [image]): this state is shown when the parent IceGrid node is down.
· Inactive ( [image] , [image] ): the server is not running.
· Activating ( [image] , [image] ): the server is starting up. The IceGrid registry is waiting for the server to register all its object adapters with server lifetime.
· Active ( [image] , [image] ): the server is running, and has registered all its object adapters with server lifetime with the IceGrid registry.
· Deactivating ( [image] , [image] ): the server is shutting down. The IceGrid registry is waiting for the server process to exit.
· Destroyed ( [image] , [image] ): the server being removed of the IceGrid registry. This is a very transient state.

A server can also be either enabled or disabled; when disabled, the icons above are grayed-out. A disabled server cannot be started until it is re-enabled.

Actions

A server provides the following actions, from its contextual menu, from the Tools > Server menu, and from buttons on the Server Properties panel:

Start

Instruct the IceGrid node to start the server.

Stop

Instruct the IceGrid node to shutdown the server.

Enable

Mark the server as "enabled".

Disable

Mark the server as "disabled". A disabled server cannot be started; however an already running server can be marked "disabled".

Patch Distribution

Patch the server's distribution, that is, instruct the IceGrid node to download the latest files from the server's distribution.

Write Message

Open a dialog that allows you to write a message to the server's stdout or stderr.

Retrieve stdout

Retrieve the stdout log file of this server into a Log File Dialog. This retrieval succeeds only when the server's stdout output has been redirected to a file using the Ice.StdOut property. This is usually achieved by setting the IceGrid.Node.Output property in the IceGrid node configuration file.

Retrieve stderr

Retrieve the stderr log file of this server into a Log File Dialog. This retrieval succeeds only when the server's stderr output has been redirected to a file using the Ice.StdErr property. This is usually achieved by setting the IceGrid.Node.Output property in the IceGrid node configuration file.

Retrieve Log

Retrieve a log file of this server into a Log File Dialog.

Send Signal

Send a signal to a server, for example SIGQUIT. Available only for non-Windows servers.

Properties

The Server Properties panel shows first the Runtime Status of the server, i.e. "live" values retrieved from the server:

State

The state of the server (Active, Deactivating, Inactive etc., see above)

Enabled

A checkbox that is checked when the server is enabled.

Process Id

The process ID of the server.

Build Id

The build Id of this server: this corresponds to the Ice property BuildId.

Properties

A table showing all the Ice properties currently set in this server. These properties are retrieved each time you select a new server in IceGrid Admin, and each time you click on the Refresh button next to the Build Id field.

The remaining Server Properties come from the IceGrid descriptors associated with this server:

Application

The name of the application containing this server's definition. The button on the right shows the server definition in an Application tab.

Description

A free-text description of this server.

Properties

A table showing all the Ice properties of this server. These properties may come from template definitions, property sets, server-instance properties etc. They are all combined in this table.

Path to Executable

The path to the server's executable, used by the IceGrid node to start the server.

Ice Version

The Ice version of this server.

Working Directory

The path to the server's working directory used by the IceGrid node when starting the server.

Command Arguments

The command-line arguments given to the server when started by IceGrid.

Run as

On Linux/Unix, a server may be started as a specific user when IceGrid node runs as root. Run as shows this username. When blank, the server runs as the IceGrid node user except if IceGrid node runs as root (on Linux/Unix); in this case, the server runs as nobody.

Environment Variables

A server started by IceGrid node gets these environment variables in addition to the environment variables inherited from the IceGrid node.

Activation Mode

The server's activation mode.

Activation Timeout

The server's activation timeout.

Deactivation Timeout

The server's deactivation timeout.

Allocatable

This checkbox Shows whether this server is allocatable or not.

Depends on the application distribution

If this checkbox is checked, this server depends on the enclosing application's distribution: each time this distribution is patched, the server is automatically shut down before the patch.

IcePatch2 Proxy

A stringified (or well-known) proxy for the IcePatch2 server than contains this server's distribution. When blank, this server does not have its own distribution.

Directories

List of directories included in the server distribution. When blank, the entire IcePatch2 server repository is used as the server distribution.

Children

A regular server node can have two types of children:

· Adapter
· Database Environment

An IceBox server node can have only one type of children:

· Service


Adapter

Navigation: Live Deployment > Runtime Components >

Adapter

 Print this Topic Return to chapter overview

An adapter represents an Ice object adapter described in the IceGrid registry that resides in a server or an IceBox service. Note that direct object adapters are not displayed since IceGrid knows nothing about them.

States

An adapter can be either active ( [image]) or inactive ( [image]).

Properties

The Adapter Properties panel shows:

Status

The status of this object adapter: Active or Inactive.

Published Endpoints

The endpoints that this object adapter has registered with the IceGrid registry. Blank when the adapter's status is Inactive.

Description

A free-text description of this adapter.

Adapter ID

This object adapter's ID. Adapter IDs are unique within an IceGrid deployment.

Replica Group

When this adapter belongs to a replica group, shows the replica group ID. Blank otherwise.

Priority

The adapter's priority. Used only when the adapter belongs to a replica group with the "Ordered" load balancing policy.

Endpoints

The Endpoints configuration property of this object adapter.

Published Endpoints

The PublishedEndpoints configuration property of this object adapter.

Register Process

When the Register Process checkbox is checked, this object adapter will register an Ice::Process object with IceGrid upon activation. This setting is meaningful only for servers with an Ice version less than 3.3.

Server Lifetime

When the Server Lifetime checkbox is checked, IceGrid considers that this object adapter is activated when the server starts up and deactivated when the server shuts down. This allows IceGrid to detect when a server is fully activated (all its object adapters with a server-lifetime have registered) and when a server is shutting down (at least one object adapter with server-lifetime has unregistered).

Well-known Objects

The well-known objects defined by this object adapter.

Allocatable Objects

The well-known objects defined by this object adapter.


Database Environment

Navigation: Live Deployment > Runtime Components >

Database Environment

 Print this Topic Return to chapter overview

A Database Environment represents a Berkeley DB database environment, typically used for storage by the Freeze persistence service.

Properties

The Database Environment Properties panel shows:

Description

A free-text description of this Berkeley DB database environment.

DB Home

The path to the home directory of this database environment. Corresponds to the Ice property Freeze.DbEnv.env-name.DbHome. It is often created by the IceGrid node in the server's private directory.

Properties

Berkeley DB configuration properties for this database environment. IceGrid generates a DB_CONFIG file in the DB Home directory with these properties.


Service

Navigation: Live Deployment > Runtime Components >

Service

 Print this Topic Return to chapter overview

A service represents an IceBox service loaded (or potentially loaded) within an IceBox server.

States

A service can be either started ( [image] ) or stopped ( [image] ) within an IceBox server.

Actions

A service provides the following actions, from its contextual menu, from the Tools > Service menu, and from buttons on the Service Properties panel:

Start

Instruct the IceBox server to start the service.

Stop

Instruct the IceBox server to stop this service.

Retrieve Log

Retrieve a log file of this service into a Log File Dialog.

Properties

The Service Properties panel shows first the Runtime Status of the service, i.e. "live" values retrieved from the service:

State

A checkbox that is checked when the service is started.

Build Id

The build Id of this service: this corresponds to the Ice property BuildId.

Properties

A table showing all the Ice properties currently set in this service. These properties are retrieved each time you select a new service in IceGrid Admin, and each time you click on the Refresh button next to the Build Id field.

The remaining Server Properties come from the IceGrid descriptors associated with this server:

Description

A free-text description of this service.

Properties

A table showing all the Ice properties of this service. These properties may come from template definitions, property sets, service-instance properties etc. They are all combined in this table.

Entry Point

The entry point for this service. This corresponds to the value of the IceBox.Service.service-name property.


Log File Dialog

Navigation: Live Deployment >

Log File Dialog

 Print this Topic Return to chapter overview

The Log File dialog shows a log file (text file) retrieved through IceGrid. Often, a process will be writing to this log file and the dialog will periodically check for new lines to display.

States

A log file dialog is always in one of the following states:

· Running
The dialog is periodically checking for new lines.
· Paused
The dialog is "connected" to a remote log file but does not currently retrieve new lines.
· Stopped
The dialog is not retrieving new lines from the remote log file.

Preferences

Use the Edit > Preferences... menu to open the Preferences dialog. These preferences apply to the current dialog and to any Log File dialog opened later on.

Max lines in buffer

The maximum number of lines displayed in the log dialog.

Max characters in buffer

The maximum number of characters displayed in the log dialog.

Initial tail

When a new dialog is opened, or when restarting a stopped dialog, the dialog retrieves and displays Initial tail lines.

Max bytes read per request

The maximum number of bytes retrieve by each request. Pick a value that is low enough to make the dialog appear responsive and big enough to avoid many round-trips when lots of data are logged. IceGrid Admin requires a value between 100 and Ice.MessageSizeMax - 512.

Poll period

When in the running state, the dialog attempts to retrieve new lines from the log file (through IceGrid) every Poll period seconds.


Application

Navigation: »No topics above this level«

Application

 Print this Topic Return to chapter overview

IceGrid definitions are organized in "applications", with typically one or a few applications deployed on a given IceGrid instance.

An Application pane allows you to:

· create a new application: describe servers, IceBox services, the nodes you want to run them, specify load-balancing policies, etc.
· browse and edit the definition of an existing, live application deployed in an IceGrid instance
· browse and edit the definition of an application stored in an IceGrid XML file


Editing & Saving

Navigation: Application >

Editing & Saving

 Print this Topic Return to chapter overview

Editing

As soon as you make any update in a form, IceGrid Admin enables two buttons at the bottom of this form: Apply and Discard.

If you navigate to another node without pressing Apply or Discard, the default is Apply: your changes are applied to the in-memory representation of the application definition. However these changes are not stored to the IceGrid registry or XML file until you save the application definition (see below).

Editing a live application ( [image] ) also disconnects this application from the IceGrid registry: updates made by other users are no longer propagated to the Application tab.

Error Checking

IceGrid Admin performs very little error checking while you are working on an application definition. For example, you may temporarily keep several servers with the same ID, leave some parameters of a template instance unset, or use an undefined variable. All such errors are only detected when you save your application to an IceGrid registry.

There are nonetheless two types of constraints enforced by IceGrid Admin at all times:

· two descriptor nodes in an application pane display cannot have the same name
· some fields (such as Path to Executable for a server) cannot be empty.

If you violate such a constraint, IceGrid Admin prevents you from applying your change.

Saving

You save an application definition to an IceGrid registry or an XML file with the menu item File > Save, File > Save to File or File > Save to Registry, or with the corresponding toolbar button.

Save saves a live application to the IceGrid registry, and a file-bound application to its associated XML file.

Discarding Updates

You may discard all your updates by selecting File > Discard Updates or pressing the corresponding toolbar button. Discard Updates simply reloads the application from the IceGrid registry or its associated XML file.

Concurrent Updates to the same IceGrid Registry

If several administrators update the same application definition concurrently, the last save will silently overwrite previous (concurrent) updates.

To avoid this situation, you can acquire an exclusive write access to the IceGrid registry with File > Acquire Exclusive Write Access. After this exclusive write access is granted, any attempt by another session to save to the IceGrid registry will result in an error:


Copy & Paste

Navigation: Application > Editing & Saving >

Copy & Paste

 Print this Topic Return to chapter overview

Most descriptor sub-trees can be copied and later pasted. Copies are always deep-copies: for example if you copy a node, all the servers on this code are copied, including all the the sub-elements of these servers (object adapters, database environment, services, etc.).

After pasting a sub-tree, you typically need to check and edit the new elements to avoid any duplicate server IDs, adapter IDs etc.


Navigation

Navigation: Application >

Navigation

 Print this Topic Return to chapter overview

Each Application pane maintains a history of the nodes you have visited in this pane. You can navigate these nodes using the View > Go Back to the Previous Node and View > Go to the Next Node menu items, or with the equivalent toolbar buttons:

Also on some forms a green arrow button provides a link to another node (typically a template) in the same Application pane:


Variables

Navigation: Application >

Variables

 Print this Topic Return to chapter overview

Variables allow you to define commonly-used information once and refer to them symbolically throughout your application descriptors.

Syntax

Substitution for a variable or parameter VP is attempted whenever the symbol ${VP} is encountered, subject to the limitations and rules described below. Substitution is case-sensitive, and a fatal error occurs if VP is not defined when the application is saved to an IceGrid registry.

Where are Variables Allowed?

Substitution is performed in all string fields except the following:

· server and service template IDs (when defining a template or when referring to a template)
· variable names
· template parameter names
· node names
· application names

Escaping a Variable

You can prevent substitution by escaping a variable reference with an additional leading $ character. For example, in order to assign the literal string ${abc} to a variable, you would use $${abc} as this variable's value.

The extra $ symbol is only meaningful when immediately preceding a variable reference, therefore text such as US$$55 is not modified. Each occurrence of the characters $$ preceding a variable reference is replaced with a single $ character, and that character does not initiate a variable reference.

Pre-Defined Variables

IceGrid defines a set of read-only variables to hold information that may be of use to descriptors. The names of these variables are reserved and cannot be used as variable or parameter names. The table below describes the purpose of each variable and defines the context in which it is valid.

Name | Description
application | The name of the enclosing application.
application.distrib | The pathname of the enclosing application’s distribution directory, and an alias for ${node.datadir}/distrib/${application}.
node | The name of the enclosing node.
node.os | The name of the enclosing node’s operating system. On Unix, this is value is provided by uname. On Windows, the value is Windows.
node.hostname | The host name of the enclosing node.
node.release | The operation system release of the enclosing node. On Unix, this value is provided by uname. On Windows, the value is obtained from the OSVERSIONINFO data structure.
node.version | The operation system version of the enclosing node. On Unix, this value is provided by uname. On Windows, the value represents the current service pack level.
node.machine | The machine hardware name of the enclosing node. On Unix, this value is provided by uname. On Windows, the value is x86 or x64.
node.datadir | The absolute pathname of the enclosing node’s data directory.
server | The ID of the enclosing server.
server.distrib | The pathname of the enclosing server’s distribution directory, and an alias for ${node.datadir}/servers/${server}/distrib.
service | The name of the enclosing service.
session.id | The client session identifier. For sessions created with a user name and password, the value is the user ID; for sessions created from a secure connection, the value is the distinguished name associated with the connection.

The availability of a variable is easily determined in some cases, but may not be readily apparent in others. For example, you can use the ${node} variable in a property value within a server template definition, because variables in the body of a server template are only evaluated when the server template is instantiated on a specific node.

Variable Substitution in IceGrid Admin Forms

In a number of forms, you can substitute variables and template parameters by their respecitive value. Use View > Show Variables and View > Substitute Variables or the corresponding toolbar toggle buttons:

When variable-substitution is enabled, the descriptors are displayed read-only.

Scoping Rules

Descriptors may only define variables at the application and node levels. Each node introduces a new scope, such that defining a variable at the node level overrides (but does not modify) the value of an application variable with the same name. Similarly, a template parameter overrides the value of a variable with the same name in an enclosing scope. A descriptor may refer to a variable defined in any enclosing scope, but its value is determined by the nearest scope. The diagram below illustrates these concepts:

In this diagram, the variable x is defined at the application level with the value 1. In nodeA, x is overridden with the value 2, whereas x remains unchanged in nodeB. Within the context of nodeA, x continues to have the value 2 in a server instance definition. However, when x is used as the name of a template parameter, the node’s definition of x is overridden and x has the value 3 in the template’s scope.

Resolving a Reference

To resolve a variable reference ${var}, IceGrid searches for a definition of var using the following order of precedence:

· Pre-defined variables
· Template parameters, if applicable
· Node variables, if applicable
· Application variables

After the initial substitution, any remaining references are resolved recursively using the following order of precedence:

· Pre-defined variables
· Node variables, if applicable
· Application variables
· Template Parameters

Template parameters are not visible in nested template instances. This situation can only occur when an IceBox server template instantiates a service template.

Modifying a Variable

A variable definition can be overridden in an inner scope, but the inner definition does not modify the outer variable.


Descriptors

Navigation: Application >

Descriptors

 Print this Topic Return to chapter overview

An application definition is described using one application descriptor with a number of nested sub-descriptors (and sub-sub descriptors). The descriptors correspond to Slice types in the IceGrid registry interfaces, and to XML element in an IceGrid XML representation.

IceGrid Admin maps these descriptors to nodes on a tree representation:


Application

Navigation: Application > Descriptors >

Application

 Print this Topic Return to chapter overview

Creating a new Application

You can create a new application using File > New Application: this opens a new Application pane, with an empty application definition.

When you are connected to an IceGrid registry, you can also use File > New Application with Default Templates from Registry. This also opens new Application pane with a brand new application definition. This new application contains a copy of all the templates definitions contained in the IceGrid registry default template file. See IceGrid.Registry.DefaultTemplates in the [image] Ice manual.

Properties

The Application Properties panel offers the following fields:

Name

The name of the application. This field is not editable for live applications.

Description

A free-text description of this application.

Variables

This table shows application-level IceGrid variables. See Variables.

IcePatch2 Proxy

A stringified (or well-known) proxy for the IcePatch2 server than contains this application's distribution. Possible values:

· "None selected" (default) or blank: no distribution defined
· ${application}.IcePatch2/server: corresponds to the well-known proxy of an IcePatch2 server deployed in this application using the IcePatch2 default server-template (with a default instance-name parameter value).
· Your own value

Directories

List of directories included in the application distribution. When blank, the entire IcePatch2 server repository is used as the distribution.

Children

An application node can have five types of children:

· Node
· Property Set
· Replica Group
· Server Template
· Service Template


Node

Navigation: Application > Descriptors >

Node

 Print this Topic Return to chapter overview

A node represents an IceGrid node that starts and monitors your servers. Several applications can be deployed on the same node; however a node descriptor describes only the servers defined by the enclosing application.

Properties

The Node Properties panel offers the following fields:

Name

The name of the node. This name must match the IceGrid.Node.Name configuration property of the node process.

Description

A free-text description of this node.

Variables

This table shows node-level IceGrid variables. See Variables.

Load Factor

A floating point value used to compare different nodes when making a load-balancing decision based on load-average (for Linux and Unix) or CPU utilization (for Windows). See Replica Group.

Leaving this value blank is equivalent to the default: 1.0 on Linux and Unix, and 1.0 divided by the number of CPUs on Windows.

Children

A node can have two types of children:

· Server
· Property Set


Server

Navigation: Application > Descriptors >

Server

 Print this Topic Return to chapter overview

A server represents an Ice server deployed on a node as part of an application. IceGrid supports three kinds of servers:

· Plain Server: a normal Ice server, with typically a single Ice communicator. IceGrid generates a single Ice configuration file for this server.
· IceBox Server: an IceBox server, with usually a number of IceBox services deployed in it. IceGrid generates an Ice configuration file for the IceBox server itself, and also a separate Ice configuration for each IceBox service.
· Server Instance: a server (either plain server or IceBox server) defined using a server template .


Plain Server

Navigation: Application > Descriptors > Server >

Plain Server

 Print this Topic Return to chapter overview

Properties

The Server Properties panel offers the following fields:

Server ID

The ID of the server; corresponds to the Ice.ServerID property. Each server must have a unique ID within an IceGrid deployment.

Description

A free-text description of this server.

Property Sets

List of property-set IDs; you refer to a property set to "include" all its properties in the server.

Properties

Ice properties private to this server.

Log Files

This table can be used to declare a number of log files used by this server. Path is the path to the log file (a relative path is relative to the IceGrid node working directory); when Property is set, IceGrid generates a property with this name and the log file path as value.

You declare log files to be able to conveniently retrieve them using IceGrid Admin (in the Live Deployment tab) or with the icegridadmin command-line utility.

Path to Executable

Path to the server's executable; cannot be blank. A relative path is relative to the IceGrid node working directory.

Ice Version

The Ice version of this server. If you don't provide a value, IceGrid assumes it's the same version as the IceGrid registry.

Working Directory

The working directory for the server when started by the IceGrid node.

Command Arguments

The command-line arguments given to the server when started by the IceGrid node.

Run as

On Linux and Unix, when IceGrid node is running as root, it is possible to run the server under any username. Enter the desired username in this field.

When not set (the default), the server runs as the same user as the IceGrid node, except when IceGrid node runs as root. In this case, the server runs as nobody.

Environment Variables

The environment variables for the server when started by the IceGrid node. These variables are in addition to variables defined in the IceGrid node own environment.

Activation Mode

The server's activation mode. Must be one of:

· always: IceGrid node keeps this server running all the time
· manual: this server is started "manually", using IceGrid Admin or the icegridadmin command-line utility
· on-demand: IceGrid starts this server when it resolves the object-adapter ID of an object adapter defined in this server
· session: IceGrid starts a separate instance of this server for each IceGrid session that allocates this server
· a variable or combination of variables that resolves to one of the values above

Activation Timeout

When activating a server, IceGrid gives timeout seconds to object adapters with server lifetime to register their endpoints with the IceGrid registry. During this time, lookup for the corresponding adapter IDs are delayed.

If not set or set to 0, the IceGrid node uses the value of its IceGrid.Node.WaitTime property.

Deactivation Timeout

When deactivating a server, IceGrid gives timeout seconds to the server to exit gracefully. After this timeout, the server process is killed.

If not set or set to 0, the IceGrid node uses the value of its IceGrid.Node.WaitTime property.

Allocatable

Specifies whether the server can be allocated. A server is allocated implicitly when one of its allocatable objects is allocated. This checkbox is ignored if the server activation mode is session; a server with this activation mode is always allocatable. Default: false.

Depends on the application distribution

A server that depends on the application distribution is stopped and disabled before any application distribution update, and re-enabled after such update. Default: true.

IcePatch2 Proxy

A stringified (or well-known) proxy for the IcePatch2 server than contains this server's private distribution. Possible values:

· "None selected" (default) or blank: no private distribution defined
· ${application}.IcePatch2/server: corresponds to the well-known proxy of an IcePatch2 server deployed in this application using the IcePatch2 default server-template (with a default instance-name parameter value).
· Your own value

Directories

List of directories included in the server distribution. When blank, the entire IcePatch2 server repository is used as the distribution.

Children

A plain server can have two types of children:

· Adapter
· Database Environment


IceBox Server

Navigation: Application > Descriptors > Server >

IceBox Server

 Print this Topic Return to chapter overview

Properties

The Properties panel for an IceBox server is identical to the Properties panel for a Plain Server.

When you create a new IceBox server, some properties are created automatically:

· IceBox.InstanceName=${server}
· Ice.Admin.Endpoints=tcp -h 127.0.0.1

The Ice.Admin.Endpoints setting enables the Admin object in the main communicator of this IceBox server. See Ice.Admin.Endpoints in the [image] Ice manual.

The Path to Executable is typically icebox, iceboxd (for a C++ IceBox), java (for a Java IceBox) or iceboxcs (for a .NET IceBox). In Java, the Command Arguments should include the IceBox container class name, IceBox.Server.

Children

An IceBox server can have only one type of children, Service.


Server Instance

Navigation: Application > Descriptors > Server >

Server Instance

 Print this Topic Return to chapter overview

A server instance is a server created from a server template; it may be a plain server or an IceBox server.

Properties

The Server Instance Properties panel offers the following fields:

Template

The name of the Server Template.

Parameters

Use this table to assign values to the template parameters defined in the server template.

Property Sets

List of property-set IDs; you refer to a property set to "include" all its properties in this server-instance.

Properties

Ice properties private to this server. Overall, the properties of the server instance are a combination of properties defined in the server template (including its own property sets references) augmented and possibly overridden by properties defined in the server instance.

Children

An instance of an IceBox server template can have one type of children, Property Set.

An instance of a plain server template cannot have any child.


Adapter

Navigation: Application > Descriptors >

Adapter

 Print this Topic Return to chapter overview

Each indirect object adapter registered with IceGrid requires its own Adapter descriptor. If you need to specify a direct adapter, simply create a number of Ice properties in your server.

Properties

The Adapter Properties panel offers the following fields:

Adapter Name

The name of the object adapter. This name must be unique within the enclosing Ice communicator, and is only used to lookup adapter properties.

Description

A free-text description of this object adapter.

Adapter ID

The ID of the object adapter. This ID must be unique within an IceGrid deployment. Default value: ${server}.adapter-name.

Replica Group

The ID of this adapter's Replica Group. By default, an adapter does not belong to any replica group.

Priority

The adapter priority in its Replica Group. The default priority is 0.

Endpoints

The configured endpoints for this object adapter. Corresponds to the adapter-name.Endpoints property. Default: default, which means listen using the default protocol (tcp by default) on an OS assigned port, on all interfaces.

Published Endpoints

The configured published endpoints for this object adapter. Corresponds to the adapter-name.PublishedEndpoints property. Default: Actual endpoints, derived by Ice from the Endpoints field above.

Register Process

This setting is ignored for servers running Ice version 3.3 or greater.

When checked, this adapter will create and register an Ice::Process object with IceGrid during activation. Such object is used to cleanly shutdown the server from IceGrid. Each server should register one, and only one such Ice::Process object.

Server Lifetime

When checked, IceGrid expects this adapter to register its endpoints during server startup and unregister them during server shutdown. See also Activation Timeout. Default: true (checked).

Well-known Objects

A table of well-known objects defined by this adapter. When Property is set, IceGrid generates a property with this name and with Identity as value.

Allocatable Objects

A table of allocatable objects defined by this adapter. When Property is set, IceGrid generates a property with this name and with Identity as value.


Database Environment

Navigation: Application > Descriptors >

Database Environment

 Print this Topic Return to chapter overview

Properties

The Database Environment Properties panel offers the following fields:

Name

The name of the Freeze Database Environment. This name must be unique within the enclosing Ice communicator.

Description

A free-text description of this database environment.

DB Home

The path of the home directory of the Berkeley DB environment. The default is "Created by the IceGrid Node": when selected, IceGrid node creates automatically a directory in its local server tree. Otherwise, if you enter your own value, the path must exist: IceGrid node will not create it if it does not.

Properties

This table shows a list of Berkeley DB properties for this database environment. These are not Ice properties! IceGrid generates a DB_CONFIG file in the DB Home directory with these settings.


Service

Navigation: Application > Descriptors >

Service

 Print this Topic Return to chapter overview

A service represents an IceBox service deployed on an IceBox server. IceGrid supports two kinds of services:

· Plain Service: a service defined directly with a service descriptor
· Service Instance: a service defined using a service template

Load Order

The load-order of services within an IceBox server is determined by their display order in IceGrid Admin. You can reorder services using Edit > Move Up or Edit > Move Down (also available from each service's contextual menu).


Plain Service

Navigation: Application > Descriptors > Service >

Plain Service

 Print this Topic Return to chapter overview

Properties

The Service Properties panel offers the following fields:

Service Name

The name of the service. Must be unique within the enclosing IceBox server.

Description

A free-text description of this service.

Property Sets

List of property-set IDs; you refer to a property set to "include" all its properties in the service.

Properties

Ice properties private to this service.

Log Files

This table can be used to declare a number of log files used by this service. Path is the path to the log file (a relative path is relative to the IceGrid node working directory); when Property is set, IceGrid generates a property with this name and the log file path as value.

You declare log files to be able to conveniently retrieve them using IceGrid Admin (in the Live Deployment tab) or with the icegridadmin command-line utility.

Entry Point

The service's entry point, for example IceStormService,32:createIceStorm.

IceGrid will append --Ice.Config=path-to-service-config-file to this entry point when it generates the IceBox.Service.service-name property in the enclosing IceBox server config file.

Children

A plain service can have two types of children:

· Adapter
· Database Environment


Service Instance

Navigation: Application > Descriptors > Service >

Service Instance

 Print this Topic Return to chapter overview

Properties

The Service Instance Properties panel offers the following fields:

Template

The name of the Service Template.

Parameters

Use this table to give values to the template parameters defined in the service template.

Property Sets

List of property-set IDs; you refer to a property set to "include" all its properties in the service.

Properties

Ice properties private to this service.


Property Set

Navigation: Application > Descriptors >

Property Set

 Print this Topic Return to chapter overview

A Property Set defines a set of Ice properties. IceGrid Admin supports two kinds of Property Sets:

· Named Property Set, defined within an application or within a node. Server and service definitions refer to such property sets to "include" the corresponding properties.
· Service-Instance Property Set, defined as a child of an IceBox server instance. Such a property set provides properties to a service instance within a concrete IceBox server.

Properties

The Property Set Properties panel offers the following fields:

ID

(Named Property Set only) The ID of a named property set.

Service Name

(Service Instance property set) The service name.

Property Sets

List of Property Set IDs. The corresponding property sets are "included" in this property set.

Properties

Ice properties private to this Property Set


Replica Group

Navigation: Application > Descriptors >

Replica Group

 Print this Topic Return to chapter overview

A replica group represents an abstract grouping of identical, or very similar, object adapters. An object adapter joins this group by setting this replica group ID in its Replica Group field.

Properties

The Replica Properties panel offers the following fields:

Replica Group ID

The ID of this replica group. Must be unique within an IceGrid deployment.

Description

A free-text description of this replica group.

Well-known Objects

A table of well-known objects defined by this replica group.

Load Balancing Policy

The load-balancing policy used by IceGrid when resolving the Replica Group ID in proxies. Must be one of:

· Adaptive: return the endpoints of the object adapters whose nodes report the lowest load-average (on Linux/Unix) or CPU utilization (on Windows). The actual load-average or CPU utilization value of each node is multiplied by the node's load-factor for this comparison. See Load Sample below, and Node.
· Ordered: return the endpoints of the object adapters with the highest priority. See Adapter.
· Random: returns the endpoints of object adapters selected at random. This is the default policy.
· Round-robin: IceGrid puts all the object adapters in a list, and for each new resolution, it returns the endpoints from the next How many Adapters items on this list.

How many Adapters

Specify the number of object adapters selected by IceGrid for each resolution. 1 is a common value.

When set to 0 (the default), IceGrid returns the endpoints of all object adapters in this replica group.

Load Sample

Available only with the Adaptive load-balancing policy. Specify the load-average or CPU utilization sample to use when comparing nodes: it can be 1 (default), 5 or 15 minutes.


Server Template

Navigation: Application > Descriptors >

Server Template

 Print this Topic Return to chapter overview

A server template is used to capture the common definitions of several similar or identical servers.

Properties

The Server Template Properties panel offers the following fields:

Template ID

The ID the template. Must be unique within the application.

Parameters

The list of parameters for this template. Each parameter can have an optional default value.

Plain Server Properties

The remaining fields are the Plain Server fields.

Children

A plain server template can have two types of children:

· Adapter
· Database Environment

An IceBox server template can have only one kind of children, Service.


Service Template

Navigation: Application > Descriptors >

Service Template

 Print this Topic Return to chapter overview

A service template is used to capture the common definitions of several similar or identical services.

Properties

The Service Template Properties panel offers the following fields:

Template ID

The ID the template. Must be unique within the application.

Parameters

The list of parameters for this template. Each parameter can have an optional default value.

Plain Service Properties

The remaining fields are the Plain Service fields.

Children

A service template can have two types of children:

· Adapter
· Database Environment