Previous Up Next

Chapter 6  Orbix Administration Made Simple

Orbix administration is performed through sub-commands of the itadmin utility. Each sub-command performs a small amount of work so you typically need to execute several itadmin commands to complete a useful unit of work, such as registering an Orbix server with the Implementation Repository (IMR) or updating configuration variables. However, itadmin has a built-in scripting language. This makes it possible to write a script that performs the entire sequence of itadmin commands required to carry out a task. This chapter discusses several useful task-based itadmin scripts:

orbix_srv_admin
can be used to perform several of the most commonly required administration tasks associated with Orbix servers, such as registering an Orbix server with the IMR and initializing or updating configuration values for the server.
orbix_set_config_vars
can initialize and update configuration values for an application but it does not attempt to interact with the IMR. As such, this script contains a subset of the functionality of orbix_srv_admin. This script is typically used with client applications or servers that are being deployed without an IMR.
orbix_notify_service
registers a Notification Service with Orbix. When Orbix is initially configured with the itconfigure utility, you can choose to create one Notification Service. However, some organizations like to have additional instances of the Notification Service to increase throughput. This utility makes it easy to do this.
orbix_ns_on_fixed_port
reconfigures the Naming Service so that it can listen on a fixed port.

6.1  Introduction

Many CORBA servers are deployed through an Implementation Repository (IMR).1 Some administration tasks are commonly performed on such Orbix server applications. For example:

Although many CORBA servers are deployed through an IMR, some are deployed without an IMR and, of course, client applications are also deployed without an IMR. There is still some administration that is associated with such IMR-less applications. In particular, you may wish to set configuration variables for such applications.

All Orbix administration tasks are performed with various sub-commands of the itadmin utility. However, each individual sub-command of itadmin performs just a small amount of work. Because of this, you typically need to execute several itadmin commands to complete a useful unit of work, such as registering an Orbix server. However, itadmin has a built-in scripting language. This built-in scripting language makes it feasible to write a script that performs the entire sequence of itadmin commands required to carry out a task.

This chapter discusses several itadmin scripts. One, called orbix_srv_admin, performs common IMR-related administration tasks associated with servers and also initializes/updates configuration variables for a server. Another script, called orbix_set_config_vars, initializes or updates configuration values for an application but it does not attempt to interact with the IMR. As such, this script contains a subset of the functionality of the orbix_srv_admin. This script is typically used with client applications or servers that are being deployed without an IMR. The orbix_notify_service script makes it easy to register several Notification Services with the IMR. The final script, orbix_ns_on_fixed_port, automates the steps required to reconfigure the Naming Service so that it listens on a fixed port (which makes it firewall-friendly).

These scripts can be used to perform several of the most commonly required administration tasks associated with Orbix applications. This has the immediate benefit of simplifying administration of Orbix applications. An additional benefit is that these scripts can echo out the itadmin command that they execute. This allows users to see the sequence of itadmin commands required for various tasks. Because of this, these scripts can be used as self-teaching tools to help people more quickly master the enormous power and flexibility of itadmin.

6.2  What is an Implementation Repository (IMR)

The CORBA specification mentions the concept of an implementation repository (IMR), but does not discuss it in much detail because much of the functionality of an IMR is platform-dependent, whereas the CORBA specification focuses on platform-independent concepts.

This section explains the central concepts of an IMR. We start by explaining the CORBA concept of an IMR. We then provide a high level overview of the Orbix implementation of an IMR and finally outline the details of what Orbix stores in its IMR database.

6.2.1  The CORBA Concept of an Implementation Repository

The CORBA specification describes an implementation repository. This term is not very intuitive so it deserves an explanation. Implementation is the CORBA terminology for “server application”, and repository means a persistent storage area, such as a database. Thus, implementation repository (commonly abbreviated to IMR) is a database that stores information about CORBA server applications.

The CORBA specification contains only a partial definition of an IMR. In particular, the specification states the high-level functionality that an IMR should provide, but the specification does not state how this functionality should be implemented. Neither does the specification state how the IMR should be administered. The need for a partial specification is because much of the functionality of an IMR must be implemented and administered in a platform-specific manner. For example:

In essence, an IMR running on a mainframe would not only be implemented differently to an IMR running on a PC or on an embedded device, but it would also be administered differently too. Put simply, one CORBA vendor’s IMR running on one kind of computer might have a very different “look and feel” to another CORBA vendor’s IMR running on a different kind of computer. This wide variation in IMRs is the reason why the CORBA specification contains only a high-level discussion about IMRs.

6.2.2  The Orbix Implementation Repository

The Orbix IMR is implemented with the following components:

  1. A database is used to record information about server applications.
  2. A locator daemon (itlocator2 ) provides a CORBA server wrapper around the IMR database.
  3. The itadmin utility is a command-line-driven CORBA client that communicates with the locator daemon in order to query and update the IMR database.
  4. Whenever the locator daemon wants to start or stop a server process, it delegates the starting/stopping task to a node daemon (itnode_daemon). The node daemon also “pings” servers periodically to check if they are still alive. There should be a node daemon running on every machine on which the IMR may want to launch a server application. When a server application is registered with the IMR, one piece of the registration information specifies the node daemon (host) that should be used for running the server.

Placing some functionality of an IMR in the locator daemon and other functionality in the node daemons is a technique that is used by several CORBA vendors (although other CORBA vendors will use terminology other than locator daemon and node daemon). This separation of functionality offers one important benefit for a CORBA vendor and a different important benefit for their customers:

You create an IMR by running the itconfigure utility. Full details of this are given in the Orbix Administrator’s Guide. You should note that “Implementation Repository” (IMR) is CORBA terminology. It is common for CORBA vendors to use a different name for their own IMR. For example, the Orbix name for an IMR is a location domain. A location domain is simply the contents of the IMR database (that is, the details for all registered server applications) plus the locator daemon and its supporting node daemon(s).

Orbix does not place any restriction on how many or how few IMRs you can create and whether different IMRs run on the same or different computers. Rather, the choice on the number of IMRs installed in an organization is typically due to pragmatic considerations. For example, it is common for each developer to have his/her own “private” IMR for day-to-day development work. Another IMR might be used for system testing and yet another IMR might be used for deployed applications. An organization might find it convenient to have several “deployment” IMRs: perhaps a separate one for each branch or department in the organization, or perhaps one IMR for, say, payroll applications and another IMR for stock-control applications.

6.2.3  What is Stored in the Implementation Repository?

When you register an Orbix-based server application with an IMR, you have to register three different kinds of entities: a process, an orbname and the POAs in the server’s POA hierarchy.

The term process means the set of details required for launching a server application. This includes:

A process is registered with the IMR through the following command: 

itadmin process create [options] <process-name>

Command-line options are used to specify the details of the process, such as the executable name, the command-line arguments, environment variables and so on.

There is an ORB object inside each CORBA-based application, and this ORB can be given a name through the "-ORBname <orbname>" command-line argument when starting an Orbix application. In effect, the orbname is the application’s name that identifies the application to the IMR. Before running an application, you can register its orbname with the IMR. This serves the following purposes:

An orbname is registered with the IMR through the following command: 

itadmin orbname create [-process <process-name>] <orb-name>

When an application is started, the application’s orbname determines what set of configuration information will be used by the Orbix runtime system. Application-level code can use Orbix-proprietary APIs to obtain application-level configuration information from the same place, or alternatively an application can obtain its runtime configuration information from somewhere else.

A CORBA server application uses a collection of POAs to manage its objects. POAs in an application are arranged in a hierarchy and each POA is either transient or persistent:

A poa is registered with the IMR through the following command: 

itadmin poa create [options] <hierarchical-poa-name>

Command-line options to the command are used to specify the details of the poa, such as whether it is transient or persistent, which (list of) orbname(s) it is associated with and, for a replicated poa, its load-balancing strategy.

When you compile or install a pre-compiled Orbix-based server application, you should register its process, orbname and poa hierarchy with an IMR. This registration occurs just once, because the IMR stores all the details in its database.

The registration details of a server are said to be static because they rarely change. The IMR also records dynamic (that is, frequently updated) information such as the host and ports of servers that are currently running. It uses this information when it needs to redirect a client to an appropriate server and also so that it can re-launch a server on an as-needed basis.

6.3  Building Task-based Utilities with itadmin

When you register an Orbix-based server application with an IMR (locator daemon), you typically execute a series of itadmin commands to:

It is not uncommon for a user to execute a series of 10 or more itadmin commands in order to register a server application. Executing this many itadmin commands is tedious and somewhat error-prone. However, the task can be made much simpler by writing a higher-level utility that encapsulates the lower-level itadmin commands. Before discussing such utilities, it is instructive to discuss how the utilities were built, because readers may wish to write their own utilities using similar techniques.

The following is a list of three ingredients vital to building task-based utilities on top of itadmin:

  1. It is important to know that itadmin has a built-in interpreter for the Tcl (pronounced “tickle”) scripting language. Tcl scripts have a ".tcl" file extension. If you write a Tcl script called foo.tcl then you can execute it with itadmin as shown below: 
    	itadmin foo.tcl ...
  2. Tcl programmers often employ the following useful technique. Tcl has a source command that is used to read and execute the Tcl commands in another file. This means that a programmer does not have to write a configuration-file parser for a Tcl-based application. Instead, the configuration information can be stored as a collection of Tcl assignment statements in one file and this file can then be sourced into the main Tcl application. The utilities discussed in this chapter use this technique to read a description file that (using Tcl syntax) describes an Orbix server application. Section 6.3.1 provides a brief overview of enough Tcl syntax to make people comfortable editing these Tcl-based description files.
  3. Once you have written an itadmin script called, say, foo.tcl, people could run the script as: 
    	itadmin /full/path/to/foo.tcl ...
    However, this is somewhat awkward because users need to type the full path to the script they want to run. Instead, it is a good idea to write a simple Windows batch file (or a UNIX shell script) wrapper that, internally, executes itadmin with the appropriate command-line arguments. Once this batch file (or shell script) has been put into a bin directory, users can then run the utility by simply typing "foo ...".

6.3.1  Overview of Tcl Syntax

Assignments to variables are made with the set command. This is illustrated in the examples below: 

set a "hello, world"
set b hello
set c 42;                # this is a comment

Commands can be terminated by a newline character or optionally by a semicolon. Comments start with # and continue to the end of the line. If you have a comment on the same line as another statement then you must terminate the statement with a semicolon before starting the comment. If a command is too long to fit on one line then you can use a backslash immediately followed by a newline character in order to continue the command on the next line.

Tcl treats all values as strings. In the above example, the value 42 assigned to variable c looks like an integer but it really is a string.3 Quotes are needed for the "hello, world" string because that string contains a space. However, the use of quotes is optional if a string does not contain any spaces. For example, there are no quotes around the strings hello or 42 in the above assignment statements.

The value of a variable is obtained by prefixing the variable’s name with $. For example: 

set a hello
set b goodbye
set c "$a and $b"

The above example also illustrates that the use of $ works inside quoted strings.

The backslash character is used as an escape character in Tcl. Because of this, you must use two backslashes if you want to embed a backslash in a string. This is often used to express Windows filenames, as shown in the example below: 

set filename "C:\\temp\\foo.txt"

Actually, Tcl is quite happy using forward slashes in Windows filenames, so the above example could be written more conveniently as shown below: 

set filename "C:/temp/foo.txt"

Tcl uses round brackets to indicate that a variable is an “array”. Tcl’s concept of an array is more like the concept of a lookup table or map in other programming languages. The env() array is used to access environment variables: 

set foo(a) hello
set foo(b) goodbye
set c "$foo(a) and $foo(b)"
set x $env(PATH)

If you want to use the return value of a function call as a parameter to another command then you surround the function call with square brackets, as shown in the following example: 

set x [factorial 5]

Lists (of strings) are enclosed in braces. For example: 

set colors {red green "light blue"}

Using $ to access the value of a variable does not work inside braces. For example, the following does not work as you might hope: 

set color1 "red"
set color2 "green"
set color3 "light blue"
set colors {$color1 $color2 $color3}

Instead, you can use the list command to build a list: 

set color1 "red"
set color2 "green"
set color3 "light blue"
set colors [list $color1 $color2 $color3]

Obviously, there is a lot more to Tcl, such as while-loops, if-then-else statements and procedures. However, the above discussion of Tcl syntax is sufficient for readers to understand how to edit description files that are used with orbix_srv_admin and orbix_set_config_vars.

6.4  Using orbix_srv_admin

The orbix_srv_admin utility is a task-based itadmin script that makes it easy to perform common administration tasks associated with Orbix servers. For example, orbix_srv_admin can be used to register and unregister Orbix servers. It can also be used to start and stop a registered server and to update configuration variables for a registered server. You can get a usage statement by running orbix_srv_admin with the -h option. The usage statement looks like that shown below: 

usage: orbix_srv_admin [options] file.des
options are:
    -s          Silent mode
    -n          Do not execute commands. Just show them
    -h          Print this usage statement
    -create     Create a starting-point description file
    -register   Register the application’s details
    -unregister Unregister the application’s details
    -start      Start the server
    -stop       Stop the server
    -set_vars   Set or update the server’s configuration variables
    -launch_cmd Print the server’s launch command

As can be seen from the usage statement, orbix_srv_admin takes a .des (description) file as a command-line argument. This file uses Tcl syntax to describe an Orbix server application. You do not need to write such a description file by hand, because orbix_srv_admin can create a starting-point description file for you. Let us assume that you want to perform administration tasks on an Orbix-based server that is part of a payroll-processing system. You can create a starting-point description file called payroll.des by running the following command: 

orbix_srv_admin -create payroll.des

The first part of the generated description file, shown below, specifies how to launch a server application. 

set orb_name          "acme.uk.payroll"
set process_name      $orb_name
set root_poa_name     $orb_name
set description       ""
set startup_mode      "on_demand"; # on_demand or disable
#——–
# File names on Windows can be expressed as "C:/full/path/to/file"
# or as "C:\full\path\to\file"
#——–
set executable        "/full/path/to/executable"
set cmd_line_args     "x y z"
set working_directory "/full/path/to/current/working/directory"
#——–
# If "env_var_list" is set to an empty list "{}" then the launched
# application inherits all the environment variables from the node
# daemon that launched it. If "env_var_list" is not empty then the
# launched application does not inherit any environment variables
# from the node daemon, and instead has only the environment
# variables listed in "env_var_list".
#——–
set env_var_list      [list \
            "PATH=$env(PATH)" \
            "CLASSPATH=$env(CLASSPATH)" \
            "SYSTEMROOT=$env(SYSTEMROOT)" \
            "IT_CONFIG_DOMAINS_DIR=$env(IT_CONFIG_DOMAINS_DIR)" \
            "IT_DOMAIN_NAME=$env(IT_DOMAIN_NAME)" \
            "IT_LICENSE_FILE=$env(IT_LICENSE_FILE)" \
        ]
#——–
# If "node_daemon_list" contains several entries then the server
# will be registered as a replicated server and "load_balancer"
# specifies the load-balancing policy (random, round_robin or active)
# to be used. If "node_daemon_list" contains just one entry then
# "load_balancer" is ignored.
#——–
set node_daemon_list  {iona_services.node_daemon.pizza}
set load_balancer     "random"; # random, round_robin or active
#——–
# UNIX-specific. These entries are ignored on Windows
#——–
set group             "nobody"
set user              "fred"
set umask             "755"

As you can see, the description file contains a sequence of Tcl assignment statements (an overview of Tcl syntax is provided in Section 6.3.1). Once you are familiar with the concepts behind the information stored in the IMR (see Section 6.2.3), then most of the variable names and values are quite intuitive. The comments in the generated file explain most of the subtle points.

The most important point to note that is not discussed in the comments is that although process_name, orb_name and root_poa_name can have different values, it is typically a good idea to use the same name for all of them. This is because the process_name, orb_name and root_poa_name are closely related concepts; using the same name for each makes it easy to see their relationship to each other. The name chosen can have embedded periods, such as "acme.uk.payroll" shown in the above example. It is a good idea to use an orb_name with embedded periods because when the application is launched, Orbix will first search for runtime configuration information in the acme.uk.payroll configuration scope. If any configuration values are missing from this scope then Orbix starts searching in surrounding scopes—in the acme.uk scope, then the acme scope and finally the global scope—to find runtime configuration values. In essence, variables in outer scopes supply default configuration values for applications, and these values can be selectively overridden by redefining the variables in inner scopes. This is a very useful feature of Orbix because related applications tend to have similar configuration values. Rather than specifying dozens of configuration values for each and every Orbix application, it is possible to specify the “common” values in an outer scope and then specify only the different values in inner scopes specific to each application.

The next entry in the description file gives details of the POA hierarchy in the server application: 

#——–
# Each line in poa_hierarchy is a pair of the form:
#       lifespan full/path/to/poa-name
# where lifespan can be one of: transient or persistent
#——–
set poa_hierarchy {
    persistent  FooFactory
    persistent  FooFactory/Foo
    transient   FooFactory/Foo/FooIterator
    persistent  Administration
}

The next entry specifies runtime configuration variables that should be set in the orb_name configuration scope. 

#——–
# Each line in runtime_config_variables is a triplet of the form:
#        type name value
# The type can be one of: long, bool, list, string or double
# list values are comma-separated strings
# bool values can be: true or false
#——–
set runtime_config_variables {
    string  plugins:local_log_stream:filename "server.log"
    list    event_log:filters                 "*=WARN+ERR+FATAL"
    long    thread_pool:high_water_mark       "5"
    long    thread_pool:low_water_mark        "5"
    long    thread_pool:initial_threads       "5"
    long    thread_pool:max_queue_size        "500"
}

Section 6.9 discusses useful runtime configuration variables that you might wish to use in a deployed application.

If you are registering the server as a replicated server (that is, with multiple node daemons) then you can optionally also specify runtime configuration variables for each replica with Tcl variables called runtime_config_variables_replica_<number>. The generated starting-point description file contains sample details for three replicas: 

set runtime_config_variables_replica_1 {
    string  plugins:local_log_stream:filename "server.replica_1.log"
}
set runtime_config_variables_replica_2 {
    string  plugins:local_log_stream:filename "server.replica_2.log"
}
set runtime_config_variables_replica_3 {
    string  plugins:local_log_stream:filename "server.replica_3.log"
}

You should modify the starting-point description file so that it contains details appropriate for the payroll server application. Once you have done that you can register the payroll server with the command: 

orbix_srv_admin -register payroll.des

When you run that command, orbix_srv_admin executes all the individual commands required to register the server.

You can start the registered server with the command: 

orbix_srv_admin -start payroll.des

If the server was registered as a replicated server then the above command causes all the replicas to be started.

You can stop the registered server with the command: 

orbix_srv_admin -stop payroll.des

If the server was registered as a replicated server then the above command stops all the replicas.

If you want to modify the runtime configuration variables for the server then you should modify the runtime_config_variables entry in payroll.des and then run the command: 

orbix_srv_admin -set_vars payroll.des

Note that an already-running server will not notice the updated runtime configuration variables. Instead, you will have to stop and then re-start the server for the new variables to take effect.

The -unregister option of orbix_srv_admin can be used to unregister the application. This is useful if you have already deployed a server and want to make changes to how it is deployed, for example, you want to change its command-line arguments or turn it from being an un-replicated server to a replicated one. In such cases, you should unregister the server, then make appropriate changes to payroll.des and finally re-register the server.

6.5  Using orbix_set_config_vars

The orbix_set_config_vars utility contains just a small subset of the functionality of orbix_srv_admin.

You can get a usage statement by running orbix_set_config_vars with the -h option. The usage statement looks like that shown below: 

usage: orbix_set_config_vars [options] file.des
options are:
    -s          Silent mode
    -n          Do not execute commands. Just show them
    -h          Print this usage statement
    -create     Create a starting-point description file

As can be seen from the usage statement, orbix_set_config_vars takes a .des (description) file as a command-line argument. This file uses Tcl syntax to describe the configuration variables required for an Orbix application. You do not need to write such a description file by hand, because orbix_set_config_vars can create a starting-point description file for you.

Let us assume that you want to manipulate configuration variables for Orbix-based client application that is part of a payroll-processing system. You can create a starting-point description file called payroll_client.des by running the following command: 

orbix_set_config_vars -create payroll_client.des

The generated description file is shown below. 

#——–
# The orb_name specifies the configuration scope where configuration
# variables will be set.
#——–
set orb_name          "acme.uk.payroll_client"

#——–
# Each line in runtime_config_variables is a triplet of the form:
#        type name value
# The type can be one of: long, bool, list, string or double
# list values are comma-separated strings
# bool values can be: true or false
#——–
set runtime_config_variables {
    string  plugins:local_log_stream:filename   "server.log"
    list    event_log:filters                   "*=WARN+ERR+FATAL"
    long    thread_pool:high_water_mark         "5"
    long    thread_pool:low_water_mark          "5"
    long    thread_pool:initial_threads         "5"
    long    thread_pool:max_queue_size          "500"
}

This file contains just two variables: orb_name and runtime_config_variables. The latter specifies the runtime configuration variables that should be set, while orb_name specifies the configuration scope in which the variables should be set. If these variables look familiar then that is because description file used by orbix_set_config_vars is a subset of the description file used by orbix_srv_admin.

You should modify the starting-point description file so that it contains details appropriate for the payroll_client application. Then you can rerun orbix_set_config_vars command (without the -create option) on the description file: 

orbix_set_config_vars payroll_client.des

Running the above command causes the Orbix configuration domain to be updated with the variables specified in the description file.

6.6  Using orbix_notify_service

When you run the itconfigure GUI to set up an Orbix environment, you can choose to have one instance of a Notification Service running. A single Notification Service is adequate for many organizations. However, some organizations that make heavy use of a Notification Service may find that a single instance limits scalability, and so may wish to have several instances of the Notification Service running, with some consumer and supplier applications configured to use one Notification Service, other consumer and supplier applications configured to use another Notification Service, and so on. The orbix_notify_service utility is useful in such situations. It is based on—and has a very similar “look and feel” to—orbix_srv_admin (Section 6.4).

All the command-line options of the orbix_notify_service utility are identical to those of orbix_srv_admin (Section 6.4), but have a behavior that is tailored to the requirements of the Notification Service.

You can create a starting-point description file called foo.des by running the following command: 

orbix_notify_service -create foo.des

The first part of the generated description file, shown below, contains a few variable setting that you might wish to change: 

set group             "nobody"
set user              $::tcl_platform(user); # current user
set umask             "755"
set unique_name_part  "[exec hostname]"
set orb_name          "iona_services.notify_$unique_name_part"
set named_key         "NotificationService_$unique_name_part"

The following points should be noted:

The remaining entries in the generated .des file should be left alone, as they have been preset to suitable values for a Notification Service.

Once you are happy with the contents of the .des file, you can then register the Notification Service by running orbix_notify_service with the -register option. Doing this causes the server to be registered similarly to the way that orbix_srv_admin registers a server, but with the following “added value” steps:

If you run orbix_notify_service with the -unregister option then it unregisters the Notification Service in a manner similar to how orbix_srv_admin unregisters a server, but it also removes the stringified IOR file in the var sub-directory of your Orbix domain and deletes the named key entry.

The other command-line options (-start, -stop, -set_vars and -launch_cmd) work with orbix_notify_service in the same way that they work with orbix_srv_admin.

6.7  Using orbix_ns_on_fixed_port

If you have a Naming Service in an IMR-based Orbix environment then itconfigure configures the Naming Service so that it listens on a random port each time it is started.4 Having the Naming Service listen on a random port is acceptable for a great many deployed CORBA systems. However, the use of a random port can cause communication problems if the Naming Service is to be accessed through a firewall; this is because firewall routers normally allow TCP/IP communication only to a collection of specified, fixed ports. There are two possible approaches to making the Naming Service accessible through a firewall.

One approach is to use the Orbix firewall proxy service that is provided with Orbix 6. The firewall proxy service acts as a delegation server: it listens on a fixed port (so it is firewall-friendly) and delegates all received messages to back-end servers, such as the Naming Service. Interested readers should look in the Orbix Administrator’s Guide for details about this service.

Some people may wish to not use the Orbix firewall proxy service, or they may be using an older version of Orbix that does not provide that service (the firewall proxy service was introduced in Orbix 6.0). Thankfully, there is a second approach to making the Naming Service firewall-friendly. This involves reconfiguring the Naming Service so that it listens on a fixed port. A Knowledge Base article5 available from the IONA web site explains the steps required to reconfigure the Naming Service so that it listens on a fixed port. The orbix_ns_on_fixed_port utility automates most of the steps discussed in the Knowledge Base article, thereby allowing you to complete the reconfiguration faster. Note that orbix_ns_on_fixed_port is intended to be used with non-replicated Naming Services; it has not been designed to reconfigure a replicated Naming Service.

Before using orbix_ns_on_fixed_port, it is strongly recommended that you make a backup of the Orbix configuration files and the var directory of your Orbix environment. The configuration files are held in the directory indicated by the IT_CONFIG_DOMAINS_DIR environment variable, and the var directory is indicated by running the following command: 

itadmin variable show o2k.data.root

The reason for performing a backup is that the orbix_ns_on_fixed_port utility makes some very important changes to your Orbix environment. This utility is believed to be bug-free, but if it misbehaves then it could have the side effect of leaving the Naming Service in a nonworking state. In such a case, the easiest way to undo the damage is to restore the configuration files and var directory from their backups. The Orbix Administrator’s Guide contains information on two different ways to backup individual databases of the Orbix services. However, the simplest way to perform a backup is as follows:

You can get a usage statement of orbix_ns_on_fixed_port by running it with the -h option. The usage statement looks like that shown below: 

usage: orbix_ns_on_fixed_port [options]
options are:
    -s           Silent mode
    -n           Do not execute commands. Just show them
    -l <host>    Local host name           (example: foo)
    -f <host>    Fully-qualified host name (example: foo.bar.com)
    -port <port> Fixed port
    -h           Print this usage statement

When you run the utility, you must specify the -port, -l and -f options. For example: 

orbix_ns_on_fixed_port -port 5000 -l foo -f foo.bar.com

The -port option is used to specify the fixed port on which the Naming Service is to listen. The -l option specifies the local hostname of the machine. This is used to find the correct configuration scope for the Naming Service.6 The -f option specifies the hostname or IP address that will be embedded in the IOR for the Naming Service. You typically use this option to specify a fully-qualified hostname, such as foo.bar.com, but if you want you could specify an IP address or even just the local hostname.

When you run orbix_ns_on_fixed_port, it performs most of the reconfiguration steps required for the Naming Service to listen on the specified fixed port. However, there are a few steps remaining that must be completed manually. The orbix_ns_on_fixed_port utility prints these steps when it terminates: 

To finish, you have to do the following...
        1. Ensure that "start_<domain>_services" starts itnaming
        2. Run "stop_<domain>_services"
           (ignore any error messages regarding the Naming Service)
        3. Run "start_<domain>_services"

To expand on those notes a bit, you should:

  1. Edit the start_<domain>_services UNIX shell script (or Windows batch file), where you replace <domain> with the name of your Orbix domain. Depending on what options you choose when creating your Orbix domain, that file may or may not contain a statement to start itnaming, which is the Naming Service executable. If the file does not start itnaming then you should add the following statement at the end of the file: 
    itnaming -background run -ORBname iona_services.naming.<host>
    Replace <host> with the same host name that you used with the -l option when running orbix_ns_on_fixed_port.
  2. Then run stop_<domain>_services, where you replace <domain> with the name of your Orbix domain. When you run this script, it will complain that it cannot kill the Naming Service. It is safe to ignore this error, because the Naming Service is already dead.
  3. Finally, run start_<domain>_services, where you replace <domain> with the name of your Orbix domain. This script restarts the Orbix services. As part of doing this, the Naming Service will listen on the desired port.

6.8  Using the Utilities to Learn About itadmin

By default, the utilities discussed in this chapter echo all the itadmin commands that they execute. The -s (silent) command-line option instructs these utilities to not echo the itadmin commands that they execute.

The default behavior of echoing each itadmin command as it is executed is a very useful feature because it means that the utilities can be used as a self-teaching tool to learn more about itadmin. For example, you can use orbix_srv_admin to register a server and then look at the echoed itadmin commands in order to understand the steps involved. You can then use the itadmin commands discussed below to query the IMR in order to see the relationships between the created process, orbname and poa entities in the IMR database.

If you are going to type a lot of itadmin commands interactively then you will quickly tire of repeatedly typing "itadmin <name-of-command> <arguments>". Instead, if you run itadmin without any command-line arguments then you will be put into a Tcl shell. Within this shell you can type commands without having to give the "itadmin" prefix. Some useful commands to type within this shell are shown below: 

process list
process list -active
process show <process-name>
orbname list
orbname list -active
orbname show <orbname>
poa list
poa list -active
poa show <poa-name>
scope list [<scope-name>]
scope show <scope-name>

In general, the list version of commands prints a list of all the processes/orbnames/poas/scopes. The "list -active" version lists only those processes/orbnames/poas that are currently active (running). The show version of a command displays details of the specified process/orbname/poa/scope. You can find details of all the available itadmin commands in the Orbix Administrator’s Guide.

6.9  Useful Configuration Variables

The Orbix runtime system makes extensive use of runtime configuration information. A complete list of all the runtime configuration variables can be found in an appendix of the Orbix Administrator’s Guide. Most of the runtime configuration variables are for low-level parts of Orbix that users typically do not care about. However, some of the runtime configuration variables are of a higher-level nature and can be of interest when deploying an application. It is those interesting configuration variables that this section focuses on.

If you want to use some of these runtime configuration variables in a server application then a simple way to do so is to list the variables in the runtime_config_variables entry in an orbix_srv_admin description file, for example, payroll.des, and then run: 

orbix_srv_admin -register payroll.des

Alternatively, if you want to modify the runtime configuration variables of a server that is already registered then you can run: 

orbix_srv_admin -set_vars payroll.des

If you want to use some of these runtime configuration variables in a client application then a simple way to do so is to list the variables in the runtime_config_variables entry in an orbix_set_config_vars description file., for example, payroll_client.des, and then run: 

orbix_set_config_vars payroll_client.des

If an application is currently running when you update its configuration variables then you will have to stop it and re-start it for it to pick up the new runtime configuration values.

6.9.1  Size of the Thread Pool in Multi-threaded Servers

A server application has a pool of threads that are used for servicing incoming requests for servants in ORB_CTRL_MODEL (that is, multi-threaded) POAs. The thread pool has an initial size and can grow and shrink, subject to constraints expressed in some configuration variables.

The default configuration values for the thread pool means it initially contains 5 threads and it can to grow infinitely large (under a heavy load). These default values are dangerous because although threads are cheap, they do consume some resources and an Orbix server that continuously adds threads to the pool will eventually run out of memory. Instead, you can safeguard the health of your server by specifying an upper bound on the size of the thread pool. You can do this as shown in the example below: 

set runtime_config_variables {
    long    thread_pool:high_water_mark   "10"
    long    thread_pool:low_water_mark    "10"
    long    thread_pool:initial_threads   "10"
    long    thread_pool:max_queue_size    "500"
}

The above example configures the thread pool to be a fixed size, that it, it cannot grow or shrink. In general though, you may want the thread pool to be able to grow slightly under a heavy load and to later shrink when the server is under a lighter load. To do that, you need to understand the meaning of the configuration variables used. The initial_threads variable specifies the initial number of threads in the thread pool. The high_water_mark specifies the pool’s maximum size, and the low_water_mark specifies the pool’s minimum size. If the all the threads in the pool are busy and the pool cannot grow then an incoming request will be put into a queue where it will wait until one of the threads in the thread pool becomes free. The maximum size of this queue is specified by max_queue_size.

The default value of high_water_mark is -1, which allows the thread pool to grown infinitely big (or until the server runs out of memory). The default value of low_water_mark is -1, which means that the thread pool will never shrink when the load on the server decreases. The default value of initial_threads is 5, which means that the thread pool initially contains 5 threads. The default value of max_queue_size is -1, which allows the queue to grow infinitely big (or until the server runs out of memory).

6.9.1.1  Warning for Java Users

In the C++ version of Orbix, all the threads in the thread-pool are available for servicing incoming requests. Unfortunately, the Java version of Orbix uses threads in the thread-pool not just to service incoming requests, but also for other Orbix-internal purposes, such as reading incoming messages from socket connections. This means that not all the threads in the thread pool are available for servicing requests. It also means that if you put a limit on the size of the thread pool in an Orbix/Java server then the server may hang under some circumstances. This is because it may use up all the threads in the thread pool for monitoring socket connections and not have any threads left over to service incoming requests or monitor a newly opened socket connection. For this reason, you are strongly advised to not impose an upper limit on the size of the thread pool in an Orbix/Java application. IONA plans to fix this mis-feature of Orbix/Java in a future release.

6.9.2  Specifying References for CORBA Services

When an application calls resolve_initial_references("NameService"), Orbix finds the Naming Service by retrieving a stringified object reference from a runtime configuration variable and calling string_to_object() on this stringified object reference. Orbix uses this technique to locate any service requested in a call to resolve_initial_references(). Sometimes, there may be several Naming Services installed in an organization. If your application is currently pointing to the “wrong” Naming Service (or some other CORBA Service such as, say, the Trading Service) then you can fix this by modifying your application’s configuration settings. You do this by obtaining a stringified object reference (or a corbaloc reference) for the “correct” Naming Service and then set a configuration entry as shown below: 

set runtime_config_variables {
    string  initial_references:NameService:reference     "IOR:..."
    string  initial_references:TradingService:reference  "IOR:..."
}

6.9.3  Loading Extra Plug-ins

Orbix is built using a micro-kernel, plug-in architecture, which means that the kernel (core) of Orbix is very small but it knows low to load additional functionality through “plug-ins”. A plug-in is implemented as a shared-library/DLL for C++ Orbix, or as a Java class for Java Orbix.

The plug-ins that are loaded into an application by default are shown below: 

set runtime_config_variables {
    list orb_plugins "local_log_stream,iiop_profile,giop,iiop"
}

The above example shows that commas separate the values in a list. The above example also illustrates that even basic functionality, such as the on-the-wire protocol stack (GIOP and IIOP), is implemented via plug-ins rather than being hard-coded into the core of Orbix. This flexibility is important because it makes it feasible to plug-in a different on-the-wire protocol, if the need ever arises.

Some plug-ins that you might need to load for some applications include:

local_log_stream
This plug-in is loaded by default. It allows Orbix-generated messages to be logged to standard error or to a file. This is discussed more in Section 6.9.4.
system_log_stream
If you load this plug-in then Orbix-generated messages will be written to syslog on UNIX machines, or to the event log on Windows machines. This is discussed more in Section 6.9.4.
ots
You will need to load this plug-in if your application makes use of the Object Transaction Service (OTS) CORBA Service. See the Orbix CORBA OTS Programmer’s Guide for more details.
shmiop
If a client and server both load this plug-in and if the client and server are running on the same computer then they can communicate through shared memory rather than through IIOP.
iiop_tls
TLS is the new name for Secure Sockets Layer (SSL) which is an encryption standard that is popular on the Internet. If you want secure communications between clients and servers then your applications should load this plug-in. See the Orbix SSL/TLS Guide for more details.
giop_snoop
This plug-in uses an interceptor to examine all the on-the-wire messages that an application sends or receives. This plug-in can print out diagnostics for each message, which can be a useful debugging aid. See Section 6.9.4 for more details.

Each plug-in that is loaded may have its own configuration variables. By convention, a plug-in called 1<name> uses configuration variables with names that have "plugins:<name>:" as a prefix. For example, configuration variables related to IIOP use "plugins:iiop:" as a prefix on their names. The use of such prefixes avoids name clashes of configuration variables. Orbix uses the terminology namespace to refer to a prefix that contains a ":" character.

You may be curious about how C++ Orbix knows which shared-library/DLL to load for a plug-in, or how Java Orbix knows which Java class to load for a plug-in. The answer is that C++ Orbix uses the variable "plugins:<name>:shlib_name" to determine the name of the shared library , and that Java Orbix uses the variable "plugins:<name>:ClassName" to determine the name of the Java class.

6.9.4  Controlling Diagnostic Messages

6.9.4.1  Controlling the Destination of Diagnostics

The CORBA specification does not standardize how a CORBA vendor product should generate diagnostic messages. Because of this, CORBA products generate diagnostic output in a product-specific way. Whenever Orbix generates a diagnostic message, it logs it by invoking a logging operation on all the objects of type IT_Logging::LogStream inside the application. This interface is documented in the Orbix Programmer’s Reference manual. If you want Orbix diagnostic messages to be logged to, say, a database then you could write an implementation of the IT_Logging::LogStream interface to do that.

Orbix provides two pre-written implementations of IT_Logging::LogStream, both of which are provided as plug-ins. If these plug-ins are loaded (see Section 6.9.3) then Orbix uses them for logging diagnostic information. These plug-ins are not mutually exclusive, so you can load neither of them, just one of them or both of them.

One of the logging plug-ins is called system_log_stream. If this plug-in is loaded then Orbix diagnostic messages are sent to the system log device. On UNIX, this is called syslog, whereas on Windows it is called the event log. This plug-in is not loaded by default.

The other logging plug-in is call local_log_stream. If this plug-in is loaded then Orbix diagnostic messages, by default, are written to standard error. However, you can redirect these messages to a file with the following runtime configuration variable: 

set runtime_config_variables {
    string  plugins:local_log_stream:filename   "/path/to/server.log"
}

If you do this then Orbix appends a date suffix (in the format ".DDMMYYYY") onto the end of the name of the log file. Rather than log all messages to this file, Orbix opens a new log file for each day. Thus, after a week of operation, an application would have 7 log files.

6.9.4.2  Log Filters

Another important part of controlling log messages is setting up filters that determine which messages are logged. The default filter is illustrated below: 

set runtime_config_variables {
    list    event_log:filters   "*=WARN+ERR+FATAL"
}

The Orbix runtime system is composed of various sub-systems. These have names like IT_CORE, IT_GIOP, IT_POA and so on. The "*" character is used as a wildcard to means all the sub-systems. For each sub-system, you can specify a list of severity levels. These have names like INFO, WARN, ERR and FATAL. The elements in the list of severity levels are separated by "+" characters. The above example (which is the default filter) causes Orbix to generate diagnostics for warnings, (non-fatal) errors and fatal errors. You can turn on all diagnostic messages with the following: 

set runtime_config_variables {
    list    event_log:filters   "*=*"
}

The final example, below, illustrates the syntax for selectively enabling different filters for different sub-systems: 

set runtime_config_variables {
    list event_log:filters "IT_GIOP=*,IT_CORE=FATAL,*=WARN+ERR+FATAL"
}

See the Orbix Administrator’s Guide for a full list of the names of both sub-systems and logging severity levels.

6.9.4.3  Obtaining Per-request Diagnostics

If you load the giop_snoop plug-in (See Section 6.9.3) then Orbix generates diagnostic messages for each message (such as requests and replies) that are sent and received by an application. The giop_snoop_README.txt file provided in the doc sub-directory of an Orbix installation contains full details on how to enable and use the the giop_snoop plug-in.

6.9.5  Avoiding POA name clashes

Each CORBA server can have POAs, and each POA has a name. The POAs are arranged in a hierarchy, and the fully-qualified name of a POA is expressed in the form: 

full/path/to/POA-name

This syntax is similar in concept to the syntax used to express the /full/path/to/a/file used in the UNIX file system, except that there is not a leading "/" when writing a POA’s full name.

Persistent POAs have to be registered with the IMR (locator daemon). When registering a persistent POA, you specify the orbname (conceptually, an application) with which the POA is associated. Transient POAs do not have to be registered, unless a transient POA is a parent (or ancestor) of a persistent POA.

Within an IMR, the full/path/to/POA-name entries must be unique for all the registered, persistent POAs. However, it is possible that two independently developed applications might have POAs with similar names. To resolve such clashes on the names of POA, Orbix allows a prefix to be applied to the names of POAs within an application. By registering different applications with different prefixes for their POAs, you can avoid POA name clashes. This prefix is obtained from the value of the plugins:poa:root_name configuration variable. If you are using the orbix_srv_admin utility then there is no need to explicitly set a value for this variable because orbix_srv_admin will do it for you automatically. The value that orbix_srv_admin assigns to this configuration variable is determined by the root_poa_name entry in the orbix_srv_admin description file. If you are using the orbix_set_config_vars utility then you should explicitly set a value for this variable if you want to avoid POA name clashes.

6.9.6  Recycling Connection Resources

When a client application communicates with objects in a server application, there will be a socket connection between the client and the server applications. Note that there will be one socket connection between a client and server, irrespective of how many objects the client is communicating with in the server. CORBA allows the socket connection between a client and a server to be closed if it is idle, that is, if there are no requests from the client currently being processed by the server. CORBA does not consider the closing of an idle socket connection to be an error condition. Rather, if an idle connection is closed then the client application will transparently re-open the connection if/when it makes another remote call to an object in a server. The Orbix terminology for the automatic closing of idle socket connections is Active Connection Management (ACM).

ACM is disabled by default, that is, the default behavior of Orbix is that it does not close idle socket connections. However, you can set some runtime configuration variables to enable ACM. This is illustrated by the example below: 

set runtime_config_variables {
    long  plugins:iiop:incoming_connections:soft_limit   "500"
    long  plugins:iiop:incoming_connections:hard_limit   "600"

    long  plugins:iiop:outgoing_connections:soft_limit   "-1"
    long  plugins:iiop:outgoing_connections:hard_limit   "-1"
}

The soft_limit variables specify the number of connections at which the Orbix runtime system (actually the IIOP plug-in) should begin closing connections. However, it may take the Orbix runtime system some time before it can find a connection that is idle. While one thread in the Orbix runtime system is searching for idle connections that it can close, more connections might be established/accepted by other threads. This is why it is necessary to also specify a hard_limit, which determines the maximum number of connections. Above this, new connection attempts will be rejected. You should always ensure that the hard_limit is greater than the soft_limit. Alternatively, you can set these values to -1, which is the default. Doing this instructs Orbix to not apply any limits.

As the above example illustrates, hard and soft limits can be specified for both incoming and outgoing connections. The concept of incoming and outgoing refers to the direction in which requests flow. Thus, a server application can place a limit on the number of connections from clients that it will keep open by specifying soft_limit and hard_limit values for the incoming connections.

It is common for many clients to connect to a single server, so specifying incoming connection limits on the server is important. However, it is very rare for one client application to open connections to many servers. Because of this, it is rarely necessary to specify limits on the outgoing connections.

The reason why the default values for connection limits is set to -1 is because there are no default values that would be suitable for all application loads on all operating systems. Instead, a user (or system administrator) should consult the documentation for their operating system to determine how many socket connections the operating system can support before performance is degraded and then ensure that the Orbix limits are set below this point. Also, if there will be many applications (each of which might use socket connections) running on the same machine then you should scale back the Orbix connection limits even further so that a heavily loaded Orbix server does not cause other applications to become starved of socket connections.

6.9.6.1  Recycling Connections for Other Protocols

The example in Section 6.9.6 showed how to set up ACM for the IIOP protocol. If your server uses the shmiop or iiop_tls plug-ins then you can enable ACM for these protocols by replacing iiop in the name of the configuration variables with shmiop or iiop_tls. This is illustrated in the example below: 

set runtime_config_variables {
    long  plugins:iiop_tls:incoming_connections:soft_limit   "500"
    long  plugins:iiop_tls:incoming_connections:hard_limit   "600"

    long  plugins:iiop_tls:outgoing_connections:soft_limit   "-1"
    long  plugins:iiop_tls:outgoing_connections:hard_limit   "-1"
}
1
Orbix uses the terminology location domain instead of Implementation Repository. An overview of the IMR/location domain is provided in Section 6.2.
2
Many executables supplied with Orbix start with the prefix "it". This prefix is an acronym for IONA Technologies, and is used to prevent namespace pollution of executables installed on a computer.
3
Tcl automatically converts strings to numbers on an as-needed basis in order to perform arithmetic operations, so treating all values as strings does not limit Tcl’s power. Once the string-to-integer conversion has been performed, the integer value is cached so future accesses of the value are faster.
4
The IOR of the Naming Service will actually contain the port of the IMR, so a client’s first invocation upon the Naming Service will actually be sent to the IMR. The IMR will then redirect the client to Naming Service’s actual port.
5
www.iona.com/support/articles/3757.360.xml
6
The iona_services.naming.<local-host-name> scope stores configuration information for the Naming Service that runs on the specified host.
Previous Up Next