HP OpenVMS Systems Documentation

1. The local namespace is listed first, and so it is the primary name service. This line defines the first of three rules for searching the local namespace. The template definition with an asterisk "*" specifies that the user-supplied name be passed to the local namespace exactly as entered by the user.
2. The template definition of local:.lky.* specifies that the user-specified name be searched next in the local namespace as local:.lky.name. For example, if the user specified node name plm, then the local namespace is searched for local:.lky.plm.
3. The template definition of local:* specifies that the user-specified name be searched next in the local namespace as local:name. For example, if the name is specified as .plm, then namespace search is for local:.plm.
4. This line defines the DECdns namespace search rules, specifying that the name be searched for exactly as the user specifies it.
5. This line defines the DNS/BIND namespace search rules, specifying that the name be searched for exactly as the user specifies it.

To display information about the search path maintained for backtranslation (address to node name translation), use the following command. An example and description of the information displayed follows:

$ ncl show session control backtranslation search path

Node 0 Session Control
AT 1996-03-19-11:00:57.490-05:00I49.712

Characteristics

    Backtranslation Search Path       =
        (
            [
                Directory Service = Local , (1)
                Template = "*"
            ] ,
            [
                Directory Service = DECdns ,
                Template = "local:.DNA_BackTranslation" (2)
            ] ,
            [
                Directory Service = Domain ,
                Template = "*" (3)
            ]
        )

1. The template in this line specifies that the user-supplied address be searched in the local namespace exactly as specified by the user.
2. The template in this line specifies that the user-specified address be searched in the directory local:.DNA_BackTranslation.
3. The template in this line specifies that the user-supplied address next be searched in the DNS/BIND namespace exactly as specified by the user.

For DECnet-Plus for OpenVMS, DIGITAL recommends that you rerun NET$CONFIGURE.COM to revise the standard search path NCL script (NET$SEARCHPATH_STARTUP.NCL) whenever it is necessary to reorder access to the name services on the node. To modify the standard search path startup script, run NET$CONFIGURE.COM and use Option 2 (Change node name/namespace name).

The name of the backtranslation directory that Session Control uses is .DNA_BackTranslation with the same nickname as the node name in the current namespace. If the node name is changed, Session Control tracks the change within the number of seconds specified by the address update interval Session Control attribute. See the backtranslation directory statusattribute under the session control entity for the current full name of the backtranslation directory used by Session Control.

5.1.4 Changing the Default Namespace Name

The name of the node synonym directory that Session Control uses is .DNA_NodeSynonym with the nickname of the default namespace at the time that Session Control was first created.

{default-namespace}:.dna_nodesynonym

If you change the default namespace name without reconfiguring, you must set the name of the node synonym directory. ( Section 5.1.6 describes how to change the default namespace name.) Set the node synonym directory with the node synonym directory characteristic attribute under the session control entity. For example:

ncl> set session control node synonym -
_ncl> directory default-namespace:.dna_nodesynonym

In very large or widely distributed networks you can use multiple directories to store node synonym soft links, rather than the single default .DNA_NodeSynonym directory.

To use an alternate node synonym directory on an OpenVMS system, edit SYS$MANAGER:NET$LOGICALS.COM and add the following line:

$ define/system/exec decnet_migrate_dir_synonym ".synonym_dir_name"

The defined directory is then used by NET$CONFIGURE, decnet_register, and decnet_migrate.

5.1.6 Managing the DECdns Clerk

The DECdns namespace is the total collection of names that one or more DECdns servers know about, look up, manage, and share. You define the default namespace name during configuration of a DECdns clerk. Then, unless a user specifies otherwise, DECdns always assumes a name is in the default namespace. Use the following NCL set command to change the default namespace:

ncl> set dns clerk default namespace {namespace-name}

Note that this command will affect all users of DECdns on the system, including the Session Control module. Therefore, DIGITAL recommends that you do not use this command, but instead use the DECnet-Plus configuration procedure.

In general, to manage the namespace, use the DECdns Control Program SYS$SYSTEM:DNS$CONTROL.EXE.

For more information about managing the namespace, refer to the DECnet-Plus DECdns Management guide.

5.2 Resolving Names and Addresses with the Naming Cache

DECnet Phase V software includes the common directory interface (CDI) as an interface between DECnet Phase V Session Control and all the supported name services (local namespace, DECdns, DNS/BIND). CDI performs the necessary switching between the various name servic during lookups, enabling the use of multiple name services.

Prior to the addition of the CDI, the DECdns clerk was the primary interface between DECnet Session Control and DECdns servers or the local namespace. Now most all DECnet-related calls to DECdns (or to any other naming service) are first handled by CDI.

The DECdns clerk receives requests for name/address information from client applications and looks up the requested information on the appropriate DECdns server or in the local namespace. The DECdns clerk caches (saves) pointers to DECdns servers discovered during these lookups. This saves the clerk from repeatedly connecting to a server for the same information. For lookups involving applications such as DECmcc and DFS, the DECdns clerk caches results of lookups. Caching improves performance and reduces network traffic.

5.2.1 The CDI Naming Cache and DECdns

On OpenVMS systems, CDI uses an in-memory naming cache to improve performance of name and address resolution for the supported name services. DECnet-Plus for OpenVMS requests CDI directly for name and address resolution. DECnet-Plus uses CDI for looking up information from all three name services: local namespace, DECdns, and DNS/BIND.

The DECdns clerk cache still exists. When CDI calls DECdns for node name information, DECdns searches the clerk cache to determine where to look up the requested information. DECdns continues to use the clerk cache to determine the location of servers in the DECdns namespace. DECnet-Plus for OpenVMS uses the DECdns clerk to parse the special namespace nicknames LOCAL: and DOMAIN:. These nicknames in a node full name indicate to DECnet-Plus the name service where the name and addressing information is stored. Note that DECdns clerks do not cache DECnet names for any namespace. The clerk caches pointers to the servers where node names are stored.

The DECdns clerk cache continues to be used by applications other than DECnet-Plus that use DECdns directly, such as the Distributed File Service (DFS) application.

5.2.2 Managing the CDI Naming Cache

Using NCL commands, you can manage two CDI naming cache parameters, the checkpoint interval and the timeout period, and you can flush entries from the in-memory naming cache. Note that these parameters do not affect DECdns; they only affect CDI.

5.2.2.1 Checkpoint Interval

To ensure that the information contained in the naming cache is preserved across system reboots, DECnet periodically saves (or checkpoints) a snapshot of the in-memory naming cache to disk. At system startup, the naming cache can be populated with the entries most recently saved to disk. Note that this means the naming cache is read into memory only during DECnet startup. Keep this in mind if you are copying the cache to other nodes in the network for updates.

The following NCL command changes the frequency of this checkpoint operation from the default of once every 8 hours to once every 12 hours:

$ mcr ncl set session control naming cache checkpoint interval 12:00:00

One advantage of resetting the checkpoint interval is that you force a new checkpoint to be written within the next 15 minutes, even if a checkpoint is not due at that time.

You can use either the Common Trace Facility or the CDI$TRACE program to obtain naming trace information.

Use the following command to invoke the Common Trace Facility:

$ Trace Start "SESSION CDI *"

Including the CDI parameter restricts trace facility output to node name and address resolution messages.

Use the following command to run CDI$TRACE, a program located in SYS$SYSTEM:

$ run sys$system:cdi$trace

You can use the following procedure to redirect CDI$TRACE output to a file:

1. Define a DCL foreign command symbol:

   $ cdi$trace == "$cdi$trace"

2. Specify the name of the file to contain the CDI$TRACE output:

   $ cdi$trace trace.log

   
   The output file may occasionally be missing the last few records of the trace. This is a known problem.

CDI$TRACE has known problems when run during a LAT terminal session (on an LT device). A workaround is to issue the DCL spawn command first.

5.2.2.2 Timeout Period

The naming cache includes a mechanism to remove old cache entries. When a naming cache entry reaches a preset age, the entry times out, or expires, and is eliminated from the cache. On the first lookup request for an entry after it has timed out, when DECnet does not find the entry in the in-memory cache, DECnet will retrieve up-to-date information from the name service. In this way, cache entries are periodically refreshed to accurately reflect the current network environment.

The following NCL command changes the length of the timeout interval from the default of 30 days. For example, this command decreases the timeout interval to once every 5 days:

$ mcr ncl set session control naming cache timeout 5-00:00:00

The default timeout value of 30 days is suitable for most networks. However, for stable networks in which node names are rarely changed or swapped with other names, you can increase the value. The only benefit of keeping a lower value is that more space is freed in the cache as each timed-out entry is deleted.

Reducing the timeout value may result in the sudden loss of cached entries. Use the NCL flush command to remove specific entries, as explained below.

DIGITAL recommends that you do not change a node name or swap names of nodes until after the naming cache timeout period has passed. This allows time for the out-of-date node and addressing information to be flushed from the cache.

Consider the following scenario. Node .mgmt.accnt is assigned address 4.234 and this name and address information is stored in the name service. After DECnet has looked up node .mgmt.accnt, it stores this node name and address combination (.mgmt.accnt and 4.234) in its in-memory cache. When node .mgmt.accnt is subsequently reassigned to address 4.235, the following events can occur:

1. DECnet retrieves address 4.234 for node name .mgmt.accnt from the in-memory cache.
2. DECnet attempts to connect to address 4.234.
3. When the connection fails, DECnet again looks up the address for node .mgmt.accnt, this time bypassing the naming cache and searching the name service. This new lookup for node .mgmt.accnt finds address 4.235 in the name service, updates the cache, and successfully connects to the node.

However, if after node .mgmt.accnt is assigned a new address, .mgmt.accnt's old address, 4.234, is subsequently reassigned to node .mgmt.pers before the timeout period has elapsed, the following can occur:

1. DECnet retrieves address 4.234 for node name .xyz.accnt from the in-memory cache.
2. DECnet attempts to connect to address 4.234.
3. The connection succeeds. DECnet is unable to tell that it has connected to the wrong node.

To prevent this scenario, do either of the following:

• Before reassigning a node address to another node name, first deassign the node address from the current node name and wait until the cache timeout interval passes before reassigning the address to another node name. This allows time for the addresses to be flushed automatically from the in-memory cache.
• Use an NCL command to manually flush one or more in-memory cache entries. When manually flushing cache entries, be sure to perform the flush command on every system with stale cache entries. If you must reassign a node before the cache timeout period has expired, you must flush all cache entries. Although entries are immediately removed from memory, the cache saved on disk will still contain these cache entries until the next checkpoint interval. To force a quicker checkpoint of the cache (within the next 15 minutes), reset the checkpoint interval to the value currently set (if you do not want to change the interval thereafter).
  In the following example, the first NCL command flushes one specified entry from the cache. The second command flushes all cache entries:

  $ mcr ncl flush session control naming cache entry "entry-name" $ mcr ncl flush session control naming cache entry "*"

The decnet_register tool simplifies and centralizes management of namespace information.

The decnet_register manage command assists with setting up and managing DECdns distributed namespaces by creating the required hierarchy of directories, setting and altering access rights to these directories, and enabling and disabling autoregistration.

This section explains how to use decnet_register to manage and register node names in a DECdns or local namespace. In particular, this section explains how to use decnet_register to perform the following distributed namespace tasks. For an alphabetical command reference, see Appendix E.

• Invoke the decnet_register utility ( Section 5.3.1).
• Use the decnet_register interface ( Section 5.3.2).
• Display node registrations and verify their internal consistency ( Section 5.3.3).
• Register and modify node names, node synonyms, and addresses in your namespaces ( Section 5.3.4).
• Update a remote node's registered address information with information decnet_register obtains by connecting to the node itself ( Section 5.3.5).
• Rename registered nodes in a namespace ( Section 5.3.6).
• Repair the synonym and address links for registered nodes ( Section 5.3.7).
• Deregister nodes from a namespace ( Section 5.3.8).
• Export node registration information from a namespace into an editable text file ( Section 5.3.9.1).
• Import node registration information from a text file into a namespace ( Section 5.3.9.2).
• Converting an existing LNO text file to a Local namespace ( Section 5.3.9.3).
• Set preferences and network values ( Section 5.3.10).
• Using an initialization command file for preset values ( Section 5.3.11).
• Manage the DECdns directory service ( Section 5.3.12).
• Spawn to DCL to enter one or more DCL commands and return again to decnet_register ( Section 5.3.13).

To invoke decnet_register, enter the run command:

$ run sys$system:decnet_register

You can also invoke decnet_register using a foreign command symbol:

$ netreg :== $sys$system:decnet_register
$ netreg

Once invoked, decnet_register continues to accept commands until you enter the exit command.

If you have defined a foreign command symbol, you can include a decnet_register command on the invocation command line as follows:

% netreg show node mynode

With this command line, decnet_register executes the included command and immediately exits.

When you invoke decnet_register from a video terminal, decnet_register starts in forms mode by default. When you invoke decnet_register from a command procedure or from a hardcopy terminal, decnet_register starts in command mode by default. You can change this default behavior permanently by defining a logical name or for a single invocation only by using the /c and /f qualifiers on the command line.

To change the default behavior permanently, define one of the following logical names:

• $ define decnet_register_commands 1 forces default use of the command line interface until you redefine the logical name.
• $ define decnet_register_forms 1 forces default use of the forms interface until you redefine the logical name.

Note that only one logical name takes effect at a time. If you define both logical names, the last one defined takes effect.

To change the default behavior for the current invocation only, use one of the following switches:

• $ netreg /c forces the use of the command line interface for the current invocation of decnet_register only.
• $ netreg /f forces the use of the forms interface for the current invocation of decnet_register only.