TAO/orbsvcs/FT_Naming_Service/README

   1
   2
   3 This directory contains files that implement a server for the TAO
   4 FT Naming Service. The FT Naming Service supports a dual redundant
   5 scheme for fault tolerance and also implements a load balancing
   6 mechanism when objects are bound to an object group within a named
   7 element in the naming service.
   8
   9 How to Run the TAO FT Naming Service
  10 =================================
  11
  12 1. Syntax
  13
  14         % tao_ft_naming  [-ORBNameServicePort nsport]
  15                          [--primary]
  16                          [--backup]
  17                          [-b base_address]
  18                          [-d debug_flag]
  19                          [-m (1=enable multicast responses,0=disable(default)]
  20                          [-n number_of_threads]
  21                          [-c ft_naming_service_ior_file]
  22                          [-g ft_naming_manager_ior_file]
  23                          [-o this_servers_object_ref_ior_file]
  24                          [-r directory_for_naming_context_replication]
  25                          [-u directory_for_flat_file_persistence]
  26                          [-v directory_for_object_group_replication]
  27                          [-s context_size]
  28                          [-z time]
  29
  30 2. Optional Command-line Arguments
  31
  32         --primary
  33                 Start this FT Naming Server in the primary role for the
  34                 dual redundant replication scheme. The primary must be
  35                 started first and then the backup. If neither primary
  36                 nor backup options are supplied, the server will run
  37                 standalone without support for fault tolerance.
  38
  39         --backup
  40                 Start this FT Naming Service in the backup role for the
  41                 dual redundant replication scheme. The backup must be
  42                 started after the primary and will coordinate with the
  43                 primary to set up the notifications with the peer for
  44                 changes to the naming contexts and object groups.
  45
  46         -ORBNameServicePort nsport
  47                 Multicast port for listening for requests from clients
  48                 trying to bootstrap to a Naming Service through the
  49                 use of multicast.  This is only used when multicast
  50                 responding is enabled via '-m 1'.
  51
  52         -b base_address
  53                 The address used for memory mapping the file specified
  54                 with the "-f" option above.  The value supplied with
  55                 this option is only used when the Naming Service runs
  56                 in persistent mode, i.e., "-f" option is present.
  57
  58         -d
  59                Provides Naming Service specific debug information. By default
  60                no diagnostics are given.
  61
  62         -m <0|1>
  63                 TAO offers a simple, very non-standard method for
  64                 clients to discover the initial reference for the
  65                 Naming Service.  However, since it can be inadequate and cause
  66                 unexpected results if, for example, there are multiple
  67                 naming services running on the network, the DEFAULT
  68                 behavior is for the Naming Service to NOT RESPOND to
  69                 such multicast queries (use the Interoperable Naming
  70                 Service bootstrap options instead).  The multicast option
  71                 only works with for standalone servers and fault tolerance
  72                 will not be supported by the server when started with this
  73                 option.
  74
  75         -n number_of_threads
  76                 Specify a number of threads to be used to run the ORB.
  77                 Default is 1.
  78
  79         -c ns_ior_output_file
  80                 The name of the file, in which to store the IOR containing
  81                 the profiles for both this naming servers root naming
  82                 context and the peer naming service root naming context.
  83                 This option should only be used for the --backup naming
  84                 service.
  85
  86         -g nm_ior_output_file
  87                 The name of the file, in which to store the IOR containing
  88                 the profiles for both this naming manager and the peer naming
  89                 manager. This option should only be used for the --backup
  90                 naming service.
  91
  92         -h nm_ior_output_file
  93                 The name of the file, in wich to store the IOR of the
  94                 naming manager for just this service. This option can
  95                 be useful for testing.
  96
  97         -o ior_output_file
  98                 The name of the file, in which to store the IOR of the
  99                 root Naming Service context for just this server.  This
 100                 option is useful if you want to run the naming service
 101                 standalone, without the backup and need to obtain the
 102                 IOR of the root context implemented by this process.
 103
 104         -p pid_file_name
 105                 The name of the file, in which to store the process id
 106                 of the Naming Service server.
 107
 108         -s context_size
 109                 Size of the hash table allocated for the root Naming
 110                 Context (if one is created).  All contexts created
 111                 under the root will use the same size for their hash
 112                 tables.  The default is 1024.
 113
 114         -t time
 115                 How long (in seconds) the server should listen for
 116                 client requests before terminating.
 117
 118         -f persistence_file_name
 119                 The name of the file to use to store/retrieve
 120                 persistent state of the Naming Service.
 121
 122         -r directory
 123                Use redundant flat-file persistence; same as the -u option,
 124                except more than one instance of the TAO Naming Service server
 125                can run, each using the same set of disk files, to achieve a
 126                degree of fault tolerence (as long as directory is accessible
 127                to both servers). Make sure you start the --primary and --backup
 128                with the same directory so they will share the persistence
 129                directory.
 130
 131         -u directory
 132                Use a flat-file persistence implementation that stores object
 133                reference information in a file per context. Each context file
 134                is placed in the directory specified. This option can be used
 135                when running the FT Naming Service standalone - without
 136                fault tolerance/redundancy.
 137
 138         -v directory
 139                Use redundant flat-file persistence for naming contexts that
 140                are created within this server. Users can add object to the
 141                object group and bind the object group to a name within the
 142                naming service to obtain a load balancing capability.
 143                Make sure you start the --primary and --backup
 144                with the same directory so they will share the persistence
 145                directory.
 146
 147         -z time
 148                 A relative round trip timeout value (in seconds) that
 149                 the service should wait for when trying to progress an
 150                 operation through a federated naming context before
 151                 timing out and throwing a 'Cannot proceed' exception
 152                 to the client. If no value is set this will never occur.
 153
 154 3. Environment Variables
 155
 156         NameServicePort
 157                 Multicast port for listening for requests from clients
 158                 trying to bootstrap to a Naming Service through the
 159                 use of multicast.  This is only used when multicast
 160                 responding is enabled via '-m 1'.
 161
 162 4. Persistence
 163
 164         When running as a fault tolerant service, the TAO FT Naming Service
 165         persists the state of naming contexts and object groups to files.
 166         This allows the state to be restored when starting and
 167         restarting the naming service and allows for dual-redundant
 168         fault-tolerance capability.
 169
 170         1. If the specified persistence directories for naming context
 171            data and object group data do not exist, the server will exit.
 172
 173         2. When a file is successfully created or updated, a backup of
 174            the file is made.
 175
 176         3. If the specified file exists, it is read in and:
 177
 178                 a) If a field can not be properly read because the
 179                 data is corrupt, an attempt will be made to read from
 180                 the backup of the file.  (The data could be corrupt, for
 181                 example, if a server or host crashed in the middle of
 182                 writing a record to this file on a previous run.) If
 183                 the backup file can be read it will replace the
 184                 primary file. Because the state of the naming context
 185                 or object group reverted to an earlier state, a log
 186                 message is generated alerting that the backup is being
 187                 used.
 188
 189                 b) If the file is recognized and is ok, the state
 190                 stored in the file becomes the current state of the
 191                 Naming Service.
 192
 193 5. Implementation Policies
 194
 195         a. No support for BindingIterators
 196
 197                 With the use of redundancy between a pair of naming
 198                 servers, there is no way to guarantee that the context
 199                 structure being iterated on would remain consistent,
 200                 so the user must ensure that when invoking the list
 201                 operation that a 'how_many' value must be provided that
 202                 is sufficiently large to hold all returned bindings in
 203                 a BindingList with no BindingIterator being needed. If
 204                 the 'how_many' parameter is insufficiently large, the
 205                 FT Naming Service will throw a CORBA::NO_IMPLEMENT
 206                 exception.
 207
 208         b. Dealing with orphaned contexts
 209
 210                 This implementation of the Naming Service does not
 211                 include any form of 'garbage collection' for orphaned
 212                 naming contexts.  It is solely the responsibility of
 213                 clients to clean up after themselves and not leak
 214                 server resources.  All the resources, including
 215                 orphaned contexts, are released during the Naming
 216                 Server shutdown.
 217
 218 6. Clients: ways to bootstrap to the Naming Service:
 219
 220         There are several methods for a client to bootstrap to a
 221         Naming Service, i.e., there are several mechanisms
 222         <resolve_initial_references> can use when asked for
 223         "NameService".  In order of predictable behavior, they are:
 224
 225         1. Command-line options
 226
 227                 The "-ORBInitRef NameService=IOR:..." or environment
 228                 variable NameServiceIOR can be used on the client side
 229                 to specify the object that the call to
 230                 <resolve_initial_references> should return to the
 231                 client.  (On the server side, -c option can be used in
 232                 the backup Naming Service to write the ior).
 233
 234                 Example (Unix, same host):
 235
 236                         % $TAO_ROOT/orbsvcs/Naming_Service/Naming_Service
 237                           -r NameService -v ObjectGroups --primary
 238                         % $TAO_ROOT/orbsvcs/Naming_Service/Naming_Service
 239                           -r NameService -v ObjectGroups -c ns_ior_file --backup
 240                         % my_client -ORBInitRef NameService=file://ns_ior_file
 241
 242                         On the first line, we start the primary Naming
 243                         Service. On the second line we start the backup
 244                         Naming Service and output the multi-profile IOR to
 245                         to <ns_ior_file>.  On the third line, we start
 246                         some client, and specify the ior
 247                         <resolve_initial_references> should return for
 248                         the Naming Service in a file format.
 249
 250
 251 Troubleshooting
 252 ============================================
 253
 254 Q1. Error Message: "Invalid persistence directory" or "Invalid object
 255 group persistence directory"
 256
 257 A1. On starting, the error message "Invalid persistence directory"
 258 indicates that the supplied value for the -r option does not point
 259 to a directory that can be used to store the state of the naming contexts
 260 or object groups. Make sure that the provided directories exist and
 261 that they are write enabled.