aboutsummaryrefslogtreecommitdiffstats
path: root/lib/orber/doc/src/ch_install.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/orber/doc/src/ch_install.xml')
-rw-r--r--lib/orber/doc/src/ch_install.xml1071
1 files changed, 1071 insertions, 0 deletions
diff --git a/lib/orber/doc/src/ch_install.xml b/lib/orber/doc/src/ch_install.xml
new file mode 100644
index 0000000000..eee2b99c92
--- /dev/null
+++ b/lib/orber/doc/src/ch_install.xml
@@ -0,0 +1,1071 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>Installing Orber</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date>1998-09-28</date>
+ <rev></rev>
+ <file>ch_install.xml</file>
+ </header>
+
+ <section>
+ <title>Installation Process </title>
+ <p>This chapter describes how to install Orber in an Erlang
+ Environment.</p>
+
+ <section>
+ <title>Preparation</title>
+ <p>To begin with, you must decide if you want to run Orber as a:</p>
+ <list type="bulleted">
+ <item><em>Single node (non-distributed)</em> - all communication with other
+ Orber instances and ORB's supplied by other vendors use the OMG
+ GIOP protocol.</item>
+ <item><em>Multi node (distributed)</em> - all Orber nodes, within the same
+ <c>domain</c>, communicate via the Erlang distribution protocol.
+ For all other Orber instances, i.e. not part of the same <c>domain</c>,
+ and ORB's supplied by other vendors, the OMG GIOP protocol
+ is used.</item>
+ </list>
+ <p>Which approach to use is highly implementation specific, but a few
+ things you should consider:</p>
+ <list type="bulleted">
+ <item>All nodes within an Orber domain should have the same
+ security level.</item>
+ <item>If the capacity is greater than load (volume of traffic)
+ a single-node Orber might be a good solution.</item>
+ <item>In some cases the distributed system architecture requires a
+ single-node <term id="Orber installation"><termdef>is the structure of the ORB or ORBs as defined during the install process is called the "installation".</termdef></term>.</item>
+ <item>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.</item>
+ <item>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 communication (GIOP).</item>
+ </list>
+ <p>You also have to decide if you want Orber to store internal data using
+ <c>disc_copies</c> and/or <c>ram_copies</c>. Which storage type you should
+ depends if/how you intend to use Mnesia in your application. If you
+ intend to use <c>disc_copies</c> 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.</p>
+ <p>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 <c>domain</c> domain. Consult the
+ <seealso marker="ch_install#config">configuration settings</seealso>
+ section. If you encounter any problems; see the chapter about
+ <em>Debugging</em> in this User's Guide.</p>
+ </section>
+
+ <section>
+ <title>Jump Start Orber</title>
+ <p>The easiest way to start Orber is to use <c>orber:jump_start(Port)</c>,
+ 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.</p>
+ <warning>
+ <p>How Orber is configured when using <c>orber:jump_start(Port)</c>
+ may change at any time without warning. Hence, this operation must
+ not be used in systems delivered to a customer.</p>
+ </warning>
+ </section>
+
+ <section>
+ <title>Install Single Node Orber</title>
+ <p>Since a single node Orber communicate via the OMG GIOP protocol it is not
+ necessary to start the Erlang distribution (i.e. using <c>-name/-sname</c>).</p>
+ <p>If we use <c>ram_copies</c> there is no need for creating a disk based
+ schema. Simply use:</p>
+ <code type="none">
+erl> mnesia:start().
+erl> corba:orb_init([{domain, "MyRAMSingleNodeORB"}]).
+erl> orber:install([node()], [{ifr_storage_type, ram_copies}]).
+erl> orber:start().
+ </code>
+ <p>If you installation requires <c>disc_copies</c> you must begin with
+ creating a Mnesia schema. Otherwise, the installation is similar
+ to a RAM installation:</p>
+ <code type="none">
+erl> mnesia:create_schema([node()]).
+erl> mnesia:start().
+erl> corba:orb_init([{domain, "MyDiskSingleNodeORB"}]).
+erl> orber:install([node()], [{ifr_storage_type, disc_copies},
+ {nameservice_storage_type, disc_copies}]).
+erl> orber:start().
+ </code>
+ <p>You can still choose to store the IFR data as ram_copies, but then
+ the data must be re-installed (i.e. invoke <c>orber:install/2</c>)
+ if the node is restarted. Hence, since the IFR data is rather static
+ you should use <c>disc_copies</c>. For more information see the
+ <c>orber</c> section in the reference manual.</p>
+ <p>If you do not need to change Orber's configuration you can skip
+ <seealso marker="corba">orb_init/1</seealso>.
+ But, you <em>should</em> at least set the IIOP timeout parameters.</p>
+ </section>
+
+ <section>
+ <title>Install RAM Based Multi Node Orber</title>
+ <p>Within a domain Orber uses the Erlang distribution protocol. Hence, you
+ <em>must</em> start it first by, for example, using:</p>
+ <code type="none">
+hostA> erl -sname nodeA
+ </code>
+ <p>In this example, we assume that we want to use two nodes; <c>nodeA</c> and
+ <c>nodeB</c>. Since Mnesia must know which other nodes should a part
+ of the distribution we either need to add the Mnesia configuration
+ parameter <c>extra_db_nodes</c> or use <c>mnesia:change_config/2</c>. To
+ begin with, Mnesia must be started on all nodes before we can install
+ Orber:</p>
+ <code type="none">
+nodeA@hostA> mnesia:start().
+nodeA@hostA> mnesia:change_config(extra_db_nodes,
+ [nodeA@hostA, nodeB@hostB]).
+ </code>
+ <p>After that the above have been repeated on <c>nodeB</c> we must
+ first make sure that both nodes will use the same domain name, then
+ we can install Orber:</p>
+ <code type="none">
+nodeA@hostA> corba:orb_init([{domain, "MyRAMMultiNodeORB"}]).
+nodeA@hostA> orber:install([nodeA@hostA, nodeB@hostB],
+ [{ifr_storage_type, ram_copies}]).
+nodeA@hostA> orber:start().
+ </code>
+ <p>Note that you can only invoke <c>orber:install/1/2</c> on one of the
+ nodes. Now we can start Orber on the other node:</p>
+ <code type="none">
+nodeB@hostB> corba:orb_init([{domain, "MyRAMMultiNodeORB"}]).
+nodeB@hostB> orber:start().
+ </code>
+ </section>
+
+ <section>
+ <title>Install Disk Based Multi Node Orber</title>
+ <p>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 disk based a Mnesia schema must be created:</p>
+ <code type="none">
+nodeA@hostA> mnesia:create_schema([nodeA@hostA, nodeB@hostB]).
+nodeA@hostA> mnesia:start().
+ </code>
+ <p>In this example, we assume that we want to use two nodes; <c>nodeA</c> and
+ <c>nodeB</c>. 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
+ <c>mnesia:start()</c>) on <c>nodeB</c>.</p>
+ <p>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:</p>
+ <code type="none">
+nodeA@hostA> corba:orb_init([{domain, "MyDiskMultiNodeORB"}]).
+nodeA@hostA> orber:install([nodeA@hostA, nodeB@hostB],
+ [{ifr_storage_type, disc_copies}]).
+nodeA@hostA> orber:start().
+ </code>
+ <p>Note that you can only invoke <c>orber:install/1/2</c> on one of the
+ nodes. Now we can start Orber on the other node:</p>
+ <code type="none">
+nodeB@hostB> corba:orb_init([{domain, "MyDiskMultiNodeORB"}]).
+nodeB@hostB> orber:start().
+ </code>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Configuration</title>
+ <marker id="config"></marker>
+ <p>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
+ <seealso marker="orber">orber:info/1/2</seealso>.
+ Orber offer the following configuration parameters:</p>
+ <table>
+ <row>
+ <cell align="center" valign="middle"><em>Key</em></cell>
+ <cell align="center" valign="middle"><em>Range</em></cell>
+ <cell align="center" valign="middle"><em>Default</em></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">domain</cell>
+ <cell align="left" valign="middle">string()</cell>
+ <cell align="left" valign="middle">"ORBER"</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_port</cell>
+ <cell align="left" valign="middle">integer() >= 0</cell>
+ <cell align="left" valign="middle">4001</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">nat_iiop_port</cell>
+ <cell align="left" valign="middle">integer() > 0 | {local, integer(), [{integer(), integer()}]}</cell>
+ <cell align="left" valign="middle">The same as <c>iiop_port</c></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_out_ports</cell>
+ <cell align="left" valign="middle">0 | {integer(),integer()}</cell>
+ <cell align="left" valign="middle">0</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_max_fragments</cell>
+ <cell align="left" valign="middle">integer() > 0 | infinity</cell>
+ <cell align="left" valign="middle">infinity</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_max_in_requests</cell>
+ <cell align="left" valign="middle">integer() > 0 | infinity</cell>
+ <cell align="left" valign="middle">infinity</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_max_in_connections</cell>
+ <cell align="left" valign="middle">integer() > 0</cell>
+ <cell align="left" valign="middle">infinity</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_backlog</cell>
+ <cell align="left" valign="middle">integer() > 0</cell>
+ <cell align="left" valign="middle">5</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_packet_size</cell>
+ <cell align="left" valign="middle">integer() > 0 | infinity</cell>
+ <cell align="left" valign="middle">infinity</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ip_address</cell>
+ <cell align="left" valign="middle">string() | {multiple, [string()]}</cell>
+ <cell align="left" valign="middle">All interfaces</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ip_address_local</cell>
+ <cell align="left" valign="middle">string()</cell>
+ <cell align="left" valign="middle">Defined by the underlying system</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">nat_ip_address</cell>
+ <cell align="left" valign="middle">string() | {multiple, [string()]} | {local, string(), [{string(), string()}]}</cell>
+ <cell align="left" valign="middle">The same as <c>ip_address</c></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">objectkeys_gc_time</cell>
+ <cell align="left" valign="middle">integer() > 0 | infinity</cell>
+ <cell align="left" valign="middle">infinity</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">giop_version</cell>
+ <cell align="left" valign="middle">{1,0} | {1,1} | {1,2}</cell>
+ <cell align="left" valign="middle">{1,1}</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_setup_connection_timeout</cell>
+ <cell align="left" valign="middle">integer() > 0 | infinity</cell>
+ <cell align="left" valign="middle">infinity</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_connection_timeout</cell>
+ <cell align="left" valign="middle">integer() > 0 | infinity</cell>
+ <cell align="left" valign="middle">infinity</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_in_connection_timeout</cell>
+ <cell align="left" valign="middle">integer() > 0 | infinity</cell>
+ <cell align="left" valign="middle">infinity</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_out_keepalive</cell>
+ <cell align="left" valign="middle">true | false</cell>
+ <cell align="left" valign="middle">false</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_in_keepalive</cell>
+ <cell align="left" valign="middle">true | false</cell>
+ <cell align="left" valign="middle">false</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_timeout</cell>
+ <cell align="left" valign="middle">integer() > 0 | infinity</cell>
+ <cell align="left" valign="middle">infinity</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">interceptors</cell>
+ <cell align="left" valign="middle">{native, [atom()]}</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">local_interceptors</cell>
+ <cell align="left" valign="middle">{native, [atom()]}</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">orbInitRef</cell>
+ <cell align="left" valign="middle">[string()] | undefined</cell>
+ <cell align="left" valign="middle">undefined</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">orbDefaultInitRef</cell>
+ <cell align="left" valign="middle">string() | undefined</cell>
+ <cell align="left" valign="middle">undefined</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">orber_debug_level</cell>
+ <cell align="left" valign="middle">0 - 10</cell>
+ <cell align="left" valign="middle">0</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">flags</cell>
+ <cell align="left" valign="middle">integer() >= 0</cell>
+ <cell align="left" valign="middle">0</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_acl</cell>
+ <cell align="left" valign="middle">[{atom(), string()}] | [{atom(), string(), [string()]}]</cell>
+ <cell align="left" valign="middle">[]</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">secure</cell>
+ <cell align="left" valign="middle">no | ssl</cell>
+ <cell align="left" valign="middle">no</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_generation</cell>
+ <cell align="left" valign="middle">2 | 3</cell>
+ <cell align="left" valign="middle">2</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_ssl_port</cell>
+ <cell align="left" valign="middle">integer() >= 0</cell>
+ <cell align="left" valign="middle">4002</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_ssl_accept_timeout</cell>
+ <cell align="left" valign="middle">integer() > 0 | infinity</cell>
+ <cell align="left" valign="middle">infinity</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_ssl_backlog</cell>
+ <cell align="left" valign="middle">integer() > 0</cell>
+ <cell align="left" valign="middle">5</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_ssl_ip_address_local</cell>
+ <cell align="left" valign="middle">string()</cell>
+ <cell align="left" valign="middle">Defined by the underlying system</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">nat_iiop_ssl_port</cell>
+ <cell align="left" valign="middle">integer() > 0 | {local, integer(), [{integer(), integer()}]}</cell>
+ <cell align="left" valign="middle">The same as <c>iiop_ssl_port</c></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_server_cacertfile</cell>
+ <cell align="left" valign="middle">string()</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_server_certfile</cell>
+ <cell align="left" valign="middle">string()</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_server_verify</cell>
+ <cell align="left" valign="middle">0 | 1 | 2</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_server_depth</cell>
+ <cell align="left" valign="middle">integer()</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_server_password</cell>
+ <cell align="left" valign="middle">string()</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_server_keyfile</cell>
+ <cell align="left" valign="middle">string()</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_server_ciphers</cell>
+ <cell align="left" valign="middle">string()</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_server_cachetimeout</cell>
+ <cell align="left" valign="middle">integer() | infinity</cell>
+ <cell align="left" valign="middle">infinity</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_client_cacertfile</cell>
+ <cell align="left" valign="middle">string()</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_client_certfile</cell>
+ <cell align="left" valign="middle">string()</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_client_verify</cell>
+ <cell align="left" valign="middle">0 | 1 | 2</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_client_depth</cell>
+ <cell align="left" valign="middle">integer()</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_client_password</cell>
+ <cell align="left" valign="middle">string()</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_client_keyfile</cell>
+ <cell align="left" valign="middle">string()</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_client_ciphers</cell>
+ <cell align="left" valign="middle">string()</cell>
+ <cell align="left" valign="middle">-</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">ssl_client_cachetimeout</cell>
+ <cell align="left" valign="middle">integer() | infinity</cell>
+ <cell align="left" valign="middle">infinity</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_ssl_out_keepalive</cell>
+ <cell align="left" valign="middle">true | false</cell>
+ <cell align="left" valign="middle">false</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">iiop_ssl_in_keepalive</cell>
+ <cell align="left" valign="middle">true | false</cell>
+ <cell align="left" valign="middle">false</cell>
+ </row>
+ <tcaption>Orber Configuration Parameters</tcaption>
+ </table>
+ <br></br>
+ <br></br>
+ <p><em>Comments on the table 'Orber Configuration Parameters':</em></p>
+ <taglist>
+ <tag><em>domain</em></tag>
+ <item>Since Orber domains, they are supposed to communicate via IIOP,
+ <em>MUST</em> have unique names, communication will
+ fail if two domains have the same name. The domain name <em>MAY NOT</em>
+ contain <c>^G</c> (i.e. <c>\\007</c>).</item>
+ <tag><em>iiop_port</em></tag>
+ <item>If set to 0 the OS will pick any vacant port.
+ <br></br>
+<em>Note:</em>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.</item>
+ <tag><em>nat_iiop_port</em></tag>
+ <item>The value is either an integer or <c>{local, DefaultNATPort, [{Port, NATPort}]}</c>. See also
+ <seealso marker="ch_install#firewall">Firewall Configuration</seealso>.</item>
+ <tag><em>iiop_out_ports</em></tag>
+ <item>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 <em>absolutely necessary</em> to
+ set <c>iiop_connection_timeout</c> as well. Otherwise, connections
+ no longer in use will block further communication. If one use, for
+ example, <c>erl -orber iiop_out_ports "{5000,5020}"</c>, Orber
+ will only use port 5000 to 5020 when connecting.
+ If communicating via SSL, make sure you use a version that supports
+ the local <c>{port, Port}</c> option. See also
+ <seealso marker="ch_install#firewall">Firewall Configuration</seealso>.</item>
+ <tag><em>iiop_max_fragments</em></tag>
+ <item>Limits the number of IIOP fragments allowed per request.</item>
+ <tag><em>iiop_max_in_requests</em></tag>
+ <item>Limits the number of concurrent incoming requests per incoming connection.</item>
+ <tag><em>iiop_max_in_connections</em></tag>
+ <item>Limits the number of concurrent incoming connections.</item>
+ <tag><em>iiop_backlog</em></tag>
+ <item>Defines the maximum length the queue of pending incoming
+ connections may grow to.</item>
+ <tag><em>iiop_packet_size</em></tag>
+ <item>Defines the maximum size of incoming requests.
+ If this limit is exceeded, the connection is closed.</item>
+ <tag><em>ip_address</em></tag>
+ <item>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 or <c>{multiple, IPList}</c>.
+ The latter requires that the object is available via the all IP addresses
+ found in the list.</item>
+ <tag><em>ip_address_local</em></tag>
+ <item>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 <c>ip_address_local</c> by defining
+ <c>iiop_acl</c> or passing the Orber generic <c>interface</c> Context.
+ If this option is not used, the underlying OS will choose which interface to
+ use. For more information, see the
+ <seealso marker="ch_install#interfaces">Interface Configuration</seealso>
+ section.</item>
+ <tag><em>nat_ip_address</em></tag>
+ <item>The value is the ip address as
+ a string (IPv4 or IPv6), <c>{multiple, IPList}</c> or
+ <c>{local, DefaultNATIPAddress, [{IPAddress, NATIPAddress}]}</c>. See also
+ <seealso marker="ch_install#firewall">Firewall Configuration</seealso>.</item>
+ <tag><em>objectkeys_gc_time</em></tag>
+ <item>This option should be set if objects are started
+ using the option <c>{persistent, true}</c>.
+ The value is <c>integer()</c> seconds.</item>
+ <tag><em>giop_version</em></tag>
+ <item>Defines the default GIOP protocol version.</item>
+ <tag><em>iiop_setup_connection_timeout</em></tag>
+ <item>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.</item>
+ <tag><em>iiop_connection_timeout</em></tag>
+ <item>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 seconds 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.</item>
+ <tag><em>iiop_in_connection_timeout</em></tag>
+ <item>The same as for <c>iiop_connection_timeout</c>. The only difference is
+ that this option only affects incoming connections (i.e. Orber act as
+ server-side ORB).</item>
+ <tag><em>iiop_out_keepalive</em></tag>
+ <item>Enables periodic transmission on a connected socket, when no other
+ data is being exchanged. If the other end does not respond, the
+ connection is considered broken and will be terminated.
+ When enabled the SO_KEEPALIVE socket level option is set.</item>
+ <tag><em>iiop_in_keepalive</em></tag>
+ <item>The same as for <c>iiop_out_keepalive</c>. The only difference is
+ that this option only affects incoming connections.</item>
+ <tag><em>iiop_timeout</em></tag>
+ <item>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. <c>TIMEOUT</c>, if no replies are delivered
+ within the given time limit.</item>
+ <tag><em>interceptors</em></tag>
+ <item>If one set this parameter, e.g.,
+ <c>erl -orber interceptors "{native, ['myInterceptor']}"</c>,
+ Orber will use the supplied interceptor(s) for all inter-ORB
+ communication. <c>'myInterceptor'</c> is the module name of the
+ interceptor. For more information, see the interceptor chapter
+ in the User's Guide and the Reference Manual.</item>
+ <tag><em>local_interceptors</em></tag>
+ <item>If defined, its value will be
+ used when activating local interceptors via
+ <seealso marker="ch_install#flags">Orber Environment Flags</seealso>.
+ If not defined, but the flag is set, Orber will use the value of
+ the <c>interceptors</c> parameter.</item>
+ <tag><em>orbInitRef</em></tag>
+ <item>Setting this option, e.g.,
+ <c>erl -orber orbInitRef [\\"NameService=corbaloc::host.com/NameService\\"]</c>,
+ will alter the location from where <c>corba:resolve_initial_references(Key)</c>
+ tries to find an object matching the given Key. The keys will also appear when
+ invoking <c>corba:list_initial_services()</c>. This variable overrides
+ <c>orbDefaultInitRef</c></item>
+ <tag><em>orbDefaultInitRef</em></tag>
+ <item>If a matching Key for <c>orbInitRef</c> is not
+ found, and this variable is set, it determines the location from where
+ <c>orber:resolve_initial_references(Key)</c> tries to find an object
+ matching the given Key. Usage:
+ <c>erl -orber orbDefaultInitRef \\"corbaloc::host.com\\"</c>.</item>
+ <tag><em>orber_debug_level</em></tag>
+ <item>The range is 0 to 10.
+ Using level 10 is the most verbose configuration.
+ This option will generate reports, using the <c>error_logger</c>,
+ 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 purpose is to assist during development.</item>
+ <tag><em>flags</em></tag>
+ <item>No flags are activated in the default case.
+ The available configuration settings are described in
+ <seealso marker="ch_install#flags">Orber Environment Flags</seealso>.</item>
+ <tag><em>iiop_acl</em></tag>
+ <item>This option must be activated by setting
+ <seealso marker="ch_install#flags">Orber Environment Flags</seealso> parameter.
+ The value of this parameter shall be a list of <c>[{Direction, Filter}]</c>
+ and/or <c>[{Direction, Filter, [Interfaces]}]</c>. The <c>Direction</c>,
+ <c>tcp_in</c>, <c>ssl_in</c>, <c>tcp_out</c> or <c>ssl_out</c>, determines if
+ the Access Control List (ACL) applies to incoming or outgoing connections
+ and IIOP or IIOP over SSL. The <c>Filter</c> uses a extended format of
+ Classless Inter Domain Routing (CIDR). For example, <c>"123.123.123.10"</c> limits
+ the connection to that particular host, while <c>"123.123.123.10/17"</c> 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,
+ <c>"123.123.123.10/17#4001"</c> and <c>"123.123.123.10/17#4001/5001"</c>
+ respectively. IPv4 or none compressed IPv6 strings are accepted. <br></br>
+
+ The list of <c>Interfaces</c>, IPv4 or IPv6 strings, may only contain
+ <em>one</em> address for outgoing connections. For incoming connections,
+ the <c>Interfaces</c> 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 required to use one of the listed interfaces locally.
+ If it fail to do so, access will be denied. The module
+ <seealso marker="orber_acl">orber_acl</seealso> provides operations for
+ evaluating the access control for filters and addresses. See also the
+ <seealso marker="ch_install#interfaces">Interface Configuration</seealso>
+ and
+ <seealso marker="ch_install#firewall">Firewall Configuration</seealso>
+ chapters.</item>
+ <tag><em>secure</em></tag>
+ <item>Determines the security mode Orber will use, which is either
+ <c>no</c> if it is an insecure domain or the type of security
+ mechanism used. Currently, per default, Orber is compliant with
+ <c>CSIv1</c> 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.</item>
+ <tag><em>ssl_generation</em></tag>
+ <item>Defines which SSL version, i.e. available API, is installed. The
+ default value, <c>2</c>, refers to SSL-3.1 or later, but earlier than SSL-4.0.
+ If set to <c>3</c> SSL-4.0, or later, must be available. Currently it not possible
+ to use <c>1</c>, it is only reserved for future use.</item>
+ <tag><em>iiop_ssl_port</em></tag>
+ <item>If set, the value must be an
+ integer greater than zero and not equal to <em>iiop_port</em>.</item>
+ <tag><em>iiop_ssl_accept_timeout</em></tag>
+ <item>The value is an integer (timeout in seconds) or the atom infinity and
+ determine how long the SSL handshake may take. This option should
+ be set to avoid if a client never initiate the handshake.</item>
+ <tag><em>iiop_ssl_backlog</em></tag>
+ <item>Defines the maximum length the queue of pending incoming
+ connections may grow to.</item>
+ <tag><em>iiop_ssl_ip_address_local</em></tag>
+ <item>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 <c>iiop_ssl_ip_address_local</c> by defining
+ <c>iiop_acl</c> or passing the Orber generic <c>interface</c> Context.
+ If this option is not used, the underlying OS will choose which interface to
+ use. For more information, see the
+ <seealso marker="ch_install#interfaces">Interface Configuration</seealso>
+ section.</item>
+ <tag><em>nat_iiop_ssl_port</em></tag>
+ <item>If set, the value must be an integer greater than zero or
+ <c>{local, DefaultNATPort, [{Port, NATPort}]}</c>. See also
+ <seealso marker="ch_install#firewall">Firewall Configuration</seealso>.</item>
+ <tag><em>ssl_server_cacertfile</em></tag>
+ <item>the file path to a server side CA certificate.</item>
+ <tag><em>ssl_server_certfile</em></tag>
+ <item>The path to a file containing a chain of PEM encoded certificates.</item>
+ <tag><em>ssl_server_verify</em></tag>
+ <item>The type of verification used by SSL during authentication of the
+ other peer for incoming calls.</item>
+ <tag><em>ssl_server_depth</em></tag>
+ <item>The SSL verification depth for outgoing calls.</item>
+ <tag><em>ssl_server_password</em></tag>
+ <item>The server side key string.</item>
+ <tag><em>ssl_server_keyfile</em></tag>
+ <item>The file path to a server side key.</item>
+ <tag><em>ssl_server_ciphers</em></tag>
+ <item>The server side cipher string.</item>
+ <tag><em>ssl_server_cachetimeout</em></tag>
+ <item>The server side cache timeout.</item>
+ <tag><em>ssl_client_cacertfile</em></tag>
+ <item>The file path to a client side CA certificate.</item>
+ <tag><em>ssl_client_certfile</em></tag>
+ <item>The path to a file containing a chain of PEM encoded certificates.</item>
+ <tag><em>ssl_client_verify</em></tag>
+ <item>The type of verification used by SSL during authentication of the
+ other peer for outgoing calls.</item>
+ <tag><em>ssl_client_depth</em></tag>
+ <item>The SSL verification depth for incoming calls.</item>
+ <tag><em>ssl_client_password</em></tag>
+ <item>The client side key string.</item>
+ <tag><em>ssl_client_keyfile</em></tag>
+ <item>The file path to a client side key.</item>
+ <tag><em>ssl_client_ciphers</em></tag>
+ <item>The client side cipher string.</item>
+ <tag><em>ssl_client_cachetimeout</em></tag>
+ <item>The client side cache timeout.</item>
+ <tag><em>iiop_ssl_out_keepalive</em></tag>
+ <item>Enables periodic transmission on a connected socket, when no other
+ data is being exchanged. If the other end does not respond, the
+ connection is considered broken and will be terminated.
+ When enabled the SO_KEEPALIVE socket level option is set. Requires that
+ the installed SSL version support the <em>keepalive</em> option
+ and that the <em>ssl_generation</em> points to this version.</item>
+ <tag><em>iiop_ssl_in_keepalive</em></tag>
+ <item>The same as for <c>iiop_ssl_out_keepalive</c>. The only difference is
+ that this option only affects incoming connections.</item>
+ </taglist>
+ <p>It is possible to invoke operations using the extra timeout parameter:</p>
+ <pre>
+erl> module_interface:function(ObjRef, Timeout, ..Arguments..).
+erl> module_interface:function(ObjRef, [{timeout, Timeout}], ..Arguments..).
+erl> module_interface:function(ObjRef, ..Arguments..). </pre>
+ <p>The extra Timeout argument will override the configuration parameter
+ <c>iiop_timeout</c>. It is, however, not possible to use <c>infinity</c>
+ to override the Timeout parameter. The Timeout option is also valid for
+ objects which resides within the same <term id="Orber domain"><termdef>A domain containing several Erlang nodes, which are communicating by using the Erlang internal format. An Orber domain looks as one ORB from the environment.</termdef></term>.</p>
+ <p>The <c>iiop_setup_connection_timeout</c>, <c>iiop_timeout</c>,
+ <c>iiop_connection_timeout</c> and <c>iiop_in_connection_timeout</c>
+ variables should be used. The specified values is implementation specific,
+ i.e., WAN or LAN, but they should range from
+ <c>iiop_setup_connection_timeout</c> to <c>iiop_connection_timeout</c>.</p>
+ <p>To change these settings in the configuration file, the
+ <c>-config</c> flag must be added to the erl command. See the
+ Reference Manual
+ <em>config(4)</em> for further information. The values can also
+ be sent separately as
+ options to the Erlang node when it is started, see the Reference
+ Manual
+ <em>erl(1)</em> for further information. </p>
+
+ <section>
+ <marker id="flags"></marker>
+ <title>Orber Environment Flags</title>
+ <p>The <c>Environment Flags</c> 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.</p>
+ <table>
+ <row>
+ <cell align="left" valign="middle"><em>Hexadecimal Value</em></cell>
+ <cell align="left" valign="middle"><em>OMG Compliant</em></cell>
+ <cell align="left" valign="middle"><em>Description</em></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">0001</cell>
+ <cell align="left" valign="middle">no</cell>
+ <cell align="left" valign="middle">Exclude CodeSet Component</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">0002</cell>
+ <cell align="left" valign="middle">yes</cell>
+ <cell align="left" valign="middle">Local Typechecking</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">0004</cell>
+ <cell align="left" valign="middle">yes</cell>
+ <cell align="left" valign="middle">Use Host Name in IOR</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">0008</cell>
+ <cell align="left" valign="middle">yes</cell>
+ <cell align="left" valign="middle">Enable NAT</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">0020</cell>
+ <cell align="left" valign="middle">yes</cell>
+ <cell align="left" valign="middle">Local Interceptors</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">0080</cell>
+ <cell align="left" valign="middle">yes</cell>
+ <cell align="left" valign="middle">Light IFR</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">0100</cell>
+ <cell align="left" valign="middle">yes</cell>
+ <cell align="left" valign="middle">Use IPv6</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">0200</cell>
+ <cell align="left" valign="middle">yes</cell>
+ <cell align="left" valign="middle">EXIT Tolerance</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">0400</cell>
+ <cell align="left" valign="middle">yes</cell>
+ <cell align="left" valign="middle">Enable Incoming ACL</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">0800</cell>
+ <cell align="left" valign="middle">yes</cell>
+ <cell align="left" valign="middle">Enable Outgoing ACL</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">1000</cell>
+ <cell align="left" valign="middle">yes</cell>
+ <cell align="left" valign="middle">Use Current Interface in IOR</cell>
+ </row>
+ <tcaption>Orber Environment Flags</tcaption>
+ </table>
+ <p>Any combination of the flags above may be used and changes the
+ behavior as follows:</p>
+ <list type="bulleted">
+ <item><em>Exclude CodeSet Component</em> - 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 data types wchar and/or wstring.</item>
+ <item><em>Local Typechecking</em> -
+ If activated, parameters, replies and raised exceptions
+ will be checked to ensure that the data is correct. If an error
+ occurs, the <c>error_logger</c> is used to generate reports.
+ One <em>MAY NOT</em> 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 <c>{local_typecheck, boolean()}</c>, when
+ invoking <c>oe_create/2</c>, <c>oe_create_link/2</c>,
+ <c>corba:create/4</c> or <c>corba:create_link/4</c>, to override
+ the configuration parameter.</item>
+ <item><em>Use Host Name in IOR</em> - 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.</item>
+ <item><em>Enable NAT</em> - if this flag is set, it is possible to use
+ the NAT (Network Address Translation) configuration parameters
+ (<c>nat_iiop_port</c>, <c>nat_iiop_ssl_port</c> and
+ <c>nat_ip_address</c>).</item>
+ <item><em>Local Interceptors</em> - use interceptors for local
+ invocations.</item>
+ <item><em>Light IFR</em> - if the IFR is not explicitly used and this
+ flag is set, Orber will use a minimal IFR to reduce memory usage
+ and installation time.</item>
+ <item><em>Use IPv6</em> - when this option is activated, Orber will use
+ <c>IPv6</c> for inter-ORB communication.</item>
+ <item><em>EXIT Tolerance</em> - servers will survive even though the
+ call-back module caused an EXIT.</item>
+ <item><em>Enable Incoming ACL</em> - activates access control for incoming
+ connections.</item>
+ <item><em>Enable Outgoing ACL</em> - activates access control for outgoing
+ connections.</item>
+ <item><em>Use Current Interface in IOR</em> - when set, Orber will add
+ the interface the request came via to exported local IOR:s.</item>
+ </list>
+ <p>Invoking the operation
+ <seealso marker="orber">orber:info/1/2</seealso> will display the currently
+ set flags in a readable way.</p>
+ </section>
+ </section>
+
+ <section>
+ <title>Firewall Configuration</title>
+ <marker id="firewall"></marker>
+ <p>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. <c>inbound protection</c> and <c>outbound protection</c>). A firewall
+ can limit access based on:</p>
+ <list type="bulleted">
+ <item><em>Transport Level</em> - performs access control decisions based on
+ address information in TCP headers.</item>
+ <item><em>Application Level</em> - understands GIOP messages and the specific
+ transport level inter-ORB Protocol supported e.g. IIOP.</item>
+ </list>
+ <p>This section describes how to configure a <c>Transport Level</c> firewall. It
+ must have prior knowledge of the source to destination mappings, and
+ conceptually has a configuration table containing tuples of the form:
+ <c>({inhost:inport}, {outhost:outport})</c>. If there are no port restrictions
+ it is rather easy to configure the firewall. Otherwise, we must consider the
+ following alternatives:</p>
+ <list type="bulleted">
+ <item><em>Incoming Requests</em> - Orber only uses the port-numbers specified
+ by the configuration parameters <em>iiop_port</em> and
+ <em>iiop_ssl_port</em>. Other ORB's may use several ports but it should
+ be possible to change this behavior. Consult the other ORBs
+ documentation.</item>
+ <item><em>Outgoing Requests</em> - Most ORB's, Orber included,
+ ask the OS to supply a vacant local port when connecting to the
+ server-side ORB. It is possible to change this behavior when using
+ Orber (i.e. set the configuration parameter <em>iiop_out_ports</em>).</item>
+ </list>
+ <warning>
+ <p>Using the option <c>iiop_out_ports</c> 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
+ <c>iiop_connection_timeout</c>.</p>
+ </warning>
+ <p>Firewall configuration example:</p>
+ <pre>
+# "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)
+ </pre>
+ <p>If the communication take place via a
+ <seealso marker="ch_install#firewall_nat">TCP Firewall with NAT</seealso>
+ (Network Address Translation), we must activate this behavior and define
+ the external address and/or ports.</p>
+ <marker id="firewall_nat"></marker>
+ <image file="firewall_nat.gif">
+ <icaption>
+TCP Firewall With NAT</icaption>
+ </image>
+ <p>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
+ <seealso marker="ch_install#flags">Enable NAT</seealso> flag must be set and
+ <c>nat_iiop_port</c>, <c>nat_iiop_ssl_port</c> and <c>nat_ip_address</c>
+ configured, which maps to <c>iiop_port</c>, <c>iiop_ssl_port</c> and
+ <c>ip_address</c> respectively. Hence, the firewall must be configured to
+ translate the external to the internal representation correctly. If these NAT parameters
+ are assigned a single port number or IP address, only those will be used when
+ an IOR is exported to another ORB. When <c>ip_address</c> is set to
+ <c>{multiple, [IPAddress]}</c>, <c>nat_ip_address</c> should be configured in the same
+ way, so that each NAT IP address can be translated to a valid address by the firewall.
+ If objects are supposed to be accessible via different interfaces and port, see also
+ <seealso marker="ch_install#interfaces">Interface Configuration</seealso>,
+ the options <c>{local, DefaultNATIPAddress, [{IPAddress, NATIPAddress}]}</c> and/or
+ <c>{local, DefaultNATPort, [{Port, NATPort}]}</c> shall be used. The default NAT IP address
+ and port, should be translated to the value of <c>ip_address_local</c> and the default
+ listen port by the firewall. If the IP address and/or port is not found in the list,
+ the default values will be inserted in the IOR. The firewall must be able to translate
+ these correctly.</p>
+ <p>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 <em>Application Level</em> 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
+ <seealso marker="ch_install#config">iiop_acl</seealso>. The Classless Inter
+ Domain Routing (CIDR) <c>Filter</c> determines which peer interfaces and
+ ports the other ORB may use.</p>
+ <table>
+ <row>
+ <cell align="left" valign="middle"><em>Filter</em></cell>
+ <cell align="left" valign="middle"><em>Peer Interface(s)</em></cell>
+ <cell align="left" valign="middle"><em>Peer Port(s)</em></cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">"10.1.1.1"</cell>
+ <cell align="left" valign="middle">10.1.1.1</cell>
+ <cell align="left" valign="middle">any</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">"10.1.1.1/8"</cell>
+ <cell align="left" valign="middle">10.0.0.0-10.255.255.255</cell>
+ <cell align="left" valign="middle">any</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">"10.1.1.1/8#4001"</cell>
+ <cell align="left" valign="middle">10.0.0.0-10.255.255.255</cell>
+ <cell align="left" valign="middle">4001</cell>
+ </row>
+ <row>
+ <cell align="left" valign="middle">"10.1.1.1/8#4001/5001"</cell>
+ <cell align="left" valign="middle">10.0.0.0-10.255.255.255</cell>
+ <cell align="left" valign="middle">4001-5001</cell>
+ </row>
+ <tcaption>Orber ACL Filters</tcaption>
+ </table>
+ <p>Orber ACL, also allows the user to define which local interface(s) may be used,
+ but will not detect <c>spoofing</c>. The operation
+ <seealso marker="orber_acl">orber_acl:match/2/3</seealso> makes it easy to
+ verify whether access would be granted or not. For example, if Orber would
+ be started with the ACL <c>[{tcp_out, "10.1.1.1/8#4001/5001"}]</c>, then
+ <c>orber_acl:match/2</c> would behave as follows:</p>
+ <code type="none">
+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}}
+ </code>
+ <p>Only if the returned boolean is true the extra return values makes a
+ difference. In the example above, <c>{true,[],{4001,5001}}</c> means that
+ Orber may connect to <c>"10.1.1.1"</c>, 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 <c>orber_acl:match/2/3</c>
+ 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.</p>
+ </section>
+
+ <section>
+ <title>Interface Configuration</title>
+ <marker id="interfaces"></marker>
+ <p>In many cases it is sufficient to simply configure 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.</p>
+ <p>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 <c>iiop_ssl_ip_address_local</c>
+ and/or <c>ip_address_local</c>, which will affect IIOP via SSL and IIOP
+ respectively. These parameters can be overridden by using the Orber generic
+ <c>interface</c> Context or defining an ACL (Access Control List). The latter
+ always takes precedence if a local interface is included (e.g.
+ <c>[{tcp_out, "10.0.0.0/8", ["10.0.0.1"]}]</c>). If the interface is excluded
+ (e.g. <c>[{tcp_out, "10.0.0.0/8"}]</c>), the interface chosen will, in the following
+ order, be determined by
+ <c>#'IOP_ServiceContext'{}</c>, <c>ip_address_local/iiop_ssl_ip_address_local</c> or
+ the configuration of the underlying system.</p>
+ <p>Adding the interface context, for generated stubs/skeletons, is done in the
+ following way:</p>
+ <code type="none">
+Ctx = #'IOP_ServiceContext'{context_id = ?ORBER_GENERIC_CTX_ID,
+ context_data = {interface, "10.0.0.1"}},
+'CosNaming_NamingContext':resolve(NS, [{context, [Ctx]}], Name),
+ </code>
+ <p>It is also possible to add the context to
+ <c>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</c> and <c>corba_object:is_a/3</c>.
+ The operations exported by <c>corba_object</c> are affected
+ if the supplied IOR is external. The function <c>corba:string_to_object/2</c>
+ might require the interface context if a <c>corbaloc</c> or a <c>corbaloc</c>
+ string is passed (See the
+ <seealso marker="ch_naming_service#interop_ns">INS</seealso> chapter),
+ while <c>corba:resolve_initial_references_remote/3</c> and
+ <c>corba:list_initial_services_remote/2</c> always connect to another ORB and
+ it might be necessary to add the context.
+ The remaining <c>corba</c> operations are affected if calls are re-directed
+ by setting the <c>orbInitRef</c> and/or <c>orbDefaultInitRef</c> configuration
+ parameters. For more information, see the Reference Manual for each module.</p>
+ <p>Configuring which interface(s) that shall be used when exporting an IOR to
+ another ORB, is determined by <c>nat_ip_address</c>, setting the flag
+ <seealso marker="ch_install#flags">16#1000</seealso>
+ and <c>ip_address</c>, in that order. Orber listens for incoming connections
+ either via all interfaces or the interface defined by <c>ip_address</c>. It is
+ also possible to add and remove extra listen interfaces by using
+ <c>orber:add_listen_interface/2/3</c> and <c>orber:remove_listen_interface/1</c>.
+ In this case one should set the 16#1000 flag and, if necessary, set the
+ configuration parameters
+ <c>{local, DefaultNATIPAddress, [{IPAddress, NATIPAddress}]}</c> and/or
+ <c>{local, DefaultNATPort, [{Port, NATPort}]}</c>.</p>
+ </section>
+</chapter>
+