diff options
Diffstat (limited to 'lib/orber/doc/src/ch_install.xml')
| -rw-r--r-- | lib/orber/doc/src/ch_install.xml | 1001 |
1 files changed, 0 insertions, 1001 deletions
diff --git a/lib/orber/doc/src/ch_install.xml b/lib/orber/doc/src/ch_install.xml deleted file mode 100644 index 65faa91ccf..0000000000 --- a/lib/orber/doc/src/ch_install.xml +++ /dev/null @@ -1,1001 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>1997</year><year>2017</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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="erl"> -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="erl"> -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="erl"> -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="erl"> -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="erl"> -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="erl"> -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="erl"> -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="erl"> -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="erl"> -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_out_ports_attempts</cell> - <cell align="left" valign="middle">integer() > 0</cell> - <cell align="left" valign="middle">1</cell> - </row> - <row> - <cell align="left" valign="middle">iiop_out_ports_random</cell> - <cell align="left" valign="middle">true | false</cell> - <cell align="left" valign="middle">false</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_options</cell> - <cell align="left" valign="middle">list()</cell> - <cell align="left" valign="middle">See the <seealso marker="ssl:ssl">SSL application</seealso> - for valid options.</cell> - </row> - <row> - <cell align="left" valign="middle">ssl_client_options</cell> - <cell align="left" valign="middle">list()</cell> - <cell align="left" valign="middle">See the <seealso marker="ssl:ssl">SSL application</seealso> - for valid options.</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_out_ports_random</em></tag> - <item>Requires that <c>iiop_out_ports</c> define a port range. If that is the - case Orber will select a port randomly from that sequence.</item> - <tag><em>iiop_out_ports_attempts</em></tag> - <item>Requires that <c>iiop_out_ports</c> define a port range. If so Orber will - accept a number of timeouts, defined by this parameter, when trying to connect - to another ORB.</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_options</em></tag> - <item>A list of the SSL options when Orber is the server. - In general it's just to remove the 'ssl_server_' prefix from the old options, - i.e. <c>ssl_server_verify</c> will just be <c>verify</c> in this option list. - See the <seealso marker="ssl:ssl">SSL application</seealso> for the correct list of possible - options and their values. - </item> - <tag><em>ssl_client_options</em></tag> - <item>A list of the SSL options when Orber is the client. - In general it's just to remove the <c>ssl_client_</c> prefix from the old options, - i.e. <c>ssl_client_depth</c> will just be <c>depth</c> in this option list. - See the <seealso marker="ssl:ssl">SSL application</seealso> for the correct list of possible - options and their values. - </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="erl"> -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="erl"> -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> - |