5 Installing Orber
5.1 Installation Process
This chapter describes how to install Orber in an Erlang Environment.
5.1.1 Preparation
Before beginning the installation process for Orber, a Mnesia database schema must exist. This schema will contain information about the location of the Erlang nodes where Orber is planned to be run.
The Mnesia schema can be created by calling the following code in an Erlang shell:
Mnesia:create_schema(NodeList)
NodeList
is the list of Erlang node names.5.1.2 Installing Orber
The next step is to actually install Orber. When the installation is completed Orber will automatically create a few Orber specific Mnesia tables and load them with data.
The installation process will differ slightly depending on whether Orber is running on one or many nodes or if Mnesia is currently running.
Functions to choose from are:
orber:install(NodeList)
.
orber:install(NodeList, Options)
.
Installation
Options
is a choice between multi-node or single node installation.
When starting Orber as lightweight, mnesia and
orber:install/*
are not required. You must, however, use the configuration parameterlightweight
.5.1.2.1 Single Node Installation
Single node (non-Distributed) installation means that Orber processes will be installed and started on only one node.
In this case, Orber still facilitates external communication with other ORBs through the IIOP protocol.
Single node installation of Orber is suitable in cases where:
- Capacity is greater than load (volume of traffic)
- Distributed system architecture requires an Orber installation on only one node.
Below, is an example of a one node installation where Mnesia is not installed. It is not necessary to have Mnesia running when installing Orber on a single node, as Orber will start Mnesia automatically.
Open an Erlang shell and install the application by typing:
1> mnesia:create_schema([]).2> orber:install([]).
In the above example the node list is empty, as the default option is the current node.
5.1.2.2 Multi-node installation
For a multi-node installation there are two extra steps. All nodes must be started and Mnesia must be running.
Below is an example of a multi-node installation where Mnesia is installed:
1> orber:install([a@machine1, b@machine2]).5.1.2.3 Running Java clients against Orber.
If you intend to run Java clients, a specific
<OTP_INSTALLPATH>/lib/orber-<current-version>/privmust be added to your CLASSPATH variable to allow Orber support for the initial references.
5.2 Configuration
The following configuration parameters exist:
- domain - default is "ORBER". The value is a string. As Orber domains must have unique names, problems can arise if two domains have the same name.
- iiop_port - default 4001. The value is an integer.
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.
- bootstrap_port - It is used for fetching initial service references and has the IIOP port as the default setting. The value is an integer.
- ip_address - default is all interfaces. This option is used if orber only should listen on a specific ip interface on a multiinterface host. The value is the ip address as a string or a tuple of four integers.
- objectkeys_gc_time - default is
infinity
. This option is should be set if objects are started using the option{persistent, true}
. The value is,integer()
, seconds. four integers.
- giop_version - default is IIOP 1.1. IIOP Version 1.0 is still usable but you have to this configuration variable, e.g.,
erl -orber giop_version "{1,0}"
- 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 the
COMM_FAILURE
system exception 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. 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 wherecorba:resolve_initial_references(Key)
tries to find an object matching the given Key. The keys will also appear when invokingcorba:list_initial_services()
. This variable overridesorbDefaultInitRef
- orbDefaultInitRef - default is undefined. If a matching Key for
orbInitRef
is not found, and this variable is set, it determines the location from whereorber: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.
IC supply the compile option
ic:gen(IdlFile, [{timeout,"module::interface"}])
, which allow the user to add an extra timeout parameter, e.g.,module_interface(ObjRef, Timeout, ... Arguments ...)
, instead ofmodule_interface(ObjRef, ... Arguments ...)
. If, a stub is compiled with the timeout option, the extra Timeout argument will override the configuration parameteriiop_timeout
. It is, however, not possible to useinfinity
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
andiiop_connection_timeout
variables should be used. The specified values is implementation specific, i.e., WAN or LAN, but they should range fromiiop_setup_connection_timeout
toiiop_connection_timeout
.IIOP communication only occurs between different Orber domains and therefore, if IIOP communication is required between two Orber domains, their domain names must be set to different values.
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.
- 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_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.
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.