5 Installing Orber

5.1 Installation Process

This chapter describes how to install Orber in an Erlang Environment.

5.1.1 Preparation

To begin with, you must decide if you want to run Orber as a:

• Single node (non-distributed) - all communication with other Orber intsances and ORB's supplied by other vendors use the OMG GIOP protocol.


• Multi node (distributed) - all Orber nodes, within the same domain, communicate via the Erlang distribution protocol. For all other Orber instances, i.e. not part of the same domain, and ORB's supplied by other vendors, the OMG GIOP protocol is used.

Which approach to use is highly implementation specific, but a few things you should consider:

• All nodes within an Orber domain should have the same security level.


• If the capacity is greater than load (volume of traffic) a single-node Orber might be a good solution.


• In some cases the distributed system architecture requires a single-node Orber installation .


• A multi-node Orber makes it possible to load balance and create a more fault tolerant system. The Objects can also have a uniform view if you use distributed Mnesia tables.


• Since the GIOP protocol creates a larger overhead than the Erlang distribution protocol, the performance will be better when communicating with Objects within the same Orber domain compared with inter ORB communcation (GIOP).

You also have to decide if you want Orber to store internal data using disc_copies and/or ram_copies. Which storage type you should depends if/how you intend to use Mnesia in your application. If you intend to use disc_copies you must start with creating a Mnesia schema, which contain information about the location of the Erlang nodes where Orber is planned to be run. For more background information, see the Mnesia documentation.

In some cases it is absolutely necessary to change the default configuration of Orber. For example, if two Orber-ORB's shall be able to communicate via GIOP, they must have a unique domain domain. Consult the configuration settings section. If you encounter any problems; see the chapter about Debugging in this User's Guide.

5.1.2 Jump Start Orber

The easiest way to start Orber is to use orber:jump_start(Port), which start a single-node ORB with (most likely) a unique domain (i.e. "IP-number:Port"). This function may only be used during development and testing. For any other situation, install and start Orber as described in the following sections. The listen port, i.e. iiop_port configuration parameter, is set to the supplied Port.

How Orber is configured when using orber:jump_start(Port) may change at any time without warning. Hence, this operation must not be used in systems delivered to a customer.

5.1.3 Install Single Node Orber

Since a single node Orber communicate via the OMG GIOP protocol it is not necessary to start the Erlang distribution (i.e. using -name/-sname).

If we use ram_copies there is no need for creating a disc based schema. Simply use:

erl> mnesia:start().
erl> corba:orb_init([{domain, "MyRAMSingleNodeORB"}]).
erl> orber:install([node()], [{ifr_storage_type, ram_copies}]).
erl> orber:start().
      

If you installation requires disc_copies you must begin with creating a Mnesia schema. Otherwise, the installation is similar to a RAM installation:

erl> mnesia:create_schema([node()]).
erl> mnesia:start().
erl> corba:orb_init([{domain, "MyDiscSingleNodeORB"}]).
erl> orber:install([node()], [{ifr_storage_type, disc_copies},
                              {nameservice_storage_type, disc_copies}]).
erl> orber:start().
      

You can still choose to store the IFR data as ram_copies, but then the data must be re-installed (i.e. invoke orber:install/2) if the node is restarted. Hence, since the IFR data is rather static you should use disc_copies. For more information see the orber section in the reference manual.

If you do not need to change Orber's configuration you can skip orb_init/1. But, you should at least set the IIOP timeout parameters.

When starting Orber as lightweight, mnesia and orber:install/* are not required. You must, however, use the configuration parameter lightweight.

5.1.4 Install RAM Based Multi Node Orber

Within a domain Orber uses the Erlang distribution protocol. Hence, you must start it first by, for example, using:

hostA> erl -sname nodeA
      

In this example, we assume that we want to use two nodes; nodeA and nodeB. Since Mnesia must know which other nodes should a part of the distribution we either need to add the Mnesia configuration parameter extra_db_nodes or use mnesia:change_config/2. To begin with, Mnesia must be started on all nodes before we can install Orber:

nodeA@hostA> mnesia:start().
nodeA@hostA> mnesia:change_config(extra_db_nodes, 
                                  [nodeA@hostA, nodeB@hostB]).
      

After that the above have been repeated on nodeB we must first make sure that both nodes will use the same domain name, then we can install Orber:

nodeA@hostA> corba:orb_init([{domain, "MyRAMMultiNodeORB"}]).
nodeA@hostA> orber:install([nodeA@hostA, nodeB@hostB],
                           [{ifr_storage_type, ram_copies}]).
nodeA@hostA> orber:start().
      

Note that you can only invoke orber:install/1/2 on one of the nodes. Now we can start Orber on the other node:

nodeB@hostB> corba:orb_init([{domain, "MyRAMMultiNodeORB"}]).
nodeB@hostB> orber:start().

      

5.1.5 Install Disc Based Multi Node Orber

As for RAM based multi-node Orber installations, the Erlang distribution must be started (e.g. erl -sname nodeA). The major difference is that when it is disc based a Mnesia schema must be created:

nodeA@hostA> mnesia:create_schema([nodeA@hostA, nodeB@hostB]).
nodeA@hostA> mnesia:start().
      

In this example, we assume that we want to use two nodes; nodeA and nodeB. Since it is not possible to create a schema on more than one node. Hence, all we have to do is to start Mnesia (i.e. invoke mnesia:start()) on nodeB.

After Mnesia have been started on all nodes, you must confirm that all nodes have the same domain name, then Orber is ready to be installed:

nodeA@hostA> corba:orb_init([{domain, "MyDiscMultiNodeORB"}]).
nodeA@hostA> orber:install([nodeA@hostA, nodeB@hostB],
                           [{ifr_storage_type, disc_copies}]).
nodeA@hostA> orber:start().
      

Note that you can only invoke orber:install/1/2 on one of the nodes. Now we can start Orber on the other node:

nodeB@hostB> corba:orb_init([{domain, "MyDiscMultiNodeORB"}]).
nodeB@hostB> orber:start().

      

5.1.6 Running Java clients against Orber.

If you intend to run Java clients and your Java ORB does not support the Interoperable Naming Service (INS), a specific

     <OTP_INSTALLPATH>/lib/orber-<current-version>/priv
        

must be added to your CLASSPATH variable to allow Orber support for the initial references. For more information about INS, see the Name Service chapter in this User's Guide.

5.2 Configuration

The following configuration parameters exist:

• domain - default is "ORBER". The value is a string. Since Orber domains must have unique names, communication will fail if two domains have the same name. The domain name MAY NOT contain ^G (i.e. \007).


• iiop_port - default 4001. The value is an integer greater than 0.
  Note:On a UNIX system it is preferable to have a IIOP port higher than 1023, since it is not recommended to run Erlang as a root user.


• iiop_out_ports - default 0 (i.e. use any available port). If set, Orber will only use the local ports within the interval when trying to connect to another ORB (Orber acts as a client ORB). If all ports are in use communication will fail. Hence, it is absolutely necessary to set iiop_connection_timeout as well. Otherwise, connections no longer in use will block further communication. If one use, for example, erl -orber iiop_out_ports "{5000,5020}", Orber will only use port 5000 to 5020 when connecting. SSL do not support this feature. Hence, one MAY NOT combine these settings.


• bootstrap_port - It is used for fetching initial service references and has the IIOP port as the default setting. The value is an integer greater than 0.


• ip_address - default is all interfaces. This option is used if orber only should listen on a specific ip interface on a multi-interface host. The value is the ip address as a string or a tuple of four integers.


• objectkeys_gc_time - default is infinity. This option should be set if objects are started using the option {persistent, true}. The value is integer() seconds.


• giop_version - default is IIOP 1.1. It is possible to IIOP Versions 1.0 or 1.2 as well, e.g., erl -orber giop_version "{1,2}"


• iiop_setup_connection_timeout - default is infinity. The value is an integer (seconds) or the atom infinity. This option is only valid for client-side connections. If this option is set, attempts to connect to other ORB's will timeout after the given time limit. Note, if the time limit is large the TCP protocol may timeout before the supplied value.


• iiop_connection_timeout - default is infinity. The value is an integer (timeout in seconds between 0 and 1000000) or the atom infinity. This option is only valid for client object connections, i.e., will have no effect on server connections. Setting this option will cause client connections to be terminated, if and only if, there are no pending requests. If there are a client still waiting for a reply, Orber will try again after the given seceonds have passed. The main purpose for this option is to reduce the number of open connections; it is, for example, not necessary to keep a connection, only used once a day, open at all time.


• iiop_timeout - default is infinity. The value is an integer (timeout in seconds between 0 and 1000000) or the atom infinity. This option is only valid on the client side. Setting this option, cause all intra-ORB requests to timeout and raise a system exception, e.g. TIMEOUT, if no replies are delivered within the given time limit.


• interceptors - if one set this parameter, e.g., erl -orber interceptors "{native, ['myInterceptor']}", Orber will use the supplied interceptor(s) for all inter-ORB communication. 'myInterceptor' is the module name of the interceptor. For more information, see the interceptor chapter in the User's Guide and the Reference Manual.


• lightweight - default is false. This option must be set if Orber is supposed to be started as lightweight. The value is a list of RemoteModifiers, equal to the orber:resolve_initial_references_remote/2 argument. The list must contain Orber nodes addresses, to which we have access and are not started as lightweight.


• orbInitRef - default is undefined. Setting this option, e.g., erl -orber orbInitRef [\"NameService=corbaloc::host.com/NameService\"], will alter the location from where corba:resolve_initial_references(Key) tries to find an object matching the given Key. The keys will also appear when invoking corba:list_initial_services(). This variable overrides orbDefaultInitRef


• orbDefaultInitRef - default is undefined. If a matching Key for orbInitRef is not found, and this variable is set, it determines the location from where orber:resolve_initial_references(Key) tries to find an object matching the given Key. Usage: erl -orber orbDefaultInitRef \"corbaloc::host.com\"


• orber_debug_level - default is 0 and the range is 0 to 10. Using level 10 is the most verbose configuration. This option will generate reports, using the error_logger, for abnormal situations. It is not recommended to use this option for delivered systems since some of the reports is not to be considered as errors. The main puropse is to assist during development.


• flags - no flags activated in the default case. The available configuration settings is described in Orber Environment Flags.

It is possible to invoke operations using the extra timeout parameter:

erl> module_interface(ObjRef, Timeout, ... Arguments ...).
erl> module_interface(ObjRef, ... Arguments ...).

The extra Timeout argument will override the configuration parameter iiop_timeout. It is, however, not possible to use infinity to override the Timeout parameter. The Timeout option is also valid for objects which resides within the same Orber domain .

The iiop_setup_connection_timeout, iiop_timeout and iiop_connection_timeout variables should be used. The specified values is implementation specific, i.e., WAN or LAN, but they should range from iiop_setup_connection_timeout to iiop_connection_timeout.

The following options are the possible configurations when using Orber with secure IIOP. Orber currently only supports security with the help of SSL and not SECIOP. To get more information about the SSL read the SSL application manual. The security chapter later in this manual describes how to get security in Orber and how the options are used.

• secure - default is no security. The values are currently just the atoms ssl and no.


• iiop_ssl_port - default 4002. If set, the value must be an integer greater than zero and not equal to iiop_port.


• ssl_server_cacertfile - the value is a file path to a server side CA certificate.


• ssl_server_certfile - the value is a file path to a server side certificate.


• ssl_server_verify - the value is an integer less or equal than two.


• ssl_server_depth - the value is an integer.


• ssl_server_password - the value is a server side key string.


• ssl_server_keyfile - the value is a file path to a server side key.


• ssl_server_ciphers - the value is a server side cipher string.


• ssl_server_cachetimeout - the value is a server side cache timeout integer. Default is infinity.


• ssl_client_cacertfile - the value is a file path to a client side CA certificate.


• ssl_client_certfile - the value is a file path to a client side certificate.


• ssl_client_verify - the value is an integer less or equal than two.


• ssl_client_depth - the value is an integer.


• ssl_client_password - the value is a client side key string.


• ssl_client_keyfile - the value is a file path to a client side key.


• ssl_client_ciphers - the value is a client side cipher string.


• ssl_client_cachetimeout - the value is a client side cache timeout integer. Default is infinity.

To change these settings in the configuration file, the -config flag must be added to the erl command. See the Reference Manual config(4) for further information. The values can also be sent separately as options to the Erlang node when it is started, see the Reference Manual erl(1) for further information.

5.2.1 Orber Environment Flags

The Environment Flags allows the user to activate debugging facilities or change Orber's behavior. The latter may result in that Orber is no longer compliant with the OMG standard, which may be necessary when communicating with a non-compliant ORB.

Orber Environment Flags

Hexadecimal Value	OMG Compliant	Description
0001	no	Exclude CodeSet Component
0002	yes	Local Typechecking
0004	yes	Use Host Name in IOR

Any combination of the flags above may be used and changes the behavior as follows:

• Exclude CodeSet Component - instruct Orber to exclude the CodeSet component in exported IOR:s. When activated, no negotiating regarding character and wide character conversions between the client and the server will occur. This flag will, most likely, cause problems if your IDL specification contains the datatypes wchar and/or wstring.


• Local Typechecking - If activated, parameters, replies and raised exceptions will be checked to ensure that the data is correct. If an error occurs, the error_logger is used to generate reports. One MAY NOT use this option for delivered systems due to the extra overhead. Since this option activates typechecking for all objects generated on the target node, it is also possible to use the option {local_typecheck, boolean()}, when invoking oe_create/2, oe_create_link/2, corba:create/4 or corba:create_link/4, to override the configuration parameter.


• Use Host Name in IOR - normally Orber inserts the IP-number in IOR:s when they are exported. In some cases, this will cause the clients to open two connections instead of one.