[Ericsson AB]

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:

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

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.

Warning!

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.

Note!

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

It is essential that one configure Orber properly, to avoid, for example, malicious attacks and automatically terminate IIOP connections no longer in use. An easy way to extract information about Orber's configuration parameters is to invoke the operation orber:info/1/2. Orber offer the following configuration parameters:

Orber Configuration Parameters
Key Range Default
domain string() "ORBER"
iiop_port integer() >= 0 4001
nat_iiop_port integer() > 0 The same as iiop_port
iiop_out_ports 0 | {integer(),integer()} 0
iiop_max_fragments integer() > 0 | infinity infinity
iiop_max_in_requests integer() > 0 | infinity infinity
iiop_max_in_connections integer() > 0 infinity
iiop_backlog integer() > 0 5
iiop_packet_size integer() > 0 | infinity infinity
ip_address string() | {multiple, [string()]} All interfaces
ip_address_local string() Defined by the underlying system
nat_ip_address string() | {multiple, [string()]} The same as ip_address
objectkeys_gc_time integer() > 0 | infinity infinity
giop_version {1,0} | {1,1} | {1,2} {1,1}
iiop_setup_connection_timeout integer() > 0 | infinity infinity
iiop_connection_timeout integer() > 0 | infinity infinity
iiop_in_connection_timeout integer() > 0 | infinity infinity
iiop_timeout integer() > 0 | infinity infinity
interceptors {native, [atom()]} -
local_interceptors {native, [atom()]} -
lightweight [string()] | false false
orbInitRef [string()]| undefined undefined
orbDefaultInitRef string() | undefined undefined
orber_debug_level 0 - 10 0
flags integer() >= 0 0
iiop_acl [{atom(), string()}] | [{atom(), string(), [string()]}] []
secure no | ssl no
iiop_ssl_port integer() >= 0 4002
iiop_ssl_backlog integer() > 0 5
iiop_ssl_ip_address_local string() Defined by the underlying system
nat_iiop_ssl_port integer() > 0 The same as iiop_ssl_port
ssl_server_cacertfile string() -
ssl_server_certfile string() -
ssl_server_verify 0 | 1 | 2 -
ssl_server_depth integer() -
ssl_server_password string() -
ssl_server_keyfile string() -
ssl_server_ciphers string() -
ssl_server_cachetimeout integer() | infinity infinity
ssl_client_cacertfile string() -
ssl_client_certfile string() -
ssl_client_verify 0 | 1 | 2 -
ssl_client_depth integer() -
ssl_client_password string() -
ssl_client_keyfile string() -
ssl_client_ciphers string() -
ssl_client_cachetimeout integer() | infinity infinity


Comments on the table 'Orber Configuration Parameters':

domain
Since Orber domains, they are supposed to communicate via IIOP, 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
If set to 0 the OS will pick any vacant port.
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.
nat_iiop_port
See also Firewall Configuration.
iiop_out_ports
When set to 0 any available port will be used. If a range is specified, 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. If communicating via SSL, make sure you use a version that supports the local {port, Port} option. See also Firewall Configuration.
iiop_max_fragments
Limits the number of IIOP fragments allowed per request.
iiop_max_in_requests
Limits the number of concurrent incoming requests per incoming connection.
iiop_max_in_connections
Limits the number of concurrent incoming connnections.
iiop_backlog
Defines the maximum length the queue of pending incoming connections may grow to.
iiop_packet_size
Defines the maximum size of incoming requests. If this limit is exceeded, the connection is closed.
ip_address
This option is used if orber only should listen on a specific ip interface on a multi-interface host or if exported IOR:s should contain multiple components. The value is the IPv4 or IPv6 address as a string.
ip_address_local
This option defines the default local interface Orber will use when connecting to another ORB via IIOP, i.e., Orber act as the client side ORB. The value is a IPv4 or IPv6 address as a string. It is possible to override ip_address_local by defining iiop_acl or passing the Orber generic interface Context. If this option is not used, the underlying will choose which interface to use. For more information, see the Interface Configuration section.
nat_ip_address
The value is the ip address as a string (IPv4 or IPv6) or {multiple, IPList}. See also Firewall Configuration.
objectkeys_gc_time
This option should be set if objects are started using the option {persistent, true}. The value is integer() seconds.
giop_version
Defines the default GIOP protocol version.
iiop_setup_connection_timeout
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
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_in_connection_timeout
The same as for iiop_connection_timeout. The only difference is that this option only affects incoming connections (i.e. Orber act as server-side ORB.
iiop_timeout
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.
local_interceptors
If defined, its value will be used when activating local interceptors via Orber Environment Flags. If not defined, but the flag is set, Orber will use the value of the interceptors parameter.
lightweight
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
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
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
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 are activated in the default case. The available configuration settings are described in Orber Environment Flags.
iiop_acl
This option must be actived by setting Orber Environment Flags parameter. The value of this parameter shall be a list of [{Direction, Filter}] and/or [{Direction, Filter, [Interfaces]}]. The Direction, tcp_in, ssl_in, tcp_out or ssl_out, determines if the Access Control List (ACL) applies to incoming or outgoing connections and IIOP or IIOP over SSL. The Filter uses a extended format of Classless Inter Domain Routing (CIDR). For example, "123.123.123.10" limits the connection to that particular host, while "123.123.123.10/17" allows connections to or from any host equal to the 17 most significant bits. Orber also allow the user to specify a certain port or port range, for example, "123.123.123.10/17#4001" and "123.123.123.10/17#4001/5001" respectively. IPv4 or none compressed IPv6 strings are accepted.
The list of Interfaces, IPv4 or IPv6 strings, may only contain one address for outgoing connections. For incoming connections, the Interfaces list may contain several IP strings. If set for outgoing connections, and access is granted, Orber will use that local interface when connecting to the server-side ORB. For incoming connections, the client-side ORB is requried to use one of the listed interfaces locally. If it fail to do so, access will be denied. The module orber_acl provides operations for evaluating the access control for filters and addresses. See also the Interface Configuration and Firewall Configuration chapters.
secure
Determines the security mode Orber will use, which is either no if it is an insecure domain or the type of security mechanism used. Currently, per default, Orber is compliant with CSIv1 level 0, which means IIOP via SSL/TLS. The security chapter later in this manual describes how to get security in Orber and how the options are used.
iiop_ssl_port
If set, the value must be an integer greater than zero and not equal to iiop_port.
iiop_ssl_backlog
Defines the maximum length the queue of pending incoming connections may grow to.
iiop_ssl_ip_address_local
This option defines the default local interface Orber will use when connecting to another ORB via IIOP SSL, i.e., Orber act as the client side ORB. The value is a IPv4 or IPv6 address as a string. It is possible to override iiop_ssl_ip_address_local by defining iiop_acl or passing the Orber generic interface Context. If this option is not used, the underlying will choose which interface to use. For more information, see the Interface Configuration section.
nat_iiop_ssl_port
If set, the value must be an integer greater than zero.
ssl_server_cacertfile
the file path to a server side CA certificate.
ssl_server_certfile
The path to a file containing a chain of PEM encoded certificates.
ssl_server_verify
The type of verification used by SSL during authentication of the other peer for incoming calls.
ssl_server_depth
The SSL verification depth for outgoing calls.
ssl_server_password
The server side key string.
ssl_server_keyfile
The file path to a server side key.
ssl_server_ciphers
The server side cipher string.
ssl_server_cachetimeout
The server side cache timeout.
ssl_client_cacertfile
The file path to a client side CA certificate.
ssl_client_certfile
The path to a file containing a chain of PEM encoded certificates.
ssl_client_verify
The type of verification used by SSL during authentication of the other peer for outgoing calls.
ssl_client_depth
The SSL verification depth for incoming calls.
ssl_client_password
The client side key string.
ssl_client_keyfile
The file path to a client side key.
ssl_client_ciphers
The client side cipher string.
ssl_client_cachetimeout
The client side cache timeout.

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

erl> module_interface:function(ObjRef, Timeout, ..Arguments..).
erl> module_interface:function(ObjRef, [{timeout, Timeout}], ..Arguments..).
erl> module_interface:function(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, iiop_connection_timeout and iiop_in_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.

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
0008 yes Enable NAT
0020 yes Local Interceptors
0080 yes Light IFR
0100 yes Use IPv6
0200 yes EXIT Tolerance
0400 yes Enable Incoming ACL
0800 yes Enable Outgoing ACL
1000 yes Use Current Interface in IOR

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

Invoking the operation orber:info/1/2 will display the currently set flags in a readable way.

5.3 Firewall Configuration

Firewalls are used to protect objects from clients in other networks or sub-networks, but also to restrict which hosts internal objects may connect to (i.e. inbound protection and outbound protection). A firewall can limit access based on:

This section describes how to configure a Transport Level firewall. It must have prior knowledge of the source to destination mappings, and conceptually has a configuration table containing tuples of the form: ({inhost:inport}, {outhost:outport}). If there are no port restrictions it is rather easy to configure the firewall. Otherwise, we must consider the following alternatives:

Warning!

Using the option iiop_out_ports may result in that Orber runs out of valid ports numbers. For example, other applications may steal some of the ports or the number of concurrent outgoing connections to other ORBs may be higher than expected. To reduce, but not eliminate, the risk you should use iiop_connection_timeout.

Firewall configuration example:

# "Plain" IIOP
To: Orber-IPNo:(iiop_port)     From: ORB-IPNo:X
To: ORB-IPNo:Z                 From: Orber-IPNo:(iiop_out_ports | Any Port)

# IIOP via SSL
To: Orber-IPNo:(iiop_port)     From: ORB-IPNo:X
To: Orber-IPNo:(iiop_ssl_port) From: ORB-IPNo:Y
To: ORB-IPNo:Z                 From: Orber-IPNo:(iiop_out_ports | Any Port)
    

If the communication take place via a TCP Firewall with NAT (Network Address Translation), we must activate this behavior and define the external address and/or ports.

firewall_nat
TCP Firewall With NAT

Using NAT makes it possible to use different host data for different network domains. This way we can share Internet Protocol address resources or obscure resources. To enable this feature the Enable NAT flag must be set and nat_iiop_port, nat_iiop_ssl_port and nat_ip_address configured, which maps to iiop_port, iiop_ssl_port and ip_address respectively. Hence, the firewall must be configured to translate the external to the internal representation correctly.

If it is necessary to limit the access to an ORB within a secure network, but other applications running on the same host may not be blocked out, one can use a Application Level firewall or Orber Access Control List (ACL). The latter makes it possible for the user to define which hosts may communicate, either as server or client, with Orber. This is achieved by defining the configuration parameter iiop_acl. The Classless Inter Domain Routing (CIDR) Filter determines which peer interfaces and ports the other ORB may use.

Orber ACL Filters
Filter Peer Interface(s) Peer Port(s)
"10.1.1.1" 10.1.1.1 any
"10.1.1.1/8" 10.0.0.0-10.255.255.255 any
"10.1.1.1/8#4001" 10.0.0.0-10.255.255.255 4001
"10.1.1.1/8#4001/5001" 10.0.0.0-10.255.255.255 4001-5001

Orber ACL, also allows the user to define which local interface(s) may be used, but will not detect spoofing. The operation orber_acl:match/2/3 makes it easy to verify whether access would be granted or not. For example, if Orber would be started with the ACL [{tcp_out, "10.1.1.1/8#4001/5001"}], then orber_acl:match/2 would behave as follows:

erl> orber_acl:match({11,1,1,1}, tcp_out).
false

erl> orber_acl:match({10,1,1,1}, tcp_out).
true

erl> orber_acl:match({11,1,1,1}, tcp_out, true).
{false,[],0}

erl> orber_acl:match({10,1,1,1}, tcp_out, true).
{true,[],{4001,5001}}
    

Only if the returned boolean is true the extra return values makes a difference. In the example above, {true,[],{4001,5001}} means that Orber may connect to "10.1.1.1", using any local interface, if the server-side ORB listens for incoming connect requests on a port within the range 4001-5001. Note, invoking the orber_acl:match/2/3 operation, will not result in a connect attempt by Orber. The reason for this, is that this function may be used on a live node as well as in test environment. Hence, if a local interface is currently not available or no server-side ORB available via the given host/port(s), will not be detected by Orber.

5.4 Interface Configuration

In many cases it is sufficient to simply configre the underlying OS which local interfaces shall be used for all applications. But, in some cases it is required, due to, for example, the firewall configuration, that different local interfaces are used for different applications. Some times, it is even necessary to use a specific interface for a single CORBA object. This section describe how one can alter this in different ways.

The default behavior is that Orber lets the OS configuration decide which interface will be added in IOR:s exported to another ORB and the local interface used when connecting to another ORB (Orber act as client side ORB). The latter can be overridden by setting the configuration parameters iiop_ssl_ip_address_local and/or ip_address_local, which will affect IIOP via SSL and IIOP respectively. These parameters can be overridden by using the Orber generic interface Context or defining an ACL (Access Control List). The latter always takes precedence if a local interface is included (e.g. [{tcp_out, "10.0.0.0/8", ["10.0.0.1"]}]). If the interface is excluded (e.g. [{tcp_out, "10.0.0.0/8"}]), the interface chosen will, in the following order, be determined by #'IOP_ServiceContext'{}, ip_address_local/iiop_ssl_ip_address_local or the configuration of the underlying system.

Adding the interface context, for generated stubs/skeletons, is done in the following way:

Ctx = #'IOP_ServiceContext'{context_id = ?ORBER_GENERIC_CTX_ID, 
                            context_data = {interface, "10.0.0.1"}},
'CosNaming_NamingContext':resolve(NS, [{context, [Ctx]}], Name),
    

It is also possible to add the context to corba:string_to_object/2, corba:resolve_initial_references/2, corba:resolve_initial_references_remote/3, corba:list_initial_services_remote/2, corba_object:not_existent/2, corba_object:non_existent/2 and corba_object:is_a/3. The operations exported by corba_object are affected if the supplied IOR is external. The function corba:string_to_object/2 might require the interface context if a corbaloc or a corbaloc string is passed (See the INS chapter), while corba:resolve_initial_references_remote/3 and corba:list_initial_services_remote/2 always connect to another ORB and it might be necessary to add the context. The remaining corba operations are affected if calls are re-directed by setting the orbInitRef and/or orbDefaultInitRef configuration parameters. For more information, see the Reference Manual for each module.

Configuring which interface(s) that shall be used when exporting an IOR to another ORB, is determined by nat_ip_address, setting the flag 16#1000 and ip_address, in that order. Orber listens for incoming connections either via all interfaces or the interface defined by ip_address. It is also possible to add and remove extra listen interfaces by using orber:add_listen_interface/2/3 and orber:remove_listen_interface/1. In this case one should set the 16#1000 flag and avoid using NAT parameters.


Copyright © 1991-2006 Ericsson AB