TAO/orbsvcs/Naming_Service/README

   1 This directory contains files that implement a server for the TAO
   2 Naming Service.  In addition, it contains files that run the TAO
   3 Naming Service as a Windows NT Service.  Both of these services are
   4 described below.
   5
   6 How to Run the TAO Naming Service
   7 =================================
   8
   9 The following describes how to run the TAO Naming Service.
  10
  11 1. Syntax
  12
  13         % tao_cosnaming  [-ORBNameServicePort nsport]
  14                          [-b base_address]
  15                          [-d ]
  16                          [-f persistence_file_name]
  17                          [-m (1=enable multicast responses,0=disable(default)]
  18                          [-n number_of_threads]
  19                          [-o ior_output_file]
  20                          [-p pid_file_name]
  21                          [-r directory]
  22                          [-s context_size]
  23                          [-t time]
  24                          [-u directory]
  25                          [-z time]
  26
  27
  28 2. Optional Command-line Arguments
  29
  30         -ORBNameServicePort nsport
  31                 Multicast port for listening for requests from clients
  32                 trying to bootstrap to a Naming Service through the
  33                 use of multicast.  This is only used when multicast
  34                 responding is enabled via '-m 1'.
  35
  36         -b base_address
  37                 The address used for memory mapping the file specified
  38                 with the "-f" option above.  The value supplied with
  39                 this option is only used when the Naming Service runs
  40                 in persistent mode, i.e., "-f" option is present.
  41
  42         -d
  43                Provides Naming Service specific debug information. By default
  44                no diagnostics are given.
  45
  46         -f persistence_file_name
  47                 The name of the file to use to store/retrieve
  48                 persistent state of the Naming Service.  Without this
  49                 option, Naming Service is started in non-persistent
  50                 mode.
  51
  52         -m <0|1>
  53                 TAO offers a simple, very non-standard method for
  54                 clients to discover the initial reference for the
  55                 Naming Service.  However, since it can be inadequate and cause
  56                 unexpected results if, for example, there are multiple
  57                 naming services running on the network, the DEFAULT
  58                 behavior is for the Naming Service to NOT RESPOND to
  59                 such multicast queries (use the Interoperable Naming
  60                 Service bootstrap options instead).
  61
  62         -n number_of_threads
  63                 Specify a number of threads to be used to run the ORB.
  64                 Default is 1.
  65
  66         -o ior_output_file
  67                 The name of the file, in which to store the IOR of the
  68                 root Naming Service context.
  69
  70         -p pid_file_name
  71                 The name of the file, in which to store the process id
  72                 of the Naming Service server.
  73
  74         -s context_size
  75                 Size of the hash table allocated for the root Naming
  76                 Context (if one is created).  All contexts created
  77                 under the root will use the same size for their hash
  78                 tables.  The default is 1024.
  79
  80         -t time
  81                 How long (in seconds) the server should listen for
  82                 client requests before terminating.
  83
  84         -r directory
  85                Use redundant flat-file persistence; same as the -u option,
  86                except more than one instance of the TAO Naming Service server
  87                can run, each using the same set of disk files, to achieve a
  88                degree of fault tolerence (as long as directory is accessible
  89                to both servers).
  90
  91         -u directory
  92                Use a flat-file persistence implementation that stores object
  93                reference information in a file per context. Each context file
  94                is placed in the directory specified.
  95
  96         -z time
  97                 A relative round trip timeout value (in seconds) that
  98                 the service should wait for when trying to progress an
  99                 operation through a federated naming context before
 100                 timing out and throwing a 'Cannot proceed' exception
 101                 to the client. If no value is set this will never occur.
 102
 103 3. Environment Variables
 104
 105         NameServicePort
 106                 Multicast port for listening for requests from clients
 107                 trying to bootstrap to a Naming Service through the
 108                 use of multicast.  This is only used when multicast
 109                 responding is enabled via '-m 1'.
 110
 111 4. Persistence
 112
 113         TAO Naming Service has an optional persistence capability.  By
 114         default, the Naming Service is started in a non-persistent
 115         mode.  Supplying "-f" command-line option to the server causes
 116         a persistent version of the Naming Service to run.
 117
 118         The file specified with the "-f" option is used to store the
 119         persistent state of the Naming Service, i.e., all Naming
 120         Contexts and their bindings.  When "-f" option is specified:
 121
 122         1. If the specified file does not exist, it is created and
 123            used to store the state of the Naming Service.  An initial
 124            (root) Naming Context is also created.
 125
 126         2. If the specified file exists, it is scanned and:
 127
 128                 a) If any inconsistency is detected in the stored
 129                 state, or the file is not recognized by the Naming
 130                 Service, the server exits.  (This may happen, for
 131                 example, if a server or host crashed in the middle of
 132                 writing a record to this file on a previous run).  A
 133                 noncorrupted version of the file must be used instead.
 134
 135                 b) If the file is recognized and is ok, the state
 136                 stored in the file becomes the current state of the
 137                 Naming Service.
 138
 139         Internally, TAO uses memory mapped file to implement
 140         persistence feature of the Naming Service.  A default memory
 141         address (ACE_DEFAULT_BASE_ADDR) is used for mapping the file.
 142         Alternate mapping address can be specified at compile-time by
 143         redefining TAO_NAMING_BASE_ADDR in tao/orbconf.h.  Alternate
 144         mapping address can also be specified at run-time
 145         with the "-b" command-line option, which takes precedence over
 146         TAO_NAMING_BASE_ADDR definition.
 147         NOTE: Naming Service stores absolute pointers in its
 148         memory-mapped file.  Therefore, it is important to use the
 149         same mapping address on each run for the same persistence file.
 150
 151
 152 5. Implementation Policies
 153
 154         a. Destroying Binding Iterators
 155
 156                 A binding iterator is destroyed when client invokes
 157                 <destroy> operation either on the iterator itself or
 158                 on the naming context it is iterating over.  In both
 159                 cases, subsequent calls on the binding iterator object
 160                 will cause OBJECT_NOT_EXIST exception.
 161
 162         b. Dealing with orphaned contexts
 163
 164                 This implementation of the Naming Service does not
 165                 include any form of 'garbage collection' for orphaned
 166                 naming contexts.  It is solely the responsibility of
 167                 clients to clean up after themselves and not leak
 168                 server resources.  All the resources, including
 169                 orphaned contexts, are released during the Naming
 170                 Server shutdown.
 171
 172 6. Clients: ways to bootstrap to the Naming Service:
 173
 174         There are several methods for a client to bootstrap to a
 175         Naming Service, i.e., there are several mechanisms
 176         <resolve_initial_references> can use when asked for
 177         "NameService".  In order of predictable behavior, they are:
 178
 179         1. Command-line options
 180
 181                 The "-ORBInitRef NameService=IOR:..." or environment
 182                 variable NameServiceIOR can be used on the client side
 183                 to specify the object that the call to
 184                 <resolve_initial_references> should return to the
 185                 client.  (On the server side, -o option can be used to
 186                 get the ior).
 187
 188                 Example (Unix, same host):
 189
 190                         % $TAO_ROOT/orbsvcs/Naming_Service/tao_cosnaming -o ior_file
 191                         % my_client -ORBInitRef NameService=file://ior_file
 192
 193                         On the first line, we start the Naming
 194                         Service, and output its ior to <ior_file>.  On
 195                         the second line, we start some client, and
 196                         specify the ior <resolve_initial_references>
 197                         should return for the Naming Service in a file
 198                         format.
 199
 200         2. Interoperable Naming Service.
 201
 202                 TAO implements the standard CORBA Interoperable Naming
 203                 Service (ING).  Therefore, most initialization options
 204                 provided by INS can be used to bootstrap to the Naming
 205                 Service (see TAO's release notes for the status of INS
 206                 implementation).
 207
 208         3. Multicast
 209
 210                 When started with the "respond to multicast queries"
 211                 option turned on ('-m 1'), clients can use IP
 212                 multicast to query for a Naming Service, and this
 213                 instance will respond. TAO Naming Server is listening
 214                 for client multicast requests on a specified port.  On
 215                 the client side, <resolve_initial_references> sends
 216                 out a multicast request on the network, trying to
 217                 locate a Naming Service.  When a Naming Server
 218                 receives a multicast request from a client, it replies
 219                 to the sender with the ior of its root Naming Context.
 220                 Note, the port used for this bootstrapping process,
 221                 i.e., 'multicast port', has nothing to do with the ORB
 222                 port used for CORBA communication.  Other points worth
 223                 mentioning:
 224
 225                 - A client and a server will only click through this
 226                   multicast protocol if they are using the same
 227                   multicast port.  For both client and server
 228                   -ORBnameserviceport command-line option and
 229                   NameServicePort environment variable can be used to
 230                   specify the multicast port to use.  If none is
 231                   specified, the default port is used.  (The ability
 232                   to specify multicast ports can be used to match
 233                   certain clients with certain Naming Servers, when
 234                   there are more than one Naming Server running on the
 235                   network).
 236
 237                 - If there are several Naming Servers running on the
 238                   network, each listening on the same port for
 239                   multicast requests, each will send a reply to a
 240                   client's request.  The client's orb will use the
 241                   first response it receives, so the Naming Service
 242                   will, in fact, be selected at random.
 243
 244                 Since this mechanism is proprietary to TAO (i.e.,
 245                 non-standard), it only works when both client and
 246                 server are written using TAO.  There is no way to turn
 247                 multicasting off on the client side, but it is used
 248                 only as a last resort, i.e., any of the other options
 249                 will override it.
 250
 251                 When OS platform doesn't support multicast, or client
 252                 or server isn't written using TAO, or a more
 253                 reliable/predictable location method is desired, etc.,
 254                 one of the other options can be used to bootstrap to
 255                 the Naming Service.
 256
 257
 258 How to use the NT_Naming_Service
 259 ================================
 260 A command line interface is provided to install, configure, start,
 261 and stop the Naming service as a Windows service.
 262
 263 1. Syntax
 264
 265         % tao_nt_cosnaming [-i [n]]
 266                            [-c [args]]
 267                            [-r]
 268                            [-s]
 269                            [-k]
 270                            [-t n]
 271                            [-d]
 272
 273 2. Optional Command-line Arguments
 274
 275         -i [n]
 276                 Install this program as an NT service, with specified startup mode
 277
 278         -c [args]
 279                 Query or supply command line arguments for NT service.
 280
 281         -r
 282                 Remove this program from the Service Manager
 283         -s
 284                 Start the service
 285
 286         -k
 287                 Kill the service
 288
 289         -t n
 290                 Set startup mode for an existing service
 291
 292         -d
 293                 Debug; run as a regular application
 294
 295 3. Usage
 296
 297         To see different stages of an NT service application, you have
 298         to run the program several times, with different options.
 299         Please note: run with only one option at a time. Only the
 300         Administrator can run commands that modify state such as the -i
 301         or -c options.
 302
 303         a. First, you must initialize the service in the NT SCM
 304            database.  Run tao_nt_cosnaming with -i [n], where n is a
 305            number from 1 to 4, corresponding to these startup options:
 306
 307            // Start Type (from WinNT.h)
 308            //
 309            #define SERVICE_SYSTEM_START    0x00000001
 310            #define SERVICE_AUTO_START      0x00000002
 311            #define SERVICE_DEMAND_START    0x00000003
 312            #define SERVICE_DISABLED        0x00000004
 313
 314            If only -i is specified, SERVICE_DEMAND_START is default option.
 315            This option may only be run as Administrator.
 316
 317         b. For System or Auto start modes, or even Demand start and using the
 318            -s option to start, any command line options, such as endpoint
 319            specification or IOR publication, must be stored in the Windows
 320            registry. Use tao_nt_cosnaming -c with no additional arguments to
 321            see the current command line setting. Use tao_nt_cosnaming -c "args"
 322            to provide a new command line for the registered name service. Be
 323            sure to quote the args string. For example:
 324
 325            tao_nt_cosnaming -c "-ORBListenEndpoints iiop://%computername%:2809"
 326
 327            will yield:
 328            tao_nt_cosnaming -c
 329            -ORBListenEndpoints iiop://VIRTWIND:2809
 330
 331            Notice the environment variable used in the argument string was
 332            expanded.
 333
 334         c. Now you are ready to run the actual service. Run
 335            tao_nt_cosnaming -s.
 336
 337         d. To stop service execution, run tao_nt_cosnaming -k.
 338
 339         c. To remove the service from the Service Control Manager
 340            database, run tao_nt_cosnaming -r.
 341
 342         In addition, once you have initialized this service (by using
 343         the -i option) you can change its startup type to one of the
 344         other values above.  To do this, run tao_nt_cosnaming -t n, where
 345         n is a number corresponding to one of the startup modes listed above.
 346
 347         In order to debug the service's execution itself, use the -d
 348         option.
 349
 350 Troubleshooting
 351 ============================================
 352
 353 Q1. Error Message: "subscribe: no such device"
 354
 355 A1. On starting, the error message "subscribe: no such device" is a
 356 rather cryptic message saying that basically either you don't support
 357 multicasting or there is no route for multicasting on one of your
 358 network interfaces( e.g. eth0 ).
 359
 360 ---------------------------------------
 361 (Step 1)
 362 Check to see if you have multicasting enabled. In the case of Linux
 363 you will need to check the configuration of your kernel. RedHat users
 364 have multicasting enabled by default. Once you are sure that you have
 365 multicast enabled then move to the next step. Alternative is to start
 366 tao_cosnaming with multicast disabled.
 367
 368
 369 ---------------------------------------
 370 (Step 2)
 371 Check to see if you have the route for multicasting. Linux users can
 372 do this by running:
 373
 374         /sbin/route
 375
 376 You should see something like this:
 377
 378 Kernel IP routing table
 379 Destination     Gateway         Genmask         Flags Metric Ref    Use Iface
 380 10.0.0.0        *               255.255.255.0   U     0      0        0 eth0
 381 127.0.0.0       *               255.0.0.0       U     0      0        0 lo
 382 224.0.0.0       *               240.0.0.0       U     0      0        0 eth0
 383
 384 If you don't see the line for multicast routing:
 385
 386 224.0.0.0       *               240.0.0.0       U     0      0        0 eth0
 387
 388 You will need to add in the next step. If you do see that line and the
 389 problem is still there then contact the tao developers on github at
 390 https://github.com/DOCGroup/ACE_TAO. Please remember to use the
 391 problem form. It helps developers to have a more educated guess at the
 392 exact problem you are having.
 393
 394 ---------------------------------------
 395 (Step 3)
 396
 397 You can do this manually in a script that start the Naming service:
 398
 399 (Linux/Unix):
 400
 401         /sbin/route add -net 224.0.0.0 netmask 240.0.0.0 dev eth0
 402
 403 Alternatively for RedHat users you can add this into a file
 404 "/etc/sysconfig/static-routes". As of Redhat 7, you might have to
 405 create this file, you can make an entry:
 406
 407         eth0 net 240.0.0.0 netmask 240.0.0.0
 408
 409 On startup when the network interfaces that will be supporting
 410 multicast routing are started the route will be added. In my case it
 411 adds multicasting routing to eth0 (the first NIC).
 412
 413 ----------------------------------------
 414 (Step 4)
 415
 416 Double check that the route has been added correctly using /sbin/route.
 417
 418 Kernel IP routing table
 419 Destination     Gateway         Genmask         Flags Metric Ref    Use Iface
 420 10.0.0.0        *               255.255.255.0   U     0      0        0 eth0
 421 127.0.0.0       *               255.0.0.0       U     0      0        0 lo
 422 224.0.0.0       *               240.0.0.0       U     0      0        0 eth0
 423
 424 At this point you should be able to run tao_cosnaming. Have fun!