DECdns uses a client/server model. An application that depends on DECdns to store and retrieve information for it is a client of DECdns. Client applications create names for resources on behalf of their users. Through a client application, a user can supply other information for DECdns to store with a name. This information is stored in data structures called attributes. Then, when a client application user refers to the resource by its DECdns name, DECdns retrieves from the attributes the data to be used by the client application.

A system running DECdns server software is a DECdns server. A DECdns server stores and maintains DECdns names and handles requests to create, modify, or look up data. You designate a system as a DECdns server when configuring the DECnet-Plus software.

A component called the clerk is the interface between client applications and DECdns servers. A clerk must exist on every DECnet-Plus node using DECdns and is created during configuration of the network software. The clerk receives a request from a client application, sends the request to a server, and returns the resulting information to the client. This process is called a lookup. The clerk is also the interface through which client applications create and modify names. One clerk can serve many client applications.

The clerk caches, or saves, the results of lookups so it does not have to repeatedly go to a server for the same information. The cache is written to disk periodically so the information can survive a system reboot or the restart of an application. Caching improves performance and reduces network traffic.

Figure 1.1, “Sample DECdns LAN Configuration” shows a sample configuration of DECdns clerks and servers on a nine-node local area network (LAN). Every node is a clerk, and DECdns servers run on two selected nodes.

Every DECdns server has a database called a clearinghouse in which it stores names and other DECdns data. The clearinghouse is where a DECdns server adds, modifies, deletes, and retrieves data on behalf of client applications. Although more than one clearinghouse can exist at a server node, VSI does not recommend it as a normal configuration because it degrades the performance of the server.

Figure 1.2, “Simple Lookup” shows the interaction between a DECdns client, clerk, server, and clearinghouse during a simple lookup. First, the clerk receives the lookup request from the client application (step 1) and checks its cache. Not finding the name there, the clerk contacts the server on Node 2 (step 2). The server finds the name in its clearinghouse (steps 3 and 4) and returns the requested information over the network to the clerk (step 5), which passes it to the client application (step 6). The clerk also caches the information so it does not have to contact a server the next time a client requests a lookup of that same name.

One of the most important users of DECdns is DECnet Phase V software such as DECnet-Plus. When you make the transition from DECnet Phase IV to DECnet Phase V, all node names in your network become full names. If DECdns is used as the naming service, then all node names become DECdns full names. (For a discussion of full names, see Section 2.1, “Structure of a Name”.) Along with the node names, DECdns stores the address and protocol information that DECnet needs to make connections between nodes. The DECnet-Plus software includes a registration tool to help you create DECdns names for nodes.

Another important user of DECdns in DECnet-Plus software is the VSI Distributed Time Service (DECdts). DECdts and DECdns actually depend on each other. DECdts uses DECdns as a networkwide registry for global time servers that synchronize system clocks in the network. DECdns uses timestamps to determine the order in which changes to its data occur, and it depends on DECdts to synchronize time on DECdns servers so their timestamps are consistent. Synchronized clocks are important to any distributed application that needs to keep track of the order in which events occur across multiple systems.

Two of the other OpenVMS applications that use DECdns (in conjunction with DECnet) are:

VSI DECdfs for OpenVMS allows users on one OpenVMS system to access files on another system as if the files were on the local system. DECdfs uses DECdns to register file resources, called DECdfs access points.

VSI Notes is a computer conferencing system that lets you conduct online conferences or meetings. It uses DECdns to store the location (node name or address) of a conference. If a conference moves from one node to another, its moderator can update the address information stored in DECdns. Users can continue to refer to the conference by the same DECdns name and never need to know that it has moved to another node.

If you have VSI software that uses DECdns, read the documentation for that software for a further understanding of how it interacts with DECdns.

The previous sections introduced a variety of ways in which applications and people can use DECdns names. This section describes basic concepts related to organizing and managing those names.

The total collection of names that one or more DECdns servers know about, look up, manage, and share is called a namespace. A DECdns namespace can be stored as a partitioned, partially replicated database. As a partitioned database, it is stored in several locations. As a partially replicated database, part of it is stored simultaneously in multiple locations.

When you create a namespace, you organize DECdns names into a hierarchical structure of directories. DECdns directories are conceptually similar to the directories you create in your operating system's file system. They are a logical way to group names for DECdns-specific management or usage purposes. Directory replicas are physical instances of a directory, stored in clearinghouses. In this way, a clearinghouse can be defined as a collection of directory replicas stored on a particular server. (A clearinghouse does not necessarily contain the entire namespace.)

The highest-level directory in the namespace is denoted by a dot (.) and is called the root directory. The root is created automatically when you initialize a namespace. You can then create and name other directories below the root. Any directory that has a directory beneath it is considered the parent of that directory. Any directory that has a directory above it is considered a child of the directory above it.

Figure 1.3, “Sample Namespace Directory Hierarchy” shows a simple hierarchy of directories. The root directory (.) is the parent of the directories named West and FarEast. The FarEast directory is a child of the root directory and the parent of the Tokyo and Osaka directories.

If you have a small network and do not expect much growth, you need a minimum number of directory levels in the namespace. For administrators of large networks, multiple directory levels provide greater flexibility in distributing, controlling access to, and managing many names. Distribution of names helps to balance the work load on DECdns servers.

1.4.2. Putting It All Together

To summarize, a namespace consists of a complete set of names shared and managed by one or more DECdns servers. A name can designate a directory, object entry, or soft link. The logical picture of a namespace is a hierarchical structure of directories and the names they contain. Every physical instance of a directory is called a replica. Names are physically stored in replicas, and replicas are stored in clearinghouses. Any node that contains a clearinghouse and runs DECdns server software is a server.

Figure 1.4, “Components of a DECdns Server Node” shows the components of a DECdns server. Every server manages at least one clearinghouse containing directory replicas. A replica can contain object entries, soft links, and child pointers. Figure 1.4, “Components of a DECdns Server Node” shows only one replica and one of each type of entry possible in a replica. Normally, a clearinghouse contains many replicas, and a replica contains many entries.

DECdns lets you control access to clearinghouses, directories, and their contents. Access to clerks and servers is determined by operating system rights identifiers.

You assign access in the form of an access control entry (ACE), which consists of two parts: the principal portion and the list of access rights that the principal has to the associated name in the namespace. The principal part of the ACE can be the name of an individual user, a name with one or more wildcard characters to denote several users, or a group name.

It is often useful to set up an access control policy when you plan your namespace, choosing a select group of users who will have control over the root of the namespace and deciding how to delegate access in lower levels of the directory structure. Section 5.3, “Setting Up Access Control in a New Namespace” provides guidelines for planning an access control policy for your namespace.

DECdns requires advance planning and, once the namespace has been established, ongoing maintenance. For detailed planning guidelines, see the VSI DECnet-Plus Planning Guide. This section describes the routine DECdns ongoing management tasks.

DECdns management tasks fall into two main categories: namespace administration and day-to-day server management. In small networks, it is possible for one person to handle both types of tasks. In larger networks, the responsibility will most likely be divided among several people.

The complete specification of a name in the namespace is called its full name and includes the names of all of its parent directories, starting from the root. Each element within a full name is separated by a dot (.) and is known as a simple name.

A full name also can include a namespace nickname, but that is not necessary when only one namespace exists in a network. A namespace administrator or system manager defines the default namespace during configuration of a DECdns clerk, or later by a management command. Then, unless a user specifies otherwise, DECdns always assumes a name is in the default namespace. If it is necessary to specify a namespace, use the following format:

namespace_nickname:.simplename.simplename...

For example, ABC:.Dir1 specifies a directory called .Dir1 in the ABC namespace. Similarly, JKL:.Dir1.Object denotes an object entry with the simple name Object in the Dir1 directory and the JKL namespace.

Just as directory names in a logical namespace hierarchy translate to physical replicas in clearinghouses, DECdns names translate to physical resources that are used either internally by DECdns or by client applications. The attributes of a name are what make the translation possible. This section illustrates the relationship between DECdns names and the physical resources they describe.

Figure 2.1, “Logical and Physical Views of a Namespace” shows three directories and their contents in a logical namespace, and how replicas of those directories are physically implemented in two clearinghouses. The clearinghouses themselves have DECdns names: .Boston_CH on Node 1 and .Sales.East.NY_CH on Node 2. The _CH suffix is a recommended convention for naming clearinghouses. The .Boston_CH clearinghouse contains replicas of the root directory and the .Sales.East directory. The .Sales.East.NY_CH clearinghouse contains a replica of the .Sales directory. VSI recommends that you create at least two replicas of every directory. Therefore, each directory shown should be replicated in at least one other clearinghouse somewhere in the network.

To discover the physical location of a DECnet resource, for example, DECdns looks up an address associated with its node name. The next four figures illustrate the connection between various kinds of DECdns names and the resources they describe. The figures are based on the namespace in Figure 2.1, “Logical and Physical Views of a Namespace”.

Figure 2.2, “A Node Object Entry and a Node” shows the relationship between an object entry named .Sales.NY01 and the resource it describes: a node at the organization's New York sales headquarters. The node object entry resides in a replica of the .Sales directory in the .Sales.East.NY_CH clearinghouse. The entry has a DNA$Towers attribute, which contains protocol and address information necessary to contact the node. The name of this attribute reflects the fact that a DECnet Phase V address consists of separate layers, sometimes called tower floors, in the Network Architecture (DNA) and Open Systems Interconnection (OSI) models.

Figure 2.3, “Clearinghouse Object Entries and Clearinghouses” shows the relationship between two clearinghouse object entries and the clearinghouses they describe. A clearinghouse object entry differs from other kinds of object entries in that it is created and maintained by the DECdns software instead of by a client application, and special rules exist regarding where it can be stored (see Appendix B, Special Clearinghouse Rules for details). However, it is just like any other object entry in that it describes a physical resource in the network: the clearinghouse. The clearinghouse and its object entry both have the same name; DECdns creates the object entry automatically when you create and name the clearinghouse.

The figure shows two clearinghouse object entries: .Boston_CH, which points to the clearinghouse named .Boston_CH on Node 1, and .Sales.East.NY_CH, which points to the clearinghouse named .Sales.East.NY_CH on Node 2. Each clearinghouse object entry has a DNA$Towers attribute that contains, among other things, the DECnet address of the node where the clearinghouse resides. As the figure shows, it is not necessary for the clearinghouse object entry to be stored within the clearinghouse to which it points.

Figure 2.4, “A Soft Link and Its Resolution” shows the relationship between a soft link, the object entry it points to, and the resource that the object entry describes. The link, .Sales.LN03, has an attribute called DNS$LinkTarget, which contains the name that the link points to: an object entry named .Sales.East.Floor1LN03. The object entry describes an LN03 printer on the first floor of the company's New York sales office. A replica containing the .Sales.East.Floor1LN03 object entry exists in the .Boston_CH clearinghouse. The entry has an attribute that contains information on how to locate the printer in the network.

Figure 2.5, “Child Pointers and Directories” shows the relationship between directories and their associated child pointers. It illustrates that, although a child pointer has the same name as its associated directory, the pointer is a separate entry in the namespace and resides in the parent of the directory to which it points.

In the .Boston_CH clearinghouse, the root replica contains a child pointer for the .Sales directory. The child pointer has an attribute called DNS$Replicas that contains the name and address of the Sales.East.NY_CH clearinghouse, where a replica of the .Sales directory exists.

In the .Sales.East.NY_CH clearinghouse, the .Sales replica contains a child pointer for the .Sales.East directory. The child pointer's DNS$Replicas attribute contains the name and address of the .Boston_CH clearinghouse, where a replica of the .Sales.East directory exists.

When a directory has multiple replicas, as would normally be the case, the DNS$Replicas attribute lists all of the clearinghouses containing a replica of that directory.

DECnet-Plus software includes the common directory interface (CDI) which acts 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 services during lookups, enabling the use of multiple name services. CDI uses an in-memory naming cache to improve performance of name and address resolution for the supported name services.

Previous to the addition of the CDI, the DECdns clerk was the primary interface between DECnet Phase V Session Control and DECdns servers or the Local namespace. Now most all DECnet-related calls to DECdns (or to any other name 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. For lookups involving applications such as DECmcc and DFS, the DECdns clerk caches results of lookups. This saves the clerk from repeatedly connecting to a server for the same information. Caching improves performance and reduces network traffic.

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 DECdfs application.

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. These parameters control CDI; they do not control DECdns. For more information on managing CDI, see the VSI DECnet-Plus for OpenVMS Network Management Guide.

As the previous figures illustrate, DECdns finds information about the physical location of a resource by looking up one or more attributes associated with its name. First, though, the clerk must know how to find the name. If a name does not yet exist in the clerk's cache, the clerk must know of at least one DECdns server to contact in search of the name.

Figure 2.6, “How the Clerk Finds a Name” is an example of how the clerk finds the root and works downward from it to locate an object entry. The entry, .Sales.RSMcl, describes a client system at a company's London sales headquarters.

Long lookups like the one illustrated in Figure 2.6, “How the Clerk Finds a Name” should not happen often after a clerk establishes its cache and becomes more knowledgeable about servers and their contents. The figure illustrates the resources and connections that could be involved in an initial lookup—the clerk contacted three servers before it found the information it needed. The figure also illustrates the important job DECdns has of making sure the parent and child directories in the namespace remain connected. If the directory path is broken or a clearinghouse is unreachable, a clerk might not be able to complete a lookup. Keep this example in mind when planning the replication of directories.

Because a full name consists of the complete directory path from the root directory to the target object entry, directory, or soft link, full names can be long if a namespace has several levels of directories.

DECnet Phase V software supports a form of abbreviated name called the node synonym. A node synonym is a soft link that points to the full name of a node object entry. Node synonym soft links, in the form of a DECnet Phase IV-style node name, enable applications that do not support the length of DECdns full names to continue to use six-character node names.

Node synonyms should not be viewed as a way for users to avoid typing the DECdns full name of a node. Local names, and a feature called the local root, are a faster and more convenient method of shortening names. Both local names and local roots are for use only on the system where they are defined; unlike node synonyms, they do not have global meaning throughout the namespace. Local names and local roots are usable for any DECdns name, not just node names. However, they are not usable for DECnet node name lookups; they are used for DECdns Control Program lookups and lookups for applications other than DECnet.

$ define/table=dns$system name1 "name2"

An update propagation is an immediate attempt to apply one change to all replicas of the directory in which the change was just made. Its main benefit is that it delivers each change in an efficient and timely way. Unlike a skulk operation, however, update propagation does not guarantee that the change gets made in all replicas. If a particular replica is not available, the update propagation does not fail; the change simply does not get made in that replica. The skulk operation ensures that when the replica is available again, it becomes consistent with the other replicas in its set.

You can tune the degree of persistence that DECdns uses in attempting an update propagation—or prevent propagation altogether—by adjusting a directory attribute called DNS$Convergence. Convergence also affects the frequency of skulks on a directory. See Section 7.5, “Adjusting a Directory's Convergence” for details on viewing and changing a directory's convergence.

DECdns skulks each directory individually. During a skulk, DECdns collects all changes made to the master replica since the last skulk completed and applies them to the replica on the server where the skulk started. DECdns then disseminates the changes from the up-to-date replica to all other replicas of the directory. All replicas must be available for a skulk to be considered successful. If DECdns cannot contact a replica, it continues making changes in the replicas that it can contact, and generates an event to notify you of the replica or replicas it could not update. DECdns then periodically reattempts the skulk until it completes successfully.

DECdns assigns a creation timestamp (CTS) to everything within a namespace (clearinghouses, directories, object entries, soft links, and child pointers) as well as to the namespace itself. On the namespace, the timestamp is called a namespace creation timestamp (NSCTS).

The CTS is a unique value reflecting the date, time, and location where a namespace, clearinghouse, directory, or entry in a directory was created. It consists of two parts: a time portion and the system identifier of the node on which the name was created. The two parts guarantee uniqueness among timestamps generated on different nodes.

During propagation of a new name to each replica of the directory where it was created, every DECdns server checks the validity of the CTS before accepting the new name. A name's CTS is valid if it falls between the current time and the time of the last skulk on the directory where it was created. When determining the current time, the server allows a maximum acceptable time difference of 300 seconds into the future.

The update timestamp (UTS) reflects the most recent change made to any of the attributes of a clearinghouse, directory, object entry, soft link, or child pointer. When a DECdns server receives an update to an existing entry in a directory, it checks the validity of the UTS before accepting the update. Occasionally, between skulks or update propagations, separate changes may be made to the same attribute of the same entry in different replicas. In that case, the change with the most recent UTS remains.

Directories and replicas have several other timestamps that DECdns uses when determining whether to skulk a directory or make a change in a directory. Chapter 11, DECdns Control Program Command Dictionary describes those timestamps and how DECdns uses them.

verb [entity-name] [argument] [attribute] [, prepositional-phrase]

Refer to the command descriptions in Chapter 11, DECdns Control Program Command Dictionary for complete listings of the arguments, attributes, and prepositional phrases you can use with a particular DECdns command.

You can enter commands that manage Network Control Language (NCL) entities from either NCL or DNSCP. You can abbreviate an NCL directive or entity name to a minimum of four unique characters. You can abbreviate a DNSCP directive or entity name to its fewest number of unique characters.

This section lists the DECdns entities and describes what each entity represents.

Child

A child pointer connects a parent and child directory in a hierarchical namespace. The child pointer is stored in the parent directory.

Clearinghouse

A clearinghouse is a database containing a collection of directory replicas at a particular server. Commands directed to this entity manage DECdns attributes of the clearinghouse (for example, its access control set). You can enter these commands only from DNSCP.

Directory

A directory contains object entries and other namespace entries that are logically stored under one name (the directory name).

DNS Clerk

The clerk is the interface between client applications and servers. You can enter commands directed to this entity from either NCL or DNSCP.

DNS Clerk Known Namespace

A known namespace is a namespace that a clerk has discovered and cached as a result of configuration information, datagrams received on a local area network (LAN), or an explicit management command. You can enter commands directed to this entity from either NCL or DNSCP.

DNS Clerk Manual Name Server

A manual name server creates knowledge in the local clerk's cache about a server that exists across a wide area network (WAN). You can enter commands directed to this entity from either NCL or DNSCP.

DNS Clerk Remote Clearinghouse

A remote clearinghouse is a clearinghouse that a clerk has discovered and cached. A clerk can learn about clearinghouses as a result of configuration information, datagrams received on a local area network (LAN), an explicit management command, or during the process of finding a name. To a clerk, all clearinghouses are remote, even if they exist on the same node as the clerk. You can enter commands directed to this entity from either NCL or DNSCP.

DNS Server

A server handles lookup requests from clerks and maintains the contents of the clearinghouse or clearinghouses at its node. You can enter commands directed to this entity from either NCL or DNSCP.

DNS Server Clearinghouse

A clearinghouse is a database containing a collection of directory replicas at a particular server. Commands directed to this entity manage NCL attributes of the clearinghouse and perform NCL management functions such as enabling or disabling the clearinghouse. You can enter these commands from either NCL or DNSCP.

Group

A group lets you assign a uniform set of access rights to several users at once. DECdns does this by mapping a set of names representing the group members to a single name (the group name).

Link

A soft link is a pointer providing an alternate name for an object entry, directory, or other soft link.

Object

An object entry is the name of a resource (such as a node, print queue, or application) that is stored in the namespace.

Replica

A replica is a copy of a directory. Each copy, including the original or master, is referred to as a replica.

Subtree

A subtree is a specific directory and its contents or a hierarchy of directories and their contents.

Every DECdns entity has attributes that contain data associated with that entity. Attributes describe the operational properties of an entity and specify other information that regulates or monitors the entity's behavior. Some attributes have a single value; others contain a set of values. Attributes fall into one of four categories:

Characteristics

Reflect or affect the operational behavior of an entity. Some characteristics are static and cannot be modified; others can be modified with DNSCP or NCL commands.

Counters

Record the number of times a particular event or problem occurred since the entity was last enabled.

Identifiers

Uniquely distinguish an entity from any other entity.

Status Attributes

Reflect the current operational state of an entity.

You can use prepositional phrases to affect the destination or content of command output. Generally these phrases are most useful with the show and directory commands. Chapter 11, DECdns Control Program Command Dictionary documents the appropriate use of prepositional phrases in individual commands.

Commands that you can enter from either DNSCP or NCL allow you to manage entities on remote systems in the network. You can specify an access control string, which consists of a user name and a password, for an account on the remote system you wish to access. Enter the access control string as part of the node name specification in the format nodename"user-name password". In the following example, syspasswd is the password of the system account on node .nrl. (In this example, the default namespace specified for the clerk is IAF.)

ncl> set node .nrl"system syspasswd" dns clerk default namespace IAF

Use the do command or run @filename from inside DNSCP to read a file of commands.

dns> do .status

You can create a .dnscpinit file if you want DECdns to execute a set of commands automatically when you start the control program. The dnscpinit. file should reside in the SYS$LOGIN directory. Note that the dot (.) follows the dnscpinit file name.

Confidence Level Commands

These commands set and display the confidence level of clerk calls. Setting the confidence controls the accuracy level and cost of clerk calls. The set dnscp confidence[=]value command sets the value as one of the following: low, medium, or high. A low confidence level means the clerk obtains information from caches or the most convenient server. A medium level means the clerk obtains information directly from a server, and a high level obtains information only at master replicas. The initial value is medium.

dns> set dnscp confidence high

dns> show dnscp confidence

Timeout Commands

These commands set and display the length of time, in seconds, that the control program will wait for a clerk call to complete. You can use the set dnscp timeout[=]value command to increase the timeout value if you are having trouble with calls not completing. This command sets the value as either a number of seconds or the word default, which is 30 seconds for most operations. You can also use the value 0 to indicate the default value.

dns> set dnscp timeout 60

dns> show dnscp timeout

Commands That Display Timestamps and Namespace Nicknames

The timestamp display commands set and display the format of timestamps, which is useful for troubleshooting or if you need to discover the timestamp for a namespace. The set dnscp timestamp display[=]value command controls the format in which timestamps are displayed. Specify one of the following units for value: time, hexadecimal, or default. The initial setting is the default value time, a human-readable date and time.

dns> set dnscp timestamp display hex

dns> show dnscp timestamp display

The nickname display commands control the format in which namespace nicknames are displayed in DNSCP. The set dnscp nickname display[=]value command sets the value as one of the following units: time, hexadecimal, timestamp, name, or default. The initial setting is the default value name.

dns> set dnscp nickname display timestamp

dns> show dnscp nickname display

Preferred Clearinghouse Commands

These commands enable you to specify a clearinghouse from which to read attribute values for entries stored in that clearinghouse. You cannot specify a preferred clearinghouse for modifications.

The set dnscp preferred clearinghouse clearinghouse-name command enables you to specify the clearinghouse from which to read the values of specific individual attributes using show clearinghouse commands of the form:

show clearinghouse clearinghouse-name attribute-specifer

dns> set dnscp preferred clearinghouse .paris_ch

The set dnscp preferred clearinghouse command (or the set dnscp preferred clearinghouse any command) causes DNSCP to revert to the default, which is to use any clearinghouse.

dns> show dnscp preferred clearinghouse

Default Entity Commands

These commands set and display a default entity. To set the default entity, enter set dnscp default entity entity-type entity-name. When the control program starts, the default entity is the root directory. This command only works for directory and show commands.

dns> set dnscp default entity directory .pjl

dns> show dnscp default entity

Local Root Commands

These commands set and display your local root setting. The local root is a prefix that DECnet-Plus software obtains automatically by stripping off the rightmost simple name of the local node's full name. DECnet Phase V Session Control creates the local root as a reserved name in the DNS$SYSTEM logical name table. The set dnscp local root command enables you to override the systemwide local name setting for your current DNSCP session. To set the local root, enter set dnscp local root directory-name.

dns> set dnscp local root IAF:.pjl

dns> show dnscp local root 

See Chapter 11, DECdns Control Program Command Dictionary for more information on using wildcard characters in specific commands.

You can cancel commands, edit command lines, continue a command beyond one line, or recall commands within DNSCP.

Canceling a Command

Press Ctrl/Y to cancel command processing during command entry or while the command is being processed.

Continuing a Command Line

dns> set group .sales.testgroup DNS$GroupRevoke -
_> 2019-12-31-12:00:00 090-00:00:00

Recalling a Command

You can recall previously typed commands and avoid the inconvenience of retyping long commands. The recall buffer holds up to 20 previously entered commands. Once a command is displayed, you can reexecute or edit it.

To display the commands stored in the recall buffer, press Ctrl/B or the up arrow and down arrow keys.

Press Ctrl/B once to display your previous command. Press Ctrl/B again to display your next previous command, and so on, to the last saved command.

Press the up arrow and down arrow keys to display the previous and successive commands, respectively. Press the arrow keys repeatedly to move backward or forward through the buffer of saved commands until you display the command you want to reuse or edit.

The access rights that you grant users to a name are stored as separate sets of values within the access control set (ACS) associated with the name's DNS$ACS attribute. Within a name's ACS is a list of access control entries (ACEs). Each ACE consists of two parts: a principal, describing the user (or users) to whom the access is granted, and a rights list containing the specific access rights granted to the principal. The ACEs stored in a name's ACS collectively determine who (which user or application accounts) can access the name.

You use the show access commands to display the ACEs associated with the clearinghouse, directory, object entry, or soft link that you specify.

Example 1

dns> show directory .eng access

             SHOW
        DIRECTORY  IAF:.eng
               AT  26-NOV-2019:18:36:03
    DNS$ACS (set) = :
            Flags = propagate, group
           Rights = read, write, delete, test, control
            Group = .DNS_Admin
    DNS$ACS (set) = :
            Flags = propagate, default
           Rights = read, test
    (V) Principal = .orion.smith
    DNS$ACS (set) = :
            Flags = propagate, default
           Rights = read, test
    (V) Principal = .rigel.jones

Example 2

dns> show directory .budget access
                               SHOW
                          DIRECTORY  IAF:.budget
                                 AT  17-APR-2019:14:54:54
                      DNS$ACS (set) = :
                              Flags = none
                             Rights = read, write, delete, test, control
                     (IV) Principal = ABC::SYSTEM
                      (V) Principal = IAF:.ABC.SYSTEM
                      DNS$ACS (set) = :
                              Flags = none
                             Rights = read, write, delete, test, control
                     (IV) Principal = ORION::DNS$SERVER
                      (V) Principal = IAF:.ORION.DNS$SERVER
                      DNS$ACS (set) = :
                              Flags = authenticated
                             Rights = read, write, delete, test, control
                      (V) Principal = IAF:.budget.orion_ch
                      DNS$ACS (set) = :
                              Flags = default, propagate, group
                             Rights = read, write, delete, test, control
                              Group = IAF:.ad_users

Use the remove access commands to remove an ACE from the ACS of the name that you specify. This command removes ACEs from a name's ACS one at a time. You cannot remove individual access rights (read, write, delete, test, or control) separately.

Examples

dns> show object .sales.work_disk2 access
             SHOW
           OBJECT  IAF:.sales.work_disk2
               AT  26-JAN-2019:09:16:51
    DNS$ACS (set) = :
            Flags = none
           Rights = read, test
    (V) Principal = .orion.smith

dns> remove object .sales.work_disk2 access .orion.smith

dns> show directory .sales access
             SHOW
        DIRECTORY  IAF:.sales
               AT  02-FEB-2019:21:09:31
    DNS$ACS (set) = :
            Flags = propagate
           Rights = read, write, delete, test, control
    (V) Principal = .polaris.jones
    DNS$ACS (set) = :
            Flags = default
           Rights = read, write, delete, test, control
    (V) Principal = .polaris.jones

dns> remove directory .sales access .polaris.jones

dns> remove directory .sales access as default .polaris.jones

The access rights of user Jones to the .sales directory and its future contents have now been removed. Remember, however, that the preceding two commands do not remove any access rights that Jones might have been granted to names that already exist in the .sales directory. To remove access rights of user Jones to these names, you must issue separate remove access commands for each name, or use the remove subtree access command to remove access for the entire directory and its contents.

dns> show directory .mfg access
             SHOW
        DIRECTORY  IAF:.mfg
               AT  21-MAR-2019:08:16:50
    DNS$ACS (set) = :
            Flags = nopropagate
           Rights = read, test
    (V) Principal = .vega.smith

dns> remove directory .mfg access .vega.smith

Remember that removing an ACE associated with an individual user does not revoke the rights granted to the user by any ACEs containing wildcard principals that include the user or access control groups of which the user is a member. To revoke the access rights of individual members of an access control group, remove the user from the group. See Section 5.6.4, “Removing Group Members” for information on how to remove group members.

A group is an object entry that contains a collection of principals (members) stored in the group's DNS$Members attribute. Whenever you identify users to whom you want to grant a common set of access rights, you can treat the users as a unit by creating an access control group of which they all are members. When you add a member to an access control group, the principal described by that member acquires all the access rights assigned to the group. When you remove a member from an access control group, the principal described by that member loses all the access granted to the group. By assembling principals into access control groups, you can simplify the task of assigning access to multiple users.

Using access control groups can also improve performance by helping you avoid the creation of ACSs that contain large numbers of ACEs specifying individual principals. Maintaining large ACSs degrades response time during access checking and can consume significant amounts of memory and disk space. Access control groups make it possible for you to keep the number of ACEs you require to a minimum.

The DECnet-Plus configuration program on the first DECdns server in your namespace automatically creates an access control group named .DNS_Admin to which you can add, as members, namespace administrators, server managers, and other personnel to whom you want to grant unlimited access to the entire namespace. See Section 5.6.2, “Adding Group Members” for information on how to add group members. See Section 5.3.2, “Adding Access for Your Namespace Administrator Group” for information on assigning access for a namespace administrator group in a new namespace.

dns> create group .sales.group1

dns> add group .DNS_Admin member .orion.smith

dns> add group .mfg.camgroup member .mfg.*...

dns> add group .mfg.camgroup member .dist.transport_group

dns> change subtree .sales group member .orion.smith .trifid

dns> change subtree .admin... group member .vega.group1 .vega.group2

dns> change subtree ... group member iaf:.orion.smith abc:.

dns> remove group .DNS_Admin member .orion.jones

dns> remove group .mfg.camgroup member .mfg.*...

dns> remove group .mfg.camgroup member .dist.transgroup

dns> remove subtree .sales group member .orion.jones

dns> remove subtree .eng... group member .vega.smith

dns> remove subtree ... group member .transport_group

dns> delete group .eng.testgroup

DECdns provides several commands that allow you to modify existing principals in ACEs or to remove ACEs associated with a particular directory and all of its contents or with an entire subtree of directories. Section 5.7.1, “Modifying Principals” and Section 5.7.2, “Removing Access from Multiple Names” describe how to use these commands to make the task of modifying or removing multiple ACEs more convenient.

dns> change subtree .sales access .orion.smith .trifid

dns> change subtree .mfg... access .oberon.jones .oberon.smith -
_> exclude links

dns> change subtree ... access iaf:.orion.smith abc:

dns> change subtree ... access iaf:. abc:.

dns> remove subtree .eng access .vega.jones

dns> remove subtree .sales... access .test_group

dns> remove subtree .eng... access .vega.jones exclude -
_> objects, exclude links

At any time, a clerk, server, or clearinghouse can be in only one of the following states: off, initial, on, shut, or broken. The clerk, server, and clearinghouse entities are available only when they are enabled (in the on state). See the reference pages for the show dns clerk, show dns server, and show dns server clearinghouse commands in Chapter 11, DECdns Control Program Command Dictionary for full descriptions of the states for these entities.

To Display Clerk Status

Use the show dns clerk command and specify the state attribute to check the current status of a clerk.

To use the show dns clerk command, you must have the NET$EXAMINE rights identifier.

Example

dns> show dns clerk state

To Display Server Status

Use the show dns server command and specify the state attribute to check the current status of a server.

To use the show dns server command, you must have the NET$EXAMINE rights identifier.

Example

dns> show dns server state

To Display Clearinghouse Status

Use the show dns server clearinghouse command and specify the state attribute to check the current status of a clearinghouse.

To use the show dns server clearinghouse command, you must have the NET$EXAMINE rights identifier.

Example

dns> show dns server clearinghouse state

Every clerk, server, and clearinghouse maintains a set of counters to keep track of the read, write, and other operations that it has performed (or that were performed on it) since it was last enabled. You can monitor these counters to determine the type and volume of the DECdns traffic being generated on your network. Clerk, server, and clearinghouse counters are fully described in Chapter 11, DECdns Control Program Command Dictionary.

Some clerk, server, and clearinghouse counters are incremented by DECdns events. See Appendix D, DECdns Events for more information on these events.

To Display Clerk Counters

Use the show dns clerk command with the all counters attribute specifier to display the current counter values of a clerk.

To use the show dns clerk command, you must have the NET$EXAMINE rights identifier.

Example

dns> show node .umbriel dns clerk all counters

To Display Server Counters

Use the show dns server command with the all counters attribute specifier to display the current counter values of a server.

To use the show dns server command, you must have the NET$EXAMINE rights identifier.

Example

dns> show dns server all counters

To Display Clearinghouse Counters

Use the show dns server clearinghouse command with the all counters attribute specifier to display the current counter values of a clearinghouse.

To use the show dns server clearinghouse command, you must have the NET$EXAMINE rights identifier.

Example

dns> show node .vega dns server clearinghouse .paris1_ch all -
_> counters

You can monitor a clerk's remote clearinghouse counters to look at the distribution of the clerk's transactions to each of the clearinghouses that it uses and to find out where a clerk's requests are most often directed.

To Monitor a Clerk's Communication with Specific Clearinghouses

Use the show dns clerk remote clearinghouse command with the all counters attribute specifier to display the current counter values for any or all of the clearinghouses with which a clerk has communicated.

To use the show dns clerk remote clearinghouse command, you must have the NET$EXAMINE rights identifier.

Examples

dns> show dns clerk remote clearinghouse .ny1_ch all counters

dns> show dns clerk remote clearinghouse * all counters

To Monitor the Contents of a Clearinghouse

Use the show clearinghouse command and specify the DNS$CHDirectories attribute to display the creation timestamps (CTSs) and names of all the directories stored in a clearinghouse.

To use the show clearinghouse command, you must have read permission to the clearinghouse.

Examples

dns> show clearinghouse .paris1_ch dns$chdirectories

The value assigned to a clerk's clerk timeout attribute specifies how long the clerk waits for a response to a request. After a clerk issues a request, it waits for the specified length of time and, if no response is received from DECdns within that time period, returns a timeout error message to the requesting application.

A clerk's clerk timeout attribute is set to a value of 150 seconds when the clerk is created. If you experience a large number of timeout errors on a clerk, you should either increase the clerk's timeout interval or replicate the information the clerk most often requests in a clearinghouse that is located closer on the network to the clerk system.

For example, a clerk that frequently initiates skulks of a directory whose replicas are spread over extreme distances throughout the network may often time out before receiving a response from the clearinghouses in which these remote replicas are stored. To make it possible for the clerk's skulks of this directory to succeed, you should increase the clerk's clerk timeout attribute value to a duration long enough to ensure that the clerk will not time out before receiving a response from the remote locations.

To Modify a Clerk's Clerk Timeout Attribute

Use the set dns clerk command to specify a new value for the clerk timeout attribute. If you do not specify a value in the command, the attribute is set to its default value of 150 seconds.

To use the set dns clerk command, you must have the NET$MANAGE rights identifier.

Example

dns> set dns clerk clerk timeout 180

DECdns clerk requests from nodes in an OpenVMS Cluster can send the cluster alias address as the source address. The default behavior is to send the individual node address.

To use this functionality, edit the SYS$MANAGER:DNS$CLERK_CLUSTER.NCL file and set outgoing alias = true.

To affect the running system, use the following NCL command on all nodes in your cluster:

NCL>set session control application dnsclerk outgoing alias = true

You may want to delete the clerk or server running on a particular system when the active clerk or server processes need to be stopped, such as to perform diagnostic or troubleshooting work on the system.

When you delete a clerk, only the active clerk processes are deleted. Deleting a clerk does not remove the clerk software from the system or delete the clerk's cache. If you delete the clerk from a system that also functions as a DECdns server, that server and the clearinghouse it serves become unavailable.

dns> disable dns clerk

dns> disable dns server
dns> disable dns clerk
dns> delete dns clerk

dns> disable node .miranda dns clerk
dns> delete node .miranda dns clerk

$ @sys$manager:net$shutdown
$ delete sys$sysroot:[sysexe]dns$cache.0000011411;1
$ delete sys$sysroot:[sysexe]dns$cache.version;11413
! Reboot the system!!!!

dns> disable node .vega dns server

dns> delete node .vega dns server

$ @sys$startup:dns$clerk_startup

$ @sys$startup:dns$server_startup

The static device tables formerly used to determine the devices used by DECdns have been removed. Now, DECdns uses the $DEVSCAN and $GETDVI system services to build a list of devices that have the following characteristics:

You can use the logical name DNS$ETHERNET_DEVICE to provide a list of devices that DECdns should NOT use. All devices must be in the form _ddcn:, where dd is the OpenVMS physical device name, c is the controller letter, and n is the port number. The string is limited to 255 characters and can contain spaces and other text which is ignored by DNS. For example, the following two commands tell DECdns not to use the _EIA0: and _FWA0: devices.

$ DEFINE/SYSTEM DNS$ETHERNET_DEVICE "Don’t use _EIA0: and _FWA0: "
$ DEFINE/SYSTEM DNS$ETHERNET_DEVICE "_EIA0:_FWA0:"

By creating directories, you make it possible to replicate and manage groups of object entries according to where, how often, or by whom they are used. Grouping application-defined object entries into separate directories also makes it possible to collectively control access to the entries and allows you to take advantage of automatic rights propagation. See Chapter 5, Managing DECdns Access Control for complete information on how to grant access to directories and their contents.

Creating a directory hierarchy requires planning. Make sure you read the naming and hierarchy design information in the VSI DECnet-Plus Planning Guide before you create directories.

To Create a Directory

Creating a Directory in a Nondefault Clearinghouse

Sometimes DECdns may not be able to create the new directory in the default clearinghouse. If this happens, or if you want to create the directory in a clearinghouse other than the default clearinghouse, use the create directory command's optional clearinghouse argument to specify another clearinghouse. The clearinghouse you choose must be named in either the root directory or in a directory that is closer to the root than the directory you are creating. (The DECdns software enforces this requirement to guarantee compliance with clearinghouse rule 2. See Appendix B, Special Clearinghouse Rules for more information on the clearinghouse rules.)

Examples

dns> create directory .sales

dns> create directory .sales.region1 clearinghouse .eng.london1_ch

After You Create a Directory

After you create a directory, enter the show directory access command to display the DNS$ACS attribute of the new directory. Make sure that the users and applications for whom the directory was created have the proper access. If the required access was not inherited from the access control set (ACS) of the new directory's parent directory, use the add directory access command to create the necessary access control entries (ACEs). See Chapter 5, Managing DECdns Access Control for complete information on how to add access to a directory.

All replicas that you create with the create replica command are read-only replicas. In a read-only replica, users and client applications can look up information, but are not permitted to create new information or modify existing information. You should create replicas in clearinghouses whose users need to access the directory but do not need (or are not permitted) to update its contents. You can modify a directory's replica set to redesignate the master replica or to exclude certain replicas, as explained in Section 9.2, “Modifying a Directory's Replica Set”.

You can display the replica set for a directory by using the DECdns Control Program command show directory directory-name dns$replicas (see Chapter 11, DECdns Control Program Command Dictionary).

Before You Create a Replica

To Create a Replica

Example

dns> create replica .mfg at clearinghouse .paris1_ch

Sometimes, you may need to delete a replica when the information it contains is no longer needed by the local users of the clearinghouse in which the replica is stored. You may also need to delete a replica to prepare for deleting the directory of which the replica is a member or before deleting the clearinghouse in which the replica is stored.

To Delete a Replica

Use the delete replica command to delete a replica from the clearinghouse that you specify.

Example

dns> delete replica .eng at clearinghouse .chicago2_ch

To Skulk a Directory

To skulk a directory, you must have write access to the directory.

Use the set directory to skulk command to initiate an immediate skulk on the directory that you specify. After you enter the command, the DECdns Control Program temporarily suspends the dns> prompt while the skulk is in progress. (It may take some time for DECdns to complete skulks of directories with large replica sets.) If the prompt returns with no error messages, the skulk was successful (see Note). If errors are returned before the prompt reappears, the skulk failed. Skulk failure also generates the DECdns Skulk Failed event at the server that stores the master replica of the directory being skulked. See Appendix D, DECdns Events for more information on this event.

For a skulk to succeed, every replica in the directory's replica set must be reachable. Skulks may sometimes fail, especially on directories with large replica sets, or when the servers that store replicas of the directory are located over great distances where network connectivity is not always reliable. Skulk failure does not make DECdns unusable. Although the skulking process is unable to update information in a replica that it cannot contact, it always updates information in the replicas it can reach. Temporarily, some replicas contain the latest information and some do not. When a skulk fails, DECdns automatically repeats the skulking process (at an interval based on the directory's convergence value) until all replicas in the set are updated with the latest changes. When all replicas contain identical information, DECdns considers the skulk to have succeeded, and updates the DNS$AllUpTo attribute of the directory.

If skulks of a particular directory continue to fail, you can determine the cause by reviewing the DECnet event log of the server that stores the master replica of the directory.

Example

dns> set directory .admin to skulk

The value assigned to a directory's DNS$Convergence attribute determines how frequently the server that stores the master replica of the directory initiates a skulk of the directory's replica set. A directory's convergence can be set to a value of low, medium, or high.

A directory set to low convergence is skulked at least once every 24 hours. The server on which a low convergence directory resides makes no attempt to propagate updates and waits for the next skulk to synchronize the replica set.

A directory set to medium convergence is skulked at least once every 12 hours. If an update is made to the directory, the server that stores the master replica attempts to propagate the new information to the entire replica set. If the propagation fails, the server waits for the next skulk to synchronize the replica set.

Every newly created directory inherits the convergence value of its parent directory. The root directory of a namespace defaults to a convergence value of medium at its creation. Unless you change this value (or the convergence value of any lower-level directories after you create them), all directories that you create under the root will also default to medium. For most directories, you should never need to modify this value. However, you may occasionally find it useful to set a directory's convergence to high or low.

Before You Modify a Directory's Convergence

Use the show directory command and specify the DNS$Convergence attribute to verify the current value of the directory's convergence.

To Modify a Directory's Convergence

You must have write access to the directory whose convergence you intend to modify.

Use the set directory command to assign a value of high, medium, or low to a directory's DNS$Convergence attribute.

Examples

dns> set directory .sales dns$convergence = high

dns> set directory .mfg dns$convergence = low

You can use prepositional phrases to redirect a command's output and to qualify commands that contain wildcard characters. For example, with the to file [=] filename phrase, you can redirect the output of a command to a file on disk. You can use the with attribute phrase to limit the action of a command to affect only those entities that have the attribute value you specify. See Chapter 11, DECdns Control Program Command Dictionary for descriptions of the prepositional phrases you can use with the show and directory commands.

With the show command, you can display the directories stored in a clearinghouse and the current values of any or all of the attributes associated with a directory, group, link, object, or child pointer.

The basic syntax of all show commands is as follows:

show entity entity-name

You cannot use wildcard characters within the directory specification, but you can use wildcard characters in the terminating (rightmost) simple name.

You can combine multiple all, all characteristics, all counters, all status, and attribute qualifiers in a single command. Separate them with commas.

Examples

dns> show dns clerk all


Node 0 DNS Clerk
AT 2019-04-29-10:38:48.306-04:00I0.102

Status

    State                        = On


Characteristics

    Version                      = V2.0.0
    Clerk Timeout                =  0-00:01:00.000I0.000   Seconds
    Solicit Holddown             =  0-00:00:15.000I0.000   Seconds
    UID                          = 32A56750-059F-11CA-B98E-08002B0DC09D
    Default Namespace            = IAF


Counters

    Creation Time                = 2019-04-28-22:54:24.163+00:00I0.000
    Incompatible Protocol Errors  = 0
    Authentication Failures      = 0
    Read Operations              = 1194
    Cache Hits                   = 364
    Cache Bypasses               = 830
    Write Operations             = 293
    Miscellaneous Operations     = 0 

dns> show dns server all


Node 0 DNS Server
AT 2019-04-29-10:42:07.717-04:00I0.108

Status

    State                        = On


Characteristics

    UID                          = 3E6475F4-059F-11CA-B98E-08002B0DC09D
    Minimum Protocol Version     = V1.0.0
    Maximum Protocol Version     = V2.0.0
    Future Skew                  =  0-00:05:00.000I0.000   Seconds


Counters

    Creation Time                = 2019-04-28-22:54:43.725+00:00I0.000
    Incompatible Protocol Errors  = 0
    Authentication Failures      = 0
    Read Accesses                = 491
    Write Accesses               = 211
    Skulks Initiated             = 12
    Skulks Completed             = 12
    Times Lookup Paths Broken    = 0
    Possible Cycles              = 0
    Crucial Replica Removals Backed Out  = 0
    Child Pointer Update Failures  = 0
    Security Failures            = 0 

You can use the directory command to display a list of names that match the name you specify in the command or to display a list of the object entries, soft links, and child pointers in a directory.

The basic syntax of all directory commands is as follows:

directory entity entity-name

You cannot use wildcard characters within the directory specification, but you can use wildcard characters in the terminating (rightmost) simple name.

Examples

dns> directory object .eng.*

        DIRECTORY
           OBJECT  IAF:.eng
               AT  13-JUL-2019:18:45:00

sales_group
test_group
triton
work_disk1
work_disk2

dns> directory object .eng.t*

        DIRECTORY
           OBJECT  IAF:.eng
               AT  13-JUL-2019:18:46:00

test_group
triton 

A soft link is an alternative name, or synonym, with which you can refer to another existing name in a namespace. Soft links allow users and client applications to refer to a particular directory, object entry, or soft link by more than one name.

dns> create link .sales.asia destination .sales.eur

dns> create link .mfg.robo1 destination .mfg.robotics_controller03 -
_> expiration 2019-12-12-09:00:00

dns> create link .admin.linka destination .sales.discount_stats -
_> expiration 2019-01-11-12:00:00 extension 090-00:00:00

dns> set link .admin.work_disk dns$linktarget .admin.work_disk03

dns> set link .eng.link01 dns$linktimeout -
_> (2019-12-31-12:00:00 000-00:00:00)

dns> set link .eng.link01 dns$linktimeout -
_> (2019-12-31-12:00:00 090-00:00:00)

You do not need to modify a directory's replica set when you create or delete read-only replicas; the normal skulking process for the directory will distribute these modifications to all members of the replica set automatically.

Before You Modify a Directory's Replica Set

Before you can modify a directory's replica set, you need to know how many replicas exist, the replica type of each replica, and the name of the clearinghouse where each of the replicas is stored. The command you use to modify a directory's replica set prevents you from accidentally leaving a replica out of the new set. You must explicitly list all existing replicas in the set. You can include or exclude any replica from the new set, but you must account for all replicas. Only one of the replicas that you include in the new set can be designated as the master replica.

Use the show directory command and specify the directory's DNS$Replicas attribute to gather this information. See Chapter 8, Viewing the Structure and Contents of a Namespace for complete information on how to use the show directory command.

After You Modify a Directory's Replica Set

After you use the set directory to new epoch command, DECdns automatically initiates a special skulk of the directory. This skulk may require more time to complete than other regularly scheduled skulks and will require more network resources.

9.2.1. Changing the Replica Type of a Replica

For configuration management reasons, you may want to designate a different replica as a directory's master replica when:

• A server system whose clearinghouse contains a master replica will be down for an extended period of time or removed permanently from the network.

• A clearinghouse that stores a master replica is going to be deleted from the namespace.

• You want to locate the master replica closer to where the majority of updates to the directory originate.

Use the set directory to new epoch command to designate a new master replica.

Example

In this example, the replica set of the .eng directory consists of three replicas: the master replica (stored in clearinghouse .ny1_ch), a read-only replica (stored in clearinghouse .ny2_ch), and a read-only replica (stored in clearinghouse .chicago1_ch), as shown in Figure 9.1, “Example Replica Set”.

The following command designates the read-only replica (stored in clearinghouse .chicago1_ch) as the directory's new master replica, designates the former master replica (stored in clearinghouse .ny1_ch) as a read-only replica, and leaves the read-only replica (stored in clearinghouse .ny2_ch) as it is. Figure 9.2, “Example Replica Set After Master Redesignation” shows the result of this command.

dns> set directory .eng to new epoch master .chicago1_ch, read-only -
_> .ny1_ch, read-only .ny2_ch

9.2.2. Excluding a Replica from a Replica Set

You can temporarily exclude a replica from its replica set when the clearinghouse in which the replica is stored unexpectedly becomes unavailable. Excluding this replica enables DECdns to complete skulks of the directory during the time the replica is unavailable. Base your decision when to exclude a replica on how long the clearinghouse where the replica is stored will be unavailable. For example, if a clearinghouse will be off line for only a few hours, or even for several days, you may not need to ensure that DECdns is able to complete skulks of the directories stored there. However, if a clearinghouse will be unavailable for several weeks or more, you may want to exclude the replicas stored there from their respective replica sets to make sure that new information can be updated to the other replicas in the sets.

Note

When you know in advance that a replica will become permanently unavailable because its clearinghouse is being removed from the network, you should delete the replica rather than temporarily exclude it from the replica set. You must delete the replica before the clearinghouse becomes unavailable. See Section 7.3, “Deleting a Replica” for complete information on using the delete replica at clearinghouse command.

Excluding a replica does not delete the replica; it only prevents the replica from being updated by a skulk. DECdns clerks and servers still use the excluded replica for lookups. You should reintroduce the excluded replica to its replica set as soon as possible after the clearinghouse on which it resides becomes available. Otherwise, lookup requests directed to the excluded replica may return outdated information.

Use the set directory to new epoch command with the optional exclude argument to rebuild a directory's replica set, excluding the replica that you specify. Remember that you must account for all existing replicas in the command.

Example

In this example, the replica set of the .eng directory consists of three replicas: the master replica (stored in clearinghouse .chicago1_ch) and read-only replicas (stored in clearinghouses .ny1_ch and .ny2_ch).

In this case, the .ny1_ch clearinghouse has been cut off from the network because of accidental damage to the network transmission lines. Connectivity to the clearinghouse will not be restored for several days. During this period, skulks of the .eng directory will fail unless you temporarily exclude the read-only replica stored in clearinghouse .ny1_ch.

To make it possible for skulks of the .eng directory to succeed during the repair period, you can enter the following set directory to new epoch command to overwrite the current values of the .eng directory's DNS$Replicas attribute with new values that include only the replicas stored in the .ny2_ch and .chicago1_ch clearinghouses:

dns> set directory .eng to new epoch master .chicago1_ch, read-only -
_> .ny2_ch, exclude .ny1_ch

Figure 9.3, “Example Replica Set After Replica Exclusion” shows the result of the preceding command.

When connectivity with the .ny1_ch clearinghouse is reestablished, enter the following set directory to new epoch command to reintroduce the read-only replica stored in clearinghouse .ny1_ch to the replica set.

dns> set directory .eng to new epoch master .chicago1_ch, read-only -
_> .ny1_ch, read-only .ny2_ch

Note

You should always reintroduce excluded replicas to their replica sets as soon as possible after the clearinghouse in which they reside again becomes available. Otherwise, lookup requests directed to the excluded replicas in the clearinghouse may return outdated information.

You may sometimes want to delete directories from your namespace when the information they contain is no longer needed by users. DECdns provides two commands you can use to delete directories: delete directory and delete subtree. (A subtree can be a single directory and its contents, or a directory and all its child directories and their contents.)

When deleting directories, remember that DECdns does not permit you to delete a directory that stores clearinghouse object entries.

dns> delete subtree .sales...

Sometimes, because of corporate restructuring or other reasons, you may want to combine or rearrange various directories, or subtrees of directories, in your namespace.

For example, suppose the engineering group in your organization (.eng) is combined with the research and development group (.rnd) and that the two groups will begin to share a common set of network resources. You can reflect this organizational change in your namespace hierarchy by combining these directories. Similarly, if the engineering group becomes subordinate to the research and development group, you can reflect this change by creating an empty directory named .rnd.eng and then merging the contents of the .eng directory into .rnd.eng, thus appending .eng below .rnd.

9.4.2. Basic Merge and Append Operations

The following merge and append operations are based on a sample namespace (Figure 9.4, “Example Namespace Hierarchy”) that consists of two directories under the root: .eng and .rnd. The source directory (.eng) contains two object entries: .eng.obj1 and .eng.link1. The target directory (.rnd) also contains two object entries: .rnd.obj2 and .rnd.link2.

9.4.2.1. Performing a Basic Merge Operation

The following procedure merges the source directory .eng into the target directory .rnd. Step 3 of the procedure deletes the merged .eng directory from its original location and replaces it with a soft link to redirect lookups of .eng to the .rnd directory.

1. The following dump subtree command creates an interim file named eng.dat that contains the .eng directory and its contents, .eng.obj1 and .eng.link1.
   

   dns> dump subtree .eng into file eng.dat

   
   

   Note

   The .dat extension of the interim file eng.dat is added to the file name only to avoid confusion in the following example commands. File extensions are not required in the names of interim files. An interim file is a printable ASCII file.

   The dump subtree command can take some time to execute, especially if you are dumping large subtrees that contain many names. The clearinghouses that store the master replicas of the directories in the subtree you specify must all be enabled and reachable when you enter the command. Otherwise, the command fails and an error message is displayed explaining the reasons for the failure. The interim file contains only the directory information that was successfully dumped before the error occurred.

2. The following merge file command merges the interim file you created in step 1 (eng.dat) with the .rnd directory. The failures to file argument copies, to a failures file named failures.dat, any names that cannot be reached (and therefore cannot be created) when you enter the command. In this example, it is assumed that all affected files were successfully merged. See Section 9.4.5, “Using the Failures File” for more information on using the failures file.
   

   dns> merge file eng.dat into subtree .rnd failures to file -
   _> failures.dat

   Figure 9.5, “Example Namespace Before and After the Merge Operation” shows the structure of the example namespace before and after this merge operation.

3. After the merge operation, the .eng directory (and its contents) still exists at the source location. The following commands delete the .eng directory from its original location and then create a soft link named .eng in place of the deleted directory. This soft link redirects lookups of .obj1 and .link1 to their new locations in the .rnd directory.
   

   dns> delete subtree .eng...

   
   

   dns> create link .eng destination .rnd

9.4.2.2. Performing a Basic Append Operation

The following procedure merges the source directory .eng into the empty target directory .rnd.eng (that is, appends the .rnd directory under the .eng directory). Step 4 of the procedure deletes the merged .eng directory from its original location and replaces it with a soft link to redirect lookups of .eng to the .rnd directory.

1. The following dump subtree command creates an interim file named eng.dat that contains the .eng directory and its contents, .eng.obj1 and .eng.link1.
   

   dns> dump subtree .eng into file eng.dat

2. The following create directory command creates a new empty directory named .rnd.eng.
   

   dns> create directory .rnd.eng

3. The following merge file command merges the interim file you created in step 1 (eng.dat) with the new .rnd.eng directory. The failures to file argument copies, to a failures file named failures.dat, any names that cannot be reached (and therefore cannot be created) when you enter the command. In this example, it is assumed that all affected files were successfully merged. See Section 9.4.5, “Using the Failures File” for more information on using the failures file.
   

   dns> merge file eng.dat into subtree .rnd.eng failures to file -
   _> failures.dat

   Figure 9.6, “Example Namespace Before and After the Append Operation” shows the structure of the example namespace before and after this append operation.

4. After the append operation, the .eng directory (and its contents) still exists at the source location. The following commands delete the .eng directory from its original location and then create a soft link named .eng in place of the deleted directory. This soft link redirects lookups of .obj1 and .link1 to their new locations in the .rnd.eng directory.
   

   dns> delete subtree .eng...

   
   

   dns> create link .eng destination .rnd.eng

dns> merge subtree .eng into subtree .rnd

dns> change subtree ... access .eng.group1 .rnd.eng.group1

dns> change subtree ... group member .eng.group1 .rnd.group1

Before You Delete a Clearinghouse

To Delete a Clearinghouse

To delete a clearinghouse, first disable it, using the disable dns clearinghouse command. Then use the delete dns server clearinghouse command. Use both of these commands locally.

To use these commands, you must have the NET$MANAGE rights identifier.

As part of the delete dns server clearinghouse command, DECdns automatically deletes all read-only replicas from the clearinghouse and rebuilds the replica sets of those directories, excluding the deleted replicas from their replica sets. In addition to deleting the clearinghouse, the command deletes the clearinghouse's associated clearinghouse object entry. The command may not delete the clearinghouse database files from the system. You should ensure that they are deleted, as indicated below.

Clearinghouse deletion can take some time to complete. DECdns deletes a clearinghouse only after successfully completing a skulk of the directory that stores its associated clearinghouse object entry. Because a clearinghouse's deletion may not be made known immediately to all replicas of the directory in which its clearinghouse object entry is stored, a deleted clearinghouse may appear to exist in the namespace for some time after you issue the command. You can initiate a skulk on the directory yourself to ensure that all replicas are updated as quickly as possible.

Example

dns>disable dns server clearinghouse .paris2_ch
dns> delete dns server clearinghouse .paris2_ch

After You Delete a Clearinghouse

where nnnnnnnnnn represents an 10-digit number.

They reside, by default, in the SYS$SYSDEVICE:[DNS$SERVER] account. (If the clearinghouse was created with DNS Version 1 software and later converted to DECdns Version 2 format, the clearinghouse files reside, by default, in the SYS$SYSROOT:[DNS$SERVER] account.)

When you delete a clearinghouse, DECdns removes the contents of the dns_files.txt file (created when the clearinghouse is created and containing the path to the clearinghouse). This file is located in SYS$SPECIFIC:[SYSMGR]. Unless you have another clearinghouse on this server, delete the dns_files.txt file to complete cleanup of all clearinghouse-related files. If you have another clearinghouse on the server, keep this file and ensure that it includes a pointer to the remaining clearinghouse only. (The pointer to the deleted clearinghouse should be removed from the file.)

To invoke the DECdns configuration program, enter the following command:

$ @sys$manager:dns$configure.com

         DECdns Configuration

   [1]  Set the default namespace
   [2]  Establish communications with an off-LAN server
   [3]  Configure server in an existing namespace
   [4]  Show address information of this node
   [5]  Exit
At anytime, you can enter ? for help or ^Z to quit the current operation

  Pick a number from the list:

A clerk learns about all namespaces on its own LAN by listening to advertisements from servers on the same LAN. Because server advertisements do not span wide area network (WAN) links, a clerk cannot automatically learn about namespaces that exist outside the clerk's own LAN. For a clerk to make an initial connection to an off-LAN server, you must provide the clerk with the server's network service access point (NSAP) address, DECnet Phase IVcompatible address, or IP address. This information is saved in the clerk's cache and is used to make subsequent connections to the off-LAN server.

The first DECdns Version 2 server in a new namespace is usually configured as a result of (or following the process of) configuring DECnet-Plus software. Even if you maintain a small namespace that services only a few nodes, you should consider configuring at least one additional server on another stable system whose connectivity to your network is reliable. By maintaining your namespace on two servers (two clearinghouses), you create a real-time backup of namespace data and ensure that a failure on one of the servers will not interrupt DECdns service. As your namespace and network expand, you may want to configure additional servers to distribute namespace information around the network.

The DECdns server software is not installed on this system. If you want to configure a server on the system, type N or ^Z to exit this procedure and install the server software and a valid license before continuing.

dns> add directory . access dna_node.meta::dns$server for r,w,d,c
dns> add directory . access dna_node.meta::system for c

Warning>> You may need your page file quota to be 10327 during conversion.

Warning>> You may require up to 10327 contiguous free pages during conversion.
       >> This may mean that you need to add an additional pagefile.

Warning>> You may need to increase your VIRTUALPAGECNT to 10327 to complete conversion.
Warning>> You may need your page file quota to be 10327 during conversion.

ERROR>> Insufficient disk space on DKA100: disk;
     >> you need 4131 free blocks there for the conversion.
     >> Please make disk space available before continuing.

  Elapsed=0 00:00:10.75   CPU=0:00:02.47   DIRs done= 0%   MEM Kbytes=13

%DNS-F-CONVERT Cannot convert V1 data

If your node is a server, system managers of clerks that want to participate in your server's namespace, but exist across WAN links, may contact you to obtain your server node's NSAP address. Clerks need this information to make an initial connection to your server.

This node's NSAP is %x490004aa0004066a1120
This node's NSAP is %x490004aa0004066a1121

The display will contain one or more NSAP addresses, each address corresponding to one of the protocols that the server runs (TP4, NSP, and so on). If more than one NSAP is listed, make sure you inform the manager of the clerk system of all addresses. At least one address is likely to correspond to a protocol that the clerk can use to make its initial connection to your server. See VSI DECnet-Plus for OpenVMS Network Management Guide for more information on NSAP addressing.

You only need to create a new DECdns namespace if you are configuring the first DECdns server for the network (where no DECdns namespace exists) or if you are creating an additional namespace. When you create a namespace, you need a namespace nickname and clearinghouse name. The namespace nickname is part of the full name of every system configured subsequently in the network and should be unique to your network. The namespace nickname that you specify becomes the actual name of the namespace.

You create and initialize a namespace during the DECnet-Plus advanced configuration procedure. See DECnet-Plus for OpenVMS Applications Installation and Advanced Configuration Guide for details.

Before creating and initializing a new namespace, first configure the server to use the Local namespace, then check that the DECnet software works properly.

To create a new namespace while configuring a DECnet-Plus system:

In addition, VSI highly recommends you to refer to the VSI DECnet-Plus Planning Guide. Once you understand what is involved in creating a namespace, you can configure the server node to use the new DECdns namespace and create and initialize that namespace.

Use the DECnet-Plus configuration procedure (SYS$MANAGER:NET$CONFIGURE.COM) and select option 2 ("Change Naming Information") to create a new namespace. Choose the DECdns directory service as the primary directory service to be used on the system. The configuration procedure then prompts you for other information required for creating a namespace and the initial namespace directories.

The procedure instructs you to use the decnet_register tool to:

For more information about the decnet_register tool, see the VSI DECnet-Plus for OpenVMS Network Management Guide.