VSI TCP/IP Services for OpenVMS Management

Software Version:
VSI TCP/IP Services Version 6.0

Preface

The TCP/IP Services product is the VSI implementation of the TCP/IP networking protocol suite and internet services for OpenVMS Alpha and OpenVMS VAX systems.

TCP/IP Services provides a comprehensive suite of functions and applications that support industry-standard protocols for heterogeneous network communications and resource sharing.

This manual provides system and network managers with information needed for the day-to-day management of the TCP/IP Services software product. This manual is best used in conjunction with the VSI TCP/IP Services for OpenVMS Management Command Reference manual.

See the VSI TCP/IP Services for OpenVMS Installation and Configuration manual for information about installing, configuring, and starting this product.

1. About VSI

VMS Software, Inc. (VSI) is an independent software company licensed by Hewlett Packard Enterprise to develop and support the OpenVMS operating system.

2. Intended Audience

This manual is for experienced OpenVMS and UNIX system managers and assumes a working knowledge of OpenVMS system management, TCP/IP networking, and TCP/IP terminology.

3. Document Structure

This manual contains seven parts, as follows:

Chapters 1–5

Describes how to configure network interfaces, how to set up serial lines, and how to configure and manage routing.

Chapters 6 and 7

Describes how to set up and manage the BIND server, resolver, and load broker components.

Chapters 8–12

Describes how to set up the following network services:
  • BOOTP and TFTP
  • Portmapper
  • Network Time Protocol (NTP)
  • SNMP

Chapters 13–19

Describes how to configure network applications that let users send and receive electronic mail from the internet, establish login sessions with a remote host, and transfer files. These network applications include:
  • TELNET
  • FTP
  • Remote (R) commands
  • SMTP and POP
  • XDM-compatible X displays

Chapters 20 and 21

Describes how to configure, use, and manage the components that enable transparent network file sharing, including the NFS server and NFS client.

Chapters 22–24

Describes how to configure and manage network printing services, including LPD/LPR, TELNETSYM, and PC-NFS.

Appendices A, B, and C

Provides appendixes that:
  • Explain how to configure GATED.

  • Provide EBCDIC/DMCS translation tables.

  • Describe how NFS converts UNIX file names to OpenVMS files names.

  • List the acronyms related to TCP/IP networking.

4. Related Documents

Table 1 lists the documents available with this version of TCP/IP Services.
Table 1. TCP/IP Services Documentation

Manual

Contents

VSI TCP/IP Services for OpenVMS Concepts and Planning

This manual provides conceptual information about TCP/IP networking on OpenVMS systems, including general planning issues to consider before configuring your system to use the TCP/IP Services software.

This manual also describes the manuals in the TCP/IP Services documentation set and provides a glossary of terms and acronyms for the TCP/IP Services software product.

VSI TCP/IP Services for OpenVMS Installation and Configuration

This manual explains how to install and configure the TCP/IP Services product.

VSI TCP/IP Services for OpenVMS User's Guide

This manual describes how to use the applications available with TCP/IP Services such as remote file operations, email, TELNET, TN3270, and network printing. This manual explains how to use these services to communicate with systems on private internets or on the worldwide Internet.

VSI TCP/IP Services for OpenVMS Management

This manual describes how to configure and manage the TCP/IP Services product.

Use this manual with the VSI TCP/IP Services for OpenVMS Management Command Reference manual.

VSI TCP/IP Services for OpenVMS Management Command Reference

This manual describes the TCP/IP Services management commands.

Use this manual with the current manual.

VSI TCP/IP Services for OpenVMS ONC RPC Programming

This manual presents an overview of high-level programming using open network computing remote procedure calls (ONC RPC). This manual also describes the RPC programming interface and how to use the RPCGEN protocol compiler to create applications.

VSI TCP/IP Services for OpenVMS Sockets API and System Services Programming

This manual describes how to use the Sockets API and OpenVMS system services to develop network applications.

VSI TCP/IP Services for OpenVMS SNMP Programming and Reference

This manual describes the Simple Network Management Protocol (SNMP) and the SNMP application programming interface (eSNMP). It describes the subagents provided with TCP/IP Services, utilities provided for managing subagents, and how to build your own subagents.

VSI TCP/IP Services for OpenVMS Guide to IPv6

This manual describes the IPv6 environment, the roles of systems in this environment, the types and function of the different IPv6 addresses, and how to configure TCP/IP Services to access the 6bone network.

For a comprehensive overview of the TCP/IP protocol suite, you might find the book Internetworking with TCP/IP: Principles, Protocols, and Architecture, by Douglas Comer, useful.

5. VSI Encourages Your Comments

You may send comments or suggestions regarding this manual or any VSI document by sending electronic mail to the following Internet address: . Users who have VSI OpenVMS support contracts through VSI can contact for help with this product.

6. OpenVMS Documentation

The full VSI OpenVMS documentation set can be found on the VMS Software Documentation webpage at https://docs.vmssoftware.com.

7. Conventions

The following conventions may be used in this manual:
ConventionMeaning

Ctrl/ x

A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.

PF1 x

A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.

Return

In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)

...
A horizontal ellipsis in examples indicates one of the following possibilities:
  • Additional optional arguments in a statement have been omitted.

  • The preceding item or items can be repeated one or more times.

  • Additional parameters, values, or other information can be entered.

.
.
.

A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

( )

In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.

[ ]

In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.

[ |]

In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are options; within braces, at least one choice is required. Do not type the vertical bars on the command line.

{ }

In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.

bold text

This typeface represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.

italic text

Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).

UPPERCASE TEXT

Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Monospace type

Monospace type indicates code examples and interactive screen displays.

In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

-

A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

numbers

All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes—binary, octal, or hexadecimal—are explicitly indicated.

Other conventions are:
  • All numbers are decimal unless otherwise noted.

  • All Ethernet addresses are hexadecimal.

Chapter 1. Managing TCP/IP Services

This chapter reviews information you need to get started with the TCP/IP Services software. Topics include:
  • Reviewing pertinent databases, logical names, and configuration guidelines (Section 1.1).

  • Enabling support for DECnet over TCP/IP, and PATHWORKS (Advanced Server) (Section 1.2).

  • Creating user accounts and proxy identities (Section 1.3).

  • Configuring TCP/IP Services on an OpenVMS cluster (Section 1.4).

  • Starting services with the auxiliary server (Section 1.5).

1.1. Getting Started

This manual assumes you installed and configured TCP/IP Services software with the configuration procedure SYS$MANAGER:TCPIP$CONFIG.COM, as described in the VSI TCP/IP Services for OpenVMS Installation and Configuration manual. This menu-driven procedure configures the software components you select or all of the TCP/IP Services software components. The out-of-the-box defaults are designed to get your system up and running as an internet host with minimal effort.

TCPIP$CONFIG creates the database files listed in Table 1.1.
Table 1.1. Configuration Databases

Database

File Name

BOOTP database

SYS$COMMON:[SYSEXE]TCPIP$BOOTP.DAT ?

Configuration database

SYS$COMMON:[SYSEXE]TCPIP$CONFIGURATION.DAT

Export database

SYS$COMMON:[SYSEXE]TCPIP$EXPORT.DAT

Hosts database

SYS$COMMON:[SYSEXE]TCPIP$HOST.DAT

Networks database

SYS$COMMON:[SYSEXE]TCPIP$NETWORK.DAT

Proxy database

SYS$COMMON:[SYSEXE]TCPIP$PROXY.DAT

Routes database

SYS$COMMON:[SYSEXE]TCPIP$ROUTE.DAT

Services database

SYS$COMMON:[SYSEXE]TCPIP$SERVICE.DAT

1.1.1. Logical Names

Logical names allow you to customize or modify component behavior. Logical names also point to directories, database files, and log files.

TCPIP$CONFIG defines the following logical names for the databases listed in Table 1.1:
  • TCPIP$BOOTP (if the BOOTP service is configured)

  • TCPIP$CONFIGURATION

  • TCPIP$EXPORT

  • TCPIP$HOST

  • TCPIP$NETWORK

  • TCPIP$PROXY

  • TCPIP$ROUTE

  • TCPIP$SERVICE

Service-specific logical names should be defined while the service is not running. Always stop the service before defining logical names.

Most logical names require SYSTEM privileges in order to affect the service. You should use the /EXECUTIVE and /SYSTEM qualifiers on the DEFINE command line.

It is important to always use the standard, documented shutdown procedures to stop the services and to stop TCP/IP Services; otherwise, logical names may revert to their default definitions.

Many services reference service-specific configuration files. To specify different configuration options for the nodes in an OpenVMS cluster, you can modify service-specific logical name so that the configuration files are specific to each node. In clusters with a shared system disk, the default device (SYS$SYSDEVICE) is a cluster-common directory.

To specify node-specific configuration files, you can define the service-specific logical to reference a node-specific file. For example, on each node that requires node-specific customizations:
  1. Shut down the service:
    $ @SYS$STARTUP:TCPIP$service_SHUTDOWN.COM
  2. Enter the DEFINE command for the service-specific logical name:
    $ DEFINE/SYS/EXEC logical-name SYS$SPECIFIC:[directory]logical-name
    
  3. Start the service:
    $ @SYS$STARTUP:TCPIP$service_STARTUP

See individual component chapters in this manual for information on how specific components use logical names.

1.1.2. Modifying Your Configuration

After the initial configuration, you may want to reconfigure existing components or configure new ones, disable and re-enable components, add hosts, reconfigure routing, and so forth.

When making any configuration modifications, VSI recommends that you run the configuration procedure TCPIP$CONFIG again.

Note

You cannot use TCPIP$CONFIG to set up SLIP or PPP lines. See Chapter 3 for more information.

In some instances, TCPIP$CONFIG only partially configures a component (for example, when configuring a BIND name server). You may need to run additional setup programs or enter management commands to complete the configuration and fine-tune your environment.

Component-specific chapters in this manual describe additional configuration tasks and explain how to configure and manage specific components. These tasks may include:
  • Manually adding information, such as database records, that the configuration procedure cannot handle

  • Temporarily enabling or disabling a service

  • Configuring customized applications

  • Tuning performance

  • Troubleshooting

1.1.3. Saving Changes

The configuration procedure TCPIP$CONFIG saves configuration and initialization information in the file TCPIP$CONFIGURATION.DAT. You can modify the configuration dynamically or permanently, as follows:
  • SET commands modify the software dynamically, as it is running. Changes made in this manner are not saved permanently and are overwritten if they differ from settings in the permanent configuration database.

  • SET CONFIGURATION commands modify the permanent database but do not take effect until the next time the product starts up.

To make changes take effect immediately and modify permanent settings, enter both the interactive SET and permanent SET CONFIGURATION commands.

The following commands permanently modify the configuration database:
  • SET CONFIGURATION [NO]BIND

  • SET CONFIGURATION COMMUNICATION

  • SET CONFIGURATION ENABLE [NO]SERVICE

  • SET CONFIGURATION [NO]INTERFACE

  • SET CONFIGURATION [NO]NAME_SERVICE

  • SET CONFIGURATION NOMAP

  • SET CONFIGURATION PROTOCOL

  • SET CONFIGURATION SMTP

  • SET CONFIGURATION SNMP

  • SET CONFIGURATION START ROUTING


Note

Throughout this manual, all commands are assumed to be TCP/IP management commands. Any DCL commands that are mentioned are identified as such.

For a full description of the TCP/IP management commands and a discussion of how to use them, see the VSI TCP/IP Services for OpenVMS Management Command Reference manual.

1.1.4. Starting and Stopping the Software

To start TCP/IP Services manually, enter the following command:
$ @SYS$STARTUP:TCPIP$STARTUP

The startup procedure enables the configured services and initializes the configured network interfaces.

The TCPIP$STARTUP procedure has been modified to check the presence and installation of SSL3 images as recognized. If these checks fail, TCPIP$STARTUP will be unable to complete successfully, thus one of two error messages will be displayed.

If the required images are not found, you will get the following error message:

$ @sys$startup:tcpip$startup
%TCPIP-E-STARTFAIL, failed to start TCP/IP Services
-TCPIP-E-SSLNOTFOUND, required product SSL3 not found on system.

If SSL3$STARTUP has not been executed, thus the images are unrecognized, the following error message will be reported:

$ @sys$startup:tcpip$startup
%TCPIP-E-STARTFAIL, failed to start TCP/IP Services
-TCPIP-E-SSLNOTSTARTED, SSL3 has not been started.
To stop (shut down) the product manually, enter the following command:
$ @SYS$STARTUP:TCPIP$SHUTDOWN
The shutdown procedure does the following:
  1. Stops network communication

  2. Disables active services

  3. Deletes the network interface definitions

  4. Deassigns defined logical names

  5. Deletes installed images

To start TCP/IP Services automatically, add the following command to the system startup file:
$ @SYS$STARTUP:TCPIP$STARTUP.COM
To maintain site-specific startup and shutdown commands and settings, create the following files:
  • SYS$STARTUP:TCPIP$SYSTARTUP.COM

  • SYS$STARTUP:TCPIP$SYSHUTDOWN.COM

The site-specific startup procedure is invoked after all the TCP/IP services have been started. These files are not overwritten when you install a new version of TCP/IP Services.

VSI recommends that you use the TCPIP$CONFIG configuration procedure to stop and start services. However, startup and shutdown files are provided for individual services, allowing you to stop and start individual components without impacting the operation of the remaining TCP/IP Services software.

This feature allows you to modify a service configuration without restarting the TCP/IP Services product. For example, you can shut down the LPD service, change its configuration parameters, and then restart it, without interrupting the other TCP/IP services that are running on the system.

Each service is provided with its own startup and shutdown command procedures, as follows:
  • SYS$STARTUP:TCPIP$ service_STARTUP.COM, a supplied command procedure that ensures the environment is configured appropriately and starts up the component specified by service.

  • SYS$STARTUP:TCPIP$ service_SHUTDOWN.COM, a supplied command procedure that shuts down a specific service component without affecting the other services that are running.

To preserve site-specific parameter settings and commands for a specific service, create the following files, specifying the service or component name for service. These files are not overwritten when you reinstall TCP/IP Services:
  • SYS$STARTUP:TCPIP$ service_SYSTARTUP.COM can be used to store site-specific startup commands.

    This procedure is invoked by the appropriate service-specific startup procedure prior to running the service. Use the *_SYSTARTUP procedure to modify the behavior of the service each time the service or TCP/IP Services is restarted. For example, to enable debugging mode for DHCP, define the logical TCPIP$DHCP_DEBUG in the SYS$STARTUP:TCPIP$DHCP_SYSTARTUP.COM file. When DHCP next starts, it will run in debug mode.

  • SYS$STARTUP:TCPIP$ service_SYSHUTDOWN.COM can be used to store site-specific shutdown commands.

Service-specific startup and shutdown procedures, as well as configuration parameters, are described in the later chapters of this manual.

1.1.5. Editing Configuration Files

Several facilities can be managed using configuration options in a facility-specific configuration file. The following facilities support configuration files:
  • LPD/LPR

  • SMTP

  • IMAP

A configuration file is an ASCII text file consisting of one or more lines formatted as follows:
Field1: Value1 Field2: Value2
.
.
.
In this format:
  • Field names start in column 1, are terminated with a colon (:), and are not case sensitive.

  • Values vary depending on the field.

    If a value consists of a list of items, specify them on multiple lines by pressing the Tab key before continuing the value on the subsequent lines. For example:
    Field1: Item1,
    TabItem2,
    TabItem3
    Field2: Value2
    Or specify each value as a separate instance of the same field. For example:
    Field1: Item1
    Field1: Item2
    Field1: Item3
    An alternative format is:
    Field1: Item1, Item2, Item3

    The maximum number of characters in a value is 500. Unless otherwise noted, a field's value is not case sensitive.

    Fields described as Boolean have the following legal values:

    To turn the feature on

    To turn the feature off

    ON

    OFF

    TRUE

    FALSE

    1

    0

    YES

    NO

To comment out a line, type an exclamation point (!) in column 1.

1.2. Enabling PATHWORKS/Advanced Server and DECnet-over-TCP/IP Support

TCP/IP Services software includes the PATHWORKS Internet Protocol (PWIP) driver and the PWIP ancillary control process (PWIP_ACP).

The PWIP driver allows OpenVMS systems that are running both the VSI PATHWORKS/Advanced Server and the TCP/IP Services software to communicate with personal computers running PATHWORKS client software. It also enables the DECnet-over-TCP/IP feature, which is included with the DECnet-Plus for OpenVMS Version 6.0 and later software. For more information about DECnet over TCP/IP, see the DECnet-Plus for OpenVMS documentation.

1.2.1. Starting and Stopping the PWIP Driver

The PWIP driver can be shut down and started independently. The following files are provided:
  • SYS$STARTUP:TCPIP$PWIP_DRIVER_STARTUP.COM allows you to start up the PWIP driver.

  • SYS$STARTUP:TCPIP$PWIP_DRIVER_SHUTDOWN.COM allows you to shut down the PWIP driver.

To preserve site-specific parameter settings and commands, create the following files. These files are not overwritten when you reinstall TCP/IP Services.
  • SYS$STARTUP:TCPIP$PWIP_DRIVER_SYSTARTUP.COM can be used as a repository for site-specific definitions and parameters to be invoked when the PWIP driver is started.

  • SYS$STARTUP:TCPIP$PWIP_DRIVER_SYSHUTDOWN.COM can be used as a repository for site-specific definitions and parameters to be invoked when the PWIP driver is shut down.

To start the PWIP driver, run TCPIP$CONFIG or enter the following command:
$ @SYS$STARTUP:TCPIP$PWIP_DRIVER_STARTUP.COM
To shut down the connection to the PWIP driver, enter the following command:
$ @SYS$STARTUP:TCPIP$PWIP_DRIVER_SHUTDOWN.COM

1.3. Setting Up User Accounts and Proxy Identities

You will need to set up accounts for local users, coordinate the establishment of corresponding accounts on remote systems, and create accounts for remote users who will be accessing server components on the local host.

When creating accounts for remote users, you can create one account for all remote users, an account for groups of remote users, or accounts for individual users. The strategy you use depends on your organization, system resources, and security needs.

Certain product components (for example, LPD, RSH, RLOGIN, and NFS) act as servers for remote clients. You control access to your system and to these services by giving remote users proxy identities. A proxy identity maps a user account on one host to an account on another host. The information you provide with each entry, along with the privileges you set for the account, lets you specifically grant or deny access to your system.

The configuration procedure TCPIP$CONFIG creates a proxy database file called TCPIP$PROXY. You add proxies to this database with the ADD PROXY command. The TCP/IP Services product allows the following two types of proxies:
  • Communication proxy

    A communication proxy provides an identity for remote users of RSH, RLOGIN, RMT/RCD, and LPD. For each host, be sure to define the host name and any aliases. Proxy entries are case sensitive. Be sure to use the appropriate case when adding entries for remote users. Enter the ADD PROXY command as follows:
    TCPIP> ADD PROXY user /HOST=host /REMOTE_USER=user
    
    You can use wildcards when adding proxy entries for users on remote systems. For example, the following command provides the identity STAFF to any user on the remote host STAR:
    TCPIP> ADD PROXY STAFF  /HOST=STAR /REMOTE_USER=*
  • NFS proxy

    NFS proxies provide identities for users of NFS client, NFS server, and PC-NFS. In addition to host and user information, NFS proxies provide UNIX identities with UID/GID pairs. NFS proxies can specify access to the NFS client or the NFS server, or both.

    For example, the following command provides the OpenVMS identity CHESTER for a local NFS client user with the UID/GID pair 23/34.
    TCPIP> ADD PROXY CHESTER /NFS=OUTGOING /UID=23 /GID=34 /HOST="orbit"
    

    This user can access remote files from the NFS server orbit.

See the VSI TCP/IP Services for OpenVMS Management Command Reference manual for a complete description of the ADD PROXY command. For a more complete discussion about UNIX style identities and how the NFS server and client use the proxy database, see Chapter 20.

1.4. Configuring a TCP/IP Cluster

If your host is part of an OpenVMS Cluster, you can use a cluster alias to represent the entire cluster or selected host members. In this case, the network sees the cluster as a single system with one name. Alternatively, you can configure clustering using a DNS alias, as described in Chapter 6.

Incoming requests are switched among the cluster hosts at the end of each cluster time interval (specified with the SET COMMUNICATION command).

Note

The cluster name is not switched from a host if there are any active TCP connections to the cluster interface on that host.

A remote host can use the cluster alias to address the cluster as a single host or the host name of the cluster member to address a cluster member individually.

All of the TCP/IP services support automatic failover and can be run on multiple nodes in an OpenVMS Cluster. For example, if more than one host in the cluster is running the NFS server, the cluster can appear to the NFS client as a single host. For more information about configuring a specific service for cluster failover, refer to the chapter in this manual that discusses the particular service.

1.4.1. Setting Up an ARP-Based Cluster

VSI strongly recommends using the configuration procedure TCPIP$CONFIG to configure a TCP/IP cluster. If you cannot run TCPIP$CONFIG, configure a TCP/IP cluster by completing the following steps:
  1. Create the interfaces for all cluster members.

  2. Interactively specify an ARP-based cluster alias (for example, ALLOFUS). Enter:
    TCPIP> SET INTERFACE QE0 /CLUSTER=ALLOFUS  /C_NETWORK=255.255.0.0 -
    _TCPIP> /C_BROADCAST=128.44.55.0
    
  3. Make these settings permanent in the configuration database. Enter:
    TCPIP> SET CONFIGURATION INTERFACE QE0 /CLUSTER=ALLOFUS - 
    _TCPIP> /C_NETWORK=255.255.0.0 /C_BROADCAST=128.44.55.0
    

    The interface changes take effect the next time the product starts up.

  4. Add the cluster host name or the cluster IP address to the database of the host. Enter the same information you use with the SET INTERFACE command.

  5. Change the interface parameters (specified with the SET INTERFACE command) only after deleting and re-creating an interface.

1.5. Auxiliary Server

The auxiliary server is the TCP/IP Services implementation of the UNIX internet daemon (inetd). In addition to standard inetd functions, the auxiliary server provides access control and event logging.

The auxiliary server listens continuously for incoming requests and acts as a master server for programs specified in its configuration file. The auxiliary server reduces the load on the system by invoking services only as they are needed.

1.5.1. How the Auxiliary Server Works

The auxiliary server listens for connections on the internet addresses of the services that its configuration file (TCPIP$SERVICES.DAT) specifies. When a connection is found, it invokes the server daemon for the service requested. Once a server is finished, the auxiliary server continues to listen on the socket.

When it receives a request, the auxiliary server dynamically creates a network process, obtaining user account information from one or all of the following sources:
  • TCP/IP Services proxy account

  • Services database

  • Remote client

  • Local OpenVMS user authorization file (UAF)

In addition, users requesting services at the client can include their user account information as part of the command line.

Once a process is created, the auxiliary server starts the requested service. All services except RLOGIN and TELNET must have access to their default device and directories and to the command procedures within them.

1.5.1.1. Rejecting Client Requests

The auxiliary server rejects client requests for the following reasons:
  • The maximum number of simultaneous processes for the requested service has been reached.

  • The request is from a host that is marked for rejection.

  • There is a problem with the target account or directory.

1.5.1.2. Configuring the Auxiliary Server

The postinstallation configuration procedure, TCPIP$CONFIG, creates an entry in the services database (TCPIP$SERVICE.DAT) for each service you configure. If you need to modify your initial configuration, run TCPIP$CONFIG or use the SET SERVICE command.

The configuration file TCPIP$SERVICE.DAT includes information about the service name, the socket and protocol type associated with the service, the user name under which the service should run, and any special options for the service program.

Before you activate a service manually, configure the auxiliary server as follows:
  1. Use the OpenVMS Authorize utility to create a restricted user account for the process. Use the following qualifiers when creating the account:
    • /NOINTERACTIVE

    • /NOBATCH

    • /NOREMOTE

    • /FLAGS=(RESTRICTED,NODISUSER,NOCAPTIVE)

    For more information about creating restricted accounts, see the OpenVMS system security documentation.

  2. Provide user account information that can be used when the network process is created. Plan your requirements carefully before setting privileges, quotas, and priorities to user accounts.

  3. Provide the network process name.

    The auxiliary server builds the network process name from the character string in the services database. Enter this string with the SET SERVICE command:
    TCPIP> SET SERVICE service /PROCESS_NAME=process

    Note

    For TELNET and RLOGIN, the process name is set by either the system or users.

  4. Set the maximum number of server processes that can run simultaneously. This number should not exceed the maximum number of sockets allowed on the system. To set the maximum number of processes that can connect to a service at the same time, enter the following TCP/IP management command:
    TCPIP> SET SERVICE service-name /LIMIT=n

    In this command, service-name is the name of the service to which the connections will be limited, and n is the number of connections that will be accepted by the service at one time.

    To activate the change, disable the service using the DISABLE SERVICE command, and then enable it using the ENABLE SERVICE command.

  5. Make sure that the protections in the systemwide SYLOGIN.COM file are set appropriately. If they are not, enter the following DCL command:
    $ SET PROTECTION=(W:RE) SYS$MANAGER:SYLOGIN.COM
    
  6. To ensure that the services database has an entry for each service offered, enter the SHOW SERVICE command.

1.6. Enabling Services

The services you configured are enabled during the TCP/IP Services startup procedure. Afterwards, to initialize (enable) a service, enter the following command:
TCPIP> ENABLE SERVICE

The ENABLE SERVICE command immediately changes the running system. The SET CONFIGURATION ENABLE SERVICE command causes the services to be enabled the next time TCP/IP Services starts up.

To specify the type of socket, include the /PROTOCOL qualifier on the SET SERVICE command line. For example, to specify stream sockets, enter /PROTOCOL=TCP. To specify datagram sockets, enter /PROTOCOL=UDP.

The auxiliary server can set socket options for a requested service either before or during data communications. Some available options are:
  • KEEPALIVE (for TCP communications)

  • BROADCAST (for UDP communications)

To set the socket options, include the /SOCKET_OPTIONS qualifier on the SET SERVICE command.

1.6.1. Setting Up Event Logging

Event logging can help you manage the software. By default, user-defined services do not log events, but you can enable event logging for all or selected configured services. You can configure the product to log events to the operator's console, a log file, or both. To set up event logging, enter the following command:
TCPIP> SET SERVICE service-name /LOG_OPTIONS=ALL

For a list of all the logging options, see the SET SERVICE command description in the VSI TCP/IP Services for OpenVMS Management Command Reference manual.

Some product components provide additional event logging capabilities. See individual component chapters for more information.

Chapter 3. Configuring and Managing Serial Lines

A serial connection is made between two systems using modems and telephone lines or other serial lines. TCP/IP Services supports serial connections using the PPP (Point-to-Point Protocol) and SLIP (Serial Line IP) protocols. SLIP includes CSLIP (compressed SLIP). You can use any standard OpenVMS terminal device as a PPP or SLIP line. (PPP is available for OpenVMS Alpha systems only.)

This chapter reviews key concepts and describes:

3.1. Key Concepts

If your OpenVMS system is part of a large network, you will probably use both PPP and SLIP for your serial connections. As an Internet standard, PPP is often preferred because it ensures interoperability between systems from a wide variety of vendors. PPP provides a way for your OpenVMS Alpha system to establish a dynamic IP network connection over a serial line without an additional router or additional server hardware.

SLIP has been in use for a longer period of time and is available for most terminal servers and in most PC implementations of TCP/IP. Because SLIP and PPP do not communicate with each other, hosts wanting to communicate must use the same protocol. For example, if your terminal server supports only SLIP, remote hosts that connect through this server must also use SLIP.

3.1.1. PPP and SLIP

One of the largest applications for IP over serial lines is dialup access. With this type of configuration, the OpenVMS host answers calls and establishes a connection initiated by a user on a client host. The client host can be another OpenVMS system, a UNIX system, or a PC. Or users on the host can originate the dialup connection to a remote host or terminal server running the same protocol.

Dedicated serial lines running PPP or SLIP can also be used to connect separate LANs into a single WAN. In such a configuration, the host at each end of the serial connection is always the same; no other hosts are allowed to connect to either serial device.

3.1.2. Assigning an IP Address to Your PPP or SLIP Interface

Every network interface must have its own unique IP address. Interfaces cannot share IP addresses.

If you configure PPP interfaces for multiple remote hosts, the remote hosts can obtain their individual IP addresses from your host when they connect. Similarly, you can configure a PPP interface on your system without knowing your own IP address and obtain it when you connect to a remote system.

Before establishing SLIP communication with a remote host, however, you must obtain the IP address for the host's serial interface and assign IP addresses for each interface you configure on the local host.

When using SLIP, consider placing each serial line in a separate subnetwork. You accomplish this by assigning the same subnet mask for the interfaces at either end of the link.

If you need to use an address in the same subnetwork as your site LAN, use the proxy Address Resolution Protocol (ARP) feature (see Section 3.3.4).

3.1.3. Serial Line Internet Protocol

SLIP sends a datagram across the serial line as a series of bytes. It uses the following characters to determine when a series of bytes should be grouped together:

Character

Function

Hex Value

Decimal Values

END

Marks the end of the datagram. When the receiving SLIP encounters the END character, it knows that it has a complete datagram.

C0

192

ESC

Indicates the end of the SLIP control characters.

DB

219

The SLIP starts by sending an END character. If END is encountered within the datagram as data, the SLIP inserts an escape character, sending the two-character sequence DB DC instead. If the ESC character appears within the datagram as data, it is replaced with the two-character sequence DB DD. The datagram ends with the END character after the last byte in the packet is transmitted.

There is neither a standard SLIP specification nor a defined maximum packet size for the SLIP. The TCP/IP Services implementation of SLIP accepts 1006-byte datagrams and does not send more than 1006 bytes in a datagram.

Compressed SLIP provides header compression that is beneficial for small packets and low-speed serial links. Header compression improves packet throughput. You can enable the CSLIP by means of the /COMPRESS qualifier when you enter a SET INTERFACE command. See Table 3.3 for more information.

3.1.4. Point-to-Point Protocol

PPP uses a frame format that includes a protocol field. The protocol field identifies the protocol (for example, IP, DECnet, or OSI) to be used for communication between the two hosts. The PPP defines the network frame in a 5-byte header and 3-byte trailer. A PPP frame starts and ends with the control byte 7E hex (126 decimal). The address and control bytes are constant. The 2-byte protocol field indicates the contents of the PPP frame.

3.2. Setting Up a PPP Interface (Alpha Only)

Use the following commands to configure a PPP interface on an OpenVMS Alpha system:
  • SET INTERFACE PP n, where n is the number of the interface, takes effect immediately and stays in effect until the next TCP/IP Services shutdown.

  • SET CONFIGURATION INTERFACE PP n, where n is the number of the interface, makes the change part of the permanent configuration and takes effect at the next TCP/IP Services startup.


Note

Specifying PP without the interface number is equivalent to specifying PP0.

If you enter a SHOW INTERFACE command, the address does not appear until a PPP connection is actually established.

Table 3.1 shows the command qualifiers used for configuring PPP interfaces.
Table 3.1. Configuring PPP Interfaces

Qualifier

Description

/COMPRESS=[ON |OFF |AUTOMATIC]

Optional. The default is ON. Use to negotiate header compression.

/DESTINATION=[ host_name | IP_address]

Optional. The default is no destination host. If you do not specify the client host's address, the PPP obtains the correct address from the client host.

If the host is used as a dialup provider, use this command to specify a unique IP address for a client. In this case, you must also specify your host address with the /HOST qualifier.

/HOST=[ host_name | IP_address]

Required when setting up a host as a dialup provider; otherwise optional. Host name or IP address using the interface. If your host is multihomed, specify the unique IP address if the two IP addresses map to the same host name.

/NETWORK_MASK= IP_address

Optional. The subnet mask of the local PPP interface in dotted-decimal notation.

/SERIAL_DEVICE= device

Required for hard-wired or dedicated modem connections. Identifies the OpenVMS device name assigned to the PPP interface, for example, TTA1.

3.2.1. Setting Up Your Host for PPP Connections

In the client/server model for PPP connections, a host can function as a server, or dialup provider, to respond to incoming PPP connection requests. A host can also function as a client dialing in to a dialup provider.
  • A PPP dialup provider answers modem calls from PPP clients, assigns IP addresses, and establishes PPP connections initiated by client hosts.

    Typically, a PPP dialup provider is permanently connected to the network through an interface such as Ethernet. The dialup provider services PPP clients that initiate temporary, dialup connections because they do not have permanent connections.

  • A PPP client establishes a temporary PPP connection to a dialup provider or a terminal server.

    Note

    For information about establishing a PPP client connection from a UNIX system, refer to the UNIX documentation. For a connection from a PC, refer to the PC's dialup networking instructions. You will need to configure your modem correctly as outlined in the Section 3.2.1.2.

Setting up an OpenVMS Alpha host as a PPP dialup provider or client involves a series of tasks. These tasks are listed in Table 3.2 in the order you should complete them, and are explained in Sections 3.2.1.1 through 3.2.1.6.
Table 3.2. Set Up Tasks Required for an OpenVMS Alpha PPP Dialup Provider or Client

Step

Task

OpenVMS Dialup Provider

OpenVMS Client

1

Install the correct terminal driver.

Yes

Yes

2

Configure your modem.

Yes

Yes

3

Set up an asynchronous port for modem connections.

Yes

Yes

4

Configure an interface for a serial PPP connection.

Yes

Optional

5

Enable IP forwarding and dynamic routing, as appropriate.

Yes

No

6

Initiate a PPP connection. NETMBX and OPER privileges required.

No

Yes

3.2.1.1. Installing the Terminal Driver

Confirm that the virtual terminal driver SYS$LOADABLE_IMAGES:SYS$TTDRIVER.EXE is installed on your host. If it is not installed, run the System Management utility (SYSMAN), connect the device, and load the driver, as shown in the following example:
$ RUN SYS$SYSTEM:SYSMAN

SYSMAN> IO CONNECT VTA0 /NOADAPTER /DRIVER=SYS$TTDRIVER
SYSMAN> EXIT

After you run SYSMAN, confirm that the VTA0 device was created. For more information about SYSMAN and its parameters, see the VSI OpenVMS System Management Utilities Reference Manual, Volume 2: M-Z.

For OpenVMS Alpha Version 7.1, you must also install the ASNDRIVER remedial kit to prevent the system from crashing. To obtain the driver and associated corrections, access a remedial kit and accompanying cover letter from:
http://ftp.service.digital.com/public/vms/axp/v7.1/alppppd01_071.A-DCX_AXPEXE
http://ftp.service.digital.com/public/vms/axp/v7.1/alppppd01_071.CVRLET_TXT

3.2.1.2. Configuring the Modem

To configure the modem, follow these steps:
  1. Make sure the serial port and modem cable support modem control signals. (VSI's BC22F cable is an example of such a cable.)

  2. Determine whether there are any baud rate restrictions associated with your phone line or on your connecting cable (when using a null modem or modem eliminator).

  3. Adjust the settings on your modem to enable AT commands, as appropriate for your modem. Some modems require you to set DIP switches, while others require you to specify software settings.

    Sample DIP switch configuration settings for U.S. Robotics Courier modems are as follows. Note the following designations in these samples:
    • X = setting on (although different settings might work)
    • X** = setting on (required)
    Dialup provider settings:
    DTR normal                X**     DTR always on               
    Verbal result codes       X       Numeric results codes
    Suppress result codes     X**     Display result codes        
    Echo offline commands     X       No echo offline commands
    Auto answer on ring       X**     Suppress auto answer        
    Normal carrier detect     X**     Carrier detect override     
    Display all results codes X       Result codes orig. mode only
    Disable AT command set            Enable AT command set       X
    Disconnect with +++               No disconnect with +++      X
    Load NVRAM defaults       X       Load &FO settings
    Client settings (defaults):
    DTR normal                X     DTR always on
    Verbal result codes       X     Numeric results codes
    Suppress result codes           Display result codes        X
    Echo offline commands     X     No echo offline commands
    Auto answer on ring             Suppress auto answer        X
    Normal carrier detect     X     Carrier detect override
    Display all results codes X     Result codes orig. mode only
    Disable AT command set          Enable AT command set       X**
    Disconnect with +++       X     No disconnect with +++
    Load NVRAM defaults       X     Load &FO settings
  4. If possible, also configure the modem so that it does not assert the Data Terminal Ready (DTR) signal until it asserts the Carrier Detect (CD) signal. This configuration ensures that the terminal driver does not drop the DTR signal prematurely.

3.2.1.3. Setting Up an Asynchronous Port

Use the DCL command SET TERMINAL and applicable qualifiers to set up an asynchronous port for use with the modem.
  • Setting up the PPP dialup provider

    Enter the SET TERMINAL command and qualifiers appropriate for your modem connection. (Note that some qualifiers require LOG_IO or PHY_IO privilege, or both.) For example:
    $ SET TERMINAL TTA0: /ALTYPEAHD /AUTOBAUD /DIALUP /DISCONNECT /EIGHTBIT -
    _$ /MODEM /NOHANGUP /NOHOSTSYNC /NOPASTHRU /NOREADSYNCH /NOTTSYNCH -
    _$ /PERMANENT /TYPE_AHEAD
    Where:

    /ALTYPEAHD

    Creates a permanent, alternate type-ahead buffer. (The system parameter TTY_ALTYPADH determines the size of the type-ahead buffer.) Helpful when transferring larger files. This qualifier is required.

    /AUTOBAUD

    Detects the incoming baud rate.

    /DIALUP

    Specifies that the terminal is a dialup terminal. This qualifier is required.

    /DISCONNECT

    Ensures that the process is disconnected if the line detects a hangup.

    /EIGHTBIT

    Sets the terminal to use the 8-bit ASCII format. This qualifier is required.

    /MODEM

    Specifies the use of a modem. This qualifier is required.

    /NOHANGUP

    Does not hang up the modem when the client logs off. This is the default. This qualifier is required.

    /NOHOSTSYNC

    Does not allow the use of Ctrl/S or Ctrl/Q functions from the terminal to stop or resume transmission when the input buffer is full or empty. This is the default.

    /PASTHRU

    The terminal passes format-type data, such as carriage returns and tabs, to an application program as binary data. This is the default.

    /NOREADSYNCH

    Does not allow the use of Ctrl/S or Ctrl/Q functions to synchronize data transmitted from the terminal. This is the default.

    /NOTTSYNCH

    Does not allow transmission to be stopped or resumed by entering Ctrl/S or Ctrl/Q, respectively.

    /PERMANENT

    Saves the settings.

    /TYPE_AHEAD

    Enables remote modems. Must be set. The terminal accepts unsolicited input to the limit of the type-ahead buffer. This is the default.

    For detailed information about these and other SET TERMINAL qualifiers, see the VSI OpenVMS DCL Dictionary: N-Z.

  • Setting up the PPP client (OpenVMS Alpha only)

    Enter the SET TERMINAL command and qualifiers appropriate for your connection, as listed for the dialup provider, with the exception of /AUTOBAUD.

    Set the baud rates using the /SPEED=(input-rate,output-rate) qualifier. If the rates are the same, specify /SPEED= rate (for example, /SPEED=9600).

3.2.1.4. Configuring a PPP Interface

  • Configuring the PPP dialup provider

    Use the SET INTERFACE command and qualifiers to configure the interface for a serial PPP connection and assign a host name, IP address, network mask, and IP address for the client host, as applicable:
    TCPIP> SET INTERFACE PP
    n /SERIAL_DEVICE=TT
    n: /HOST=
    IP_address -
    _TCPIP> /NETWORK_MASK=
    IP_address /DESTINATION=
    IP_address /COMPRESS=AUTO
    In this command:
    • n is the controller name and unit number.

    • The /HOST address is the IP address.

    • The /NETWORK_MASK IP address is required if your network uses subnets.

    • The /DESTINATION address is the IP address assigned to the client host making a connection request. This address always overrides the client's own IP address, if the client has one.

    • /COMPRESS=AUTO turns off IP header compression unless the client uses it.

  • Configuring the PPP client (OpenVMS Alpha only) (Optional)

    Use the SET INTERFACE command and /HOST qualifier to assign an IP address:
    TCPIP> SET INTERFACE PP
    n /SERIAL_DEVICE=TT
    n: /HOST=
    IP_address

    In this command, n is the interface number. If you omit the interface number, PP0 is used.

    If you do not specify your host's IP address using SET INTERFACE, the dialup provider or terminal server provides an IP address after the connection is established.

    Note

    If the connecting client host has only a loopback and tunnel interface defined:
    1. A default route to the PPP interface is added to the routing table when the connection is established.

    2. The IP address of the PPP interface is assigned to the logical names TCPIP$INET_HOSTADDR and UCX$INET_HOSTADDR (for backward compatibility).

3.2.1.5. Enabling IP Forwarding (Dialup Provider Only)

Enter the following command to enable IP forwarding:
TCPIP> SET PROTOCOL IP/FORWARD
To enable IP forwarding in the configuration database, enter the following command:
TCPIP> SET CONFIGURATION PROTOCOL IP/FORWARD
Alternatively, use the sysconfig utility. First, define the TCP/IP Services foreign commands:
$ @SYS$MANAGER:TCPIP$DEFINE_COMMANDS.COM
Enter the following sysconfig commands:
$ sysconfig -r inet ipforwarding=1 
$ sysconfig -r inet ipgateway=1
$ sysconfig -q inet

Note

These changes affect the running system only. To make permanent changes to the system, modify the TCPIP$ETC:SYSCONFIGTAB.DAT database as described in the VSI TCP/IP Services for OpenVMS Tuning and Troubleshooting guide.

To send notifications automatically on all connected LANs when new hosts or networks become reachable, use dynamic routing with the /SUPPLY option. For example, every time a PPP link is set up to a new subnetwork, RIP (Routing Information Protocol) advertises a corresponding route.

For example, enter the following commands:
TCPIP> START ROUTING /SUPPLY
TCPIP> SET CONFIGURATION START ROUTING /SUPPLY 

If your PPP and Ethernet interfaces are in the same network, a route is created automatically for the client hosts and an ARP proxy is advertised.

3.2.1.6. Initiating a PPP Connection

You use the OpenVMS PPP utility (PPPD) and associated commands to establish and manage a temporary PPP connection from an OpenVMS Alpha client host to an OpenVMS dialup provider or terminal server. Note that NETMBX and OPER privileges are required to establish a successful connection and to display OPCOM messages.

To invoke PPPD, enter the DCL command PPPD. The PPPD commands are summarized in the following table. For detailed information about PPPD commands and qualifiers, enter the HELP command.

Command

Function

CONNECT

Establishes a network connection through the current physical port or a specified remote port.

DIAL_OUT

Allows direct access to a device in order to dial out over a modem or link to an external device.

DISCONNECT

Terminates the network connection and returns control to the terminal driver.

EXIT

Leaves the utility and returns you to the DCL command prompt ($).

HELP

Displays help text for PPPD commands.

SET

Determines the device and line characteristics for the specified terminal.

SHOW

Displays the device and line characteristics of the specified terminal.

To initiate a PPP connection from an OpenVMS Alpha client to an OpenVMS dialup provider or terminal server, follow these steps.
  1. Confirm that you have NETMBX and OPER privileges.

  2. Use the PPPD command DIAL_OUT and specify the terminal device. After the atdt command, enter the telephone number of the dialup provider or terminal server. (With some modems, you might need to type the number again until dialing begins.)

    For example:
    $ PPPD 
    
    PPPD> DIAL_OUT TTA0
    
    Type control-~ to send a break
         control-\ to disconnect
         control-@ to switch to a Point-to-Point connection.
    
    atdt 8671234
  3. If you are connecting to another OpenVMS system, log in to the system after you dial up, and enter the following commands to establish the connection:
    $ PPPD
    PPPD> CONNECT

    To end the connection, enter the DISCONNECT TT n command at the PPPD> prompt and log out.

  4. If you are connecting to a terminal server, enter the CONNECT PPP prompt at the LOCAL> prompt. An informational message will confirm the PPP connection:
    LOCAL> CONNECT PPP
    
    Local -561- Starting SLIP or PPP datalink session
    %PPPD-I-CONNECTTERM, converting connection on device _TTA0: to a
    Point-to-Point connection
    To end the connection, enter DISCONNECT TT n at the PPPD> prompt. After the connection is terminated, an OPCOM message is displayed. For example:
    %%%%%%%%%%%  OPCOM   23-APR-1998 15:44:32.10  %%%%%%%%%%%
    Message from user XYZnet on JONES
    %TCPIP-S-PPPDISCONN, Disconnected  PPP Interface PP1 on TTA0

3.2.2. Removing the PPP Configuration

To remove the PPP configuration, follow these steps:
  1. If you created a PPP interface, return the associated terminal port to general use. Enter:
    TCPIP> SET NOINTERFACE PPn

    In this example, n is the number of the interface. If you omit the interface number, PP0 is assumed.

  2. If you added special route and proxy entries with the PPP line, remove them.

  3. If you changed any terminal settings in preparation for PPP, restore them. Enter the DCL command SET TERMINAL, and wait for the modem to reset and free the port and phone line.

3.3. Setting Up a SLIP Interface

Configuring the network interface for SLIP is the same as configuring the interface for Ethernet connections. In this case, the network interface is the modem connection. Remember that before you can configure a SLIP line, you must choose an IP address for the interface at each end of the line and establish a physical connection.

Use the following commands to set up the SLIP interface:
  • SET INTERFACE SLn, where n is the number of the interface. If you omit the interface number, SL0 is assumed. This command takes effect immediately and stays in effect until the next TCP/IP Services shutdown.

  • SET CONFIGURATION INTERFACE SLn, where n is the number of the interface. If you omit the interface number, SL0 is assumed. This command makes the change part of the permanent configuration. The change takes effect at the next product startup.

Table 3.3 describes the command qualifiers used for configuring SLIP interfaces.
Table 3.3. Command Qualifiers Used for Configuring SLIP

Qualifier

Description

/[NO]AUTO_START

Optional. The default is /AUTO_START. Automatically creates the interface on startup.

/COMPRESS=[ON |OFF |AUTOMATIC]

Optional. The default is no compression. Enables or disables TCP header compression (CSLIP). With /COMPRESS=AUTOMATIC, compression remains off unless the remote host begins to use it.

/[NO]FLOWCONTROL

Optional. The default is No flow control. Enables the special handling of XON and XOFF characters to work properly with modems that are configured to interpret these characters locally.

Specify /FLOWCONTROL only if the host at the other end of the line is another host running TCP/IP Services. If you cannot use /FLOWCONTROL, configure your modem to pass all the XON and XOFF characters through transparently.

/HOST=(host_name, IP_address)

Required. Host name or IP address of the local host. If your host is multihomed, you must specify an address in dotted-decimal notation.

/NETWORK_MASK= subnet_address

Required. The subnet mask of the local SLIP interface in dotted-decimal notation.

/SERIAL_DEVICE= device

Required for hard-wired or dedicated modem connections. Optional for dynamic connections.

Identifies the OpenVMS device name assigned to the SLIP interface, for example, TTA1.

For example, the following command configures SLIP interface SL5, using the local IP address assigned to host CROW, with a subnetwork mask of 255.255.255.0. The interface uses the terminal device TTA3:. The /COMPRESS qualifier enables TCP header compression (CSLIP). The /FLOWCONTROL qualifier enables special handling of XON and XOFF characters.
TCPIP> SET INTERFACE SL5 /HOST=CROW /NETWORK_MASK=255.255.255.0 -
_TCPIP> /SERIAL_DEVICE=TTA3 /COMPRESS=ON /FLOWCONTROL

3.3.1. Setting Up Hard-Wired SLIP Lines

To configure SLIP with hard-wired lines, follow these steps:
  1. Establish a physical connection. Plug in a serial cable between the two host systems or ensure that they are both cabled to opposite ends of a leased line.

  2. Obtain an IP address if necessary.

  3. Configure the SLIP interface. Enter the SET INTERFACE command with the /HOST and /SERIAL_DEVICE qualifiers, which are required.

3.3.2. Setting Up SLIP Dialup Lines

You can configure either a terminal server port or an OpenVMS system to answer dialin calls.

Follow these steps:
  1. Configure the appropriate settings for the terminal port to which you will connect. Begin a dialog of dialing (or answering) commands with your modem. The specific required commands depend on the type of modem you are using.

    For example, to prevent the modem from hanging up when you exit the DTE session to bring up the SLIP line, enter the following command:
    $ SET TERMINAL TTA2 /PERMANENT /MODEM /NOHANGUP
    To disable interactive logins on the line, enter the following command:
    $ SET TERMINAL TTA2 /PERMANENT /NOTYPEAHEAD

    Any SLIP data that arrives before you enter the SET INTERFACE command is ignored. Otherwise, this command triggers the creation of a new interactive login process.

    To enable interactive logins after a user sends a Break, enter the following command:
    $ SET TERMINAL TTA2 /PERMANENT /NOAUTOBAUD /SECURE_SERVER
  2. Configure the modem. Enter the appropriate commands to dial the telephone and establish communication.

  3. Unless you are setting up a SLIP line between two hosts running TCP/IP Services and plan to use the /FLOWCONTROL qualifier at both ends, disable modem recognition of XON and XOFF characters. (If SLIP packets have Ctrl/S and Ctrl/Q characters embedded in them as data, you must prevent the modem from trying to interpret these characters.)

    Either use hardware flow control or disable flow control entirely. The following examples disable all flow control.
    • With a DECmodem V32 in AT command mode, set the following values:
      • AT%F0 — No speed buffering flow control

      • AT%M0 — Disable speed buffering (optional)

    • With a DECmodem V32 in DMCL mode, set the following values:
      • SET P2/SBU

      • SET P1/SBU

      • prompts appropriate_answers
    • With a U.S. Robotics Sportster modem, set the following values:
      • AT&B0 — Variable, follows connection rate (optional)

      • AT&H0 — Flow control disabled

      • AT&I0 — Software flow control disabled

  4. Obtain IP addresses if necessary.

  5. To dial in, follow these steps:
    1. Enter the SET HOST /DTE command:
      $ SET HOST /DTE TTnx
    2. Type the telephone number. For example:
      atdt telephone_number
    3. The connected system displays its interactive (command mode) prompt. You are talking to the terminal server and can now make the connection.

The following example shows a user named SLIP-USER at a PC named ROBIN with a 9600-baud modem, using terminal device TTA2 and connecting it to the port of a terminal server. In this example:
  • The terminal server is a DECserver 700 terminal server.

  • The user directs the modem to dial the telephone number 222-2222.

  • The password prompt of the terminal server is #.

  • The terminal server's current login password is hootowl.

  • The terminal server's prompt is Local>.

  • The user types Ctrl/\ (Ctrl key plus backslash) to escape from the terminal server to the SLIP host.

  • The user defines interface SL2 and identifies it as SLIP device TTA1: with IP address 1.2.3.4. Communication on this line will use CSLIP.


$ SET HOST /DTE TTA2

%REM-I-TOQUIT, connection established
Press Ctrl/\ to quit, Ctrl/@ for command mode 

atdt 2222222

CONNECT 9600

# hootowl (not echoed)

Network Access SW V1.5 for DS700-16 
(c) Copyright 1994, Digital Equipment Corporation - All Rights Reserved
Please type HELP if you need assistance

Enter username>SLIP-USER

Local> CONNECT SLIP
Ctrl/\ 

TCPIP> SET INTERFACE SL2 /HOST=1.2.3.4 /NETWORK_MASK=255.255.255.0 - 
_TCPIP> /SERIAL_DEVICE=TTA1: /COMPRESS=ON

3.3.3. Setting Up Your Host as a SLIP Dialup Provider

You can configure your host to answer calls and establish connections initiated by users on remote hosts.

To set up your host as a SLIP provider:
  1. Over the line you will define as a SLIP line, dial in to the host.

  2. Log in to the remote host.

  3. Enter an appropriate SET INTERFACE command with the /SERIAL_DEVICE qualifier to turn the line into a SLIP line.

    For example, the following command creates a SLIP interface named SL5, using the terminal device associated with the session where the command is entered.
    TCPIP> SET INTERFACE SL5 /HOST=192.208.35.5 /SERIAL_DEVICE=TT
  4. Log out.

As soon as you log out, your terminal port becomes a SLIP interface. Without causing the modem to hang up, start SLIP on the remote system.

To facilitate connection setup for end users, create a dedicated user name for each remote host that dials in. These users need to have a LOGIN.COM procedure that invokes appropriate SET TERMINAL commands and TCP/IP management SET INTERFACE commands, terminating with a LOGOUT command. Every user should specify a different SLIP interface name and host name (or IP address). These users require the OPER privilege to create interfaces.

You can enable IP forwarding on the SLIP provider host and start dynamic routing. For example, enter the following commands:
TCPIP> SET PROTOCOL IP /FORWARD

TCPIP> SET CONFIGURATION PROTOCOL IP /FORWARD
To send notifications automatically on all connected LANs when new hosts or networks become reachable, use dynamic routing with the /SUPPLY option. For example, every time a SLIP connection is set up to a new remote subnetwork, RIP (Routing Information Protocol) advertises a corresponding route. For example, enter the following commands:
TCPIP> START ROUTING /SUPPLY

TCPIP> SET CONFIGURATION START ROUTING /SUPPLY

3.3.4. Connecting a Host to the LAN

You can make your SLIP-connected host appear as if it were directly connected to the LAN. This is possible using a proxy ARP server (usually the same host that is acting as a SLIP gateway into the LAN).

To use proxy ARP (Address Resolution Protocol), assign to the remote host an IP address in the same subnetwork as the LAN. As other hosts on the LAN attempt to communicate with the remote host, the SLIP gateway answers ARP queries for the remote host by giving its own LAN address. The gateway then forwards packets across the SLIP line.

Many DECserver terminal server products support SLIP connections and implement proxy ARP. If you dial in from an OpenVMS host to a terminal server, the terminal server automatically detects your IP address and begins responding to ARP queries, forwarding packets as necessary.

To use proxy ARP with a DECserver terminal server, assign an IP address in the same subnetwork as the terminal server.

At the terminal server, enter the TCP/IP management command SHOW PORT SLIP. Verify that:
  • An IP address has not already been associated with your port.

  • Header compression is available, if you plan to use it.

3.3.5. Setting Up a SLIP Gateway with Proxy ARP

It is also possible to set up your host as a SLIP gateway with proxy ARP. You might prefer this approach if your dialin modems are attached directly to an OpenVMS system rather than to a terminal server.

Follow these steps on the host to become a SLIP gateway:
  1. Create a SLIP interface in another network or subnetwork, for example:
    $ TCPIP SET INTERFACE SL0 /HOST=10.1.2.3 /SERIAL_DEVICE=TTA2
  2. Add a host route for the remote system. For example:
    $ TCPIP SET ROUTE FINCH /GATEWAY=10.1.2.3
  3. Configure an ARP entry for the remote host, listing your own Ethernet address (as shown in TCPIP SHOW INTERFACE /FULL). For example:
    $ TCPIP SET ARP 08-00-2B-2C-4F-46 FINCH /PUBLIC
  4. Enable IP packet forwarding, if not already done. Enter:
    $ TCPIP SET PROTOCOL IP /FORWARD

When your host is set up as a SLIP gateway, create an interface on the remote host at the other end of the serial line. Specify an address in the same subnetwork as the LAN.

Although the two ends of the SLIP line are in different subnetworks, traffic can flow properly due to the interface route you added with the SET ROUTE command.

3.3.6. Shutting Down SLIP

To terminate a SLIP connection, follow these steps:
  1. Return the associated terminal port to general use. Enter:
    $ TCPIP SET NOINTERFACE interface
  2. If you added special route and proxy entries in conjunction with the SLIP line, remove them.

  3. If you changed any terminal settings in preparation for SLIP, restore them using the SET TERMINAL command.

3.4. Solving Serial Line Problems

If you have problems dialing in to an OpenVMS system using SLIP or PPP after following the instructions in this chapter, perform the following steps to isolate the cause of the problem:
  1. Check the equipment used by both the client and the dialin provider:
    • Do the cables work?

    • Are the modems configured properly?

    • Are the DIP switches on the modems set correctly?

    • Are the modem software settings correct? Make sure that flow control is disabled.

    • Are all clients and dialup providers using unique addresses?

    After a software upgrade, be sure to reboot and restart TCP/IP Services.

  2. Make sure the SET HOST attempts have not exceeded the OpenVMS security level. To check and then delete, if necessary, any information about these attempts, enter the following commands. Note that SECURITY privilege must be enabled to use these commands.
    $ SHOW INTRUSION
    $ DELETE/INTRUSION_RECORD source
  3. Make sure that IP forwarding is enabled using the following command:
    TCPIP> SHOW PROTOCOL IP/FORWARD
  4. Make sure the terminal characteristics for the terminal device associated with the interface are set up as follows:
    $ SET TERMINAL TTnx /ALTYPEAHD /AUTOBAUD /DIALUP -
    _$ /DISCONNECT /EIGHTBIT /MODEM /NOHANGUP /NOHOSTSYNC /NOPASTHRU -
    _$ /NOREADSYNCH /NOTTYSYNCH /PERMANENT /TYPE_AHEAD

    Make sure you specify the /TYPE_AHEAD qualifier when you enter the SET TERMINAL command to set up an asynchronous port.

  5. Enter the SET HOST/DTE command to make sure you can log in to the system:
    $ SET HOST/DTE TTnx

    If you cannot log in to or communicate with the system, you may be using the wrong terminal device name (TT nx).

  6. Set up OPCOM to receive messages using the DCL command REPLY/ENABLE. You need OPER privileges to use OPCOM.

  7. You need NETMBX and OPER privileges to establish a successful connection. If these privileges are not enabled when you enter the CONNECT command, you will see messages similar to the following:
    $ PPPD
    PPPD> CONNECT
    
    \}`}"}(}"6~ <CTRL/@>
    %PPPD-I-CONNECTTERM, converting connection on device _TTA0: to a
    Point-to-Point connection
    %PPPD-E-CALLBACKERR, error calling network callback
    %SYSTEM-F-NOPRIV, insufficient privilege or object protection violation
    %PPPD-F-ABORT, fatal error encountered; operation terminated

    Note that the extraneous data in this sample is an ASCII representation of IP packets transmitted over the open line.

    PPP sets up a default route on the client if one did not exist. Typically, a default route exists if another interface exists on the client.

  8. Attempt to ping the remote system:
    TCPIP> PING host-name

    Watch the modem's LED display as you attempt to communicate using the PING command.

    You might not be able to ping the system if the serial line is tied up with a large FTP operation.

  9. Use the TCPTRACE command to see packets going in and out of the local system. For information about using TCPTRACE, enter:
    $ HELP TCPTRACE
  10. Display a count of the packets being sent and received on the problem interface, in full screen format, updated every second. For a SLIP problem, enter:
    TCPIP> SHOW INTERFACE SLn
    To display the packet counts for PPP problem, enter:
    TCPIP> SHOW INTERFACE PPn

    In these commands, n is the interface number.

3.4.1. Solving PPP Problems

Keep the following in mind for PPP-specific problems:
  • If the virtual terminal software has not been loaded, the following error will be displayed when you try to connect:
    %PPPD-E-NEEDVIRTTERM, point-to-point connection on device _TTB0: must
    be done on a virtual terminal
    Correct this problem by entering the following commands before you dial out:
    $ RUN SYS$SYSTEM:SYSMAN
    SYSMAN> IO 
    CONNECT VT/NOADAPTER/DRIVER=SYS$LOADABLE_IMAGES:SYS$TTDRIVER.EXE
    SYSMAN> EXIT
    To make this permanent, add the following commands to the SYS$MANAGER:SYSTARTUP_VMS.COM file:
    $ SET PROCESS/PRIVILEGE=CMKRNL
    $ SYSMANIO = "SYSMAN IO"
    $ SYSMANIO CONNECT VT/NOADAPTER/DRIVER=SYS$LOADABLE_IMAGES:SYS$TTDRIVER.EXE

    Be sure to terminate any old virtual terminal sessions.

  • If you are trying to use OpenVMS as a PPP client to your ISP (Internet service provider), check where the ISP uses an authentication protocol, such as CHAP, PAP, or RADIUS. These protocols are not supported and will prevent a connection to OpenVMS.

Chapter 4. Configuring and Managing Routing

Routing allows traffic from your local network to reach its destination elsewhere on the internet. Hosts and gateways on a network use routing protocols to exchange and store routing information. Routing is the act of forwarding datagrams based on information stored in a routing table.

The TCP/IP Services product provides two types of routing: static and dynamic. This chapter reviews key routing concepts and describes:

4.1. Key Concepts

If the hosts on your network need to communicate with computers on other networks, a route through a gateway must be defined. All hosts and gateways on a network store information about routes in routing tables. With TCP/IP Services, routing tables are maintained in both dynamic and permanent memory.

You can define routes manually (static routing), or you can enable routing protocols that exchange information and build routing tables based on the information exchanged (dynamic routing).

4.1.1. Static Routing

Because static routing requires manual configuration, it is most useful when the number of gateways is limited and where routes do not change frequently. For information on manually configuring routing, see Section 4.2.

4.1.2. Dynamic Routing

Complex environments require a more flexible approach to routing than a static routing table provides. Routing protocols distribute information that reflect changing network conditions and update the routing table accordingly. Routing protocols can switch to a backup route when a primary route becomes unavailable and can determine the best route to a given destination.

Dynamic routing tables use information received by means of routing protocol updates; when routes change, the routing protocol provides information about the changes.

Routing daemons implement a routing policy, that is, the set of rules that specify which routes go into the routing table. A routing daemon writes routing messages to a routing socket, causing the kernel to add a new route, delete an existing route, or modify an existing route.

The kernel also generates routing messages that can be read by any routing socket when events occur that may be of interest to the process, for example, the interface has gone down or a redirect has been received.

TCP/IP Services implements two routing daemons: the Routing Daemon (ROUTED) and the Gateway Routing Daemon (GATED). The following sections provide more information.

4.1.2.1. Routing Daemon (ROUTED)

This daemon (pronounced route-dee) supports the Routing Information Protocol (RIP). When ROUTED starts, it issues routing update requests then listens for responses. A system configured to supply RIP information responds to the request with an update packet. The update packet contains destination addresses and routing metrics associated with each destination. After receiving a RIP update, the ROUTED uses the information to update its routing table.

To configure dynamic routing with ROUTED, see Section 4.3.

4.1.2.2. Gateway Routing Daemon (GATED)

This daemon (pronounced gate-de) supports interior and exterior gateway protocols. It obtains information from several routing protocols and selects the best routes based on that information. You can configure GATED to use one or more of the protocols described in Table 4.1.
Table 4.1. GATED Routing Protocols

Protocol

RFC

Description

Routing Information Protocol (RIP) Versions 1 and 2

RFC 1058, RFC 1723

RIP is a commonly used interior protocol that selects the route with the lowest metric (hop count) as the best route.

Open Shortest Path First (OSPF) Version 2

RFC 1583

Another interior routing protocol, OSPF is a link-state protocol (shortest path first) and better suited than RIP for use in complex networks with many routers.

Exterior Gateway Protocol (EGP)

RFC 904

EGP exchanges reachability information between autonomous systems. An autonomous system is usually defined as a set of routers under a single administration, using an interior gateway protocol and common metric to route packets. Autonomous systems use exterior routing protocols to route packets to other autonomous systems.

Border Gateway Protocol (BGP)

RFCs 1163, 1267, 1771

Like EGP, BGP exchanges reachability information between autonomous systems but supports nonhierarchical topologies. BGP uses path attributes to provide more information about each route. Path attributes can include, for example, administrative preferences based on political, organizational, or security considerations.

Router Discovery

RFC 1256

This protocol is used to inform hosts of the availability of routers that it can send packets to, and to supplement a statically configured default router.

These routing protocols are configured in the GATED configuration file TCPIP$GATED.CONF. This file contains statements that control tracing options, select routing protocols, manage routing information, and manage independent system routing.

For information on configuring dynamic routing with GATED, see Section 4.4.

4.2. Configuring Static Routes

The first time you run the configuration procedure, TCPIP$CONFIG.COM, static routing is configured automatically. To manually configure static routing, use the CREATE ROUTE command to create an empty routes database file.

The default file name is SYS$COMMON:[SYSEXE]TCPIP$ROUTE.DAT. To specify a different name, define the systemwide logical name TCPIP$ROUTE.

Note

Do not enter the CREATE ROUTE command unless you intend to reconfigure your entire cluster.

4.2.1. Creating a Default Route

When TCP/IP is sending a packet, it consults the routing table to determine which interface is connected to the destination network. If the packet has a destination network address that is unknown, the packet is sent to the default router. The default route points at the default router. For example, if a router with address 16.20.0.173 is designated to route all packets between the local network and the rest of the world, then the default route can be set with the following command:
$ TCPIP SET ROUTE /DEFAULT /GATEWAY=16.20.0.173
If TCP/IP Services is active, this affects the active routes database. To ensure this default route is available next time TCP/IP Services is started, the /PERMANENT qualifier must be used. For example:
$ TCPIP SET ROUTE /DEFAULT /GATEWAY=16.20.0.173 /PERMANENT

Use the SET NOROUTE command to remove a route.

Or you can define the default route using the route UNIX command. In this case, to ensure the default route is recreated next time TCP/IP Services is started, add the command to SYS$STARTUP:TCPIP$SYSTARTUP.COM. For example, to create the same default route as defined above, use the following UNIX style command:
$ route add default 16.20.0.173
To remove the route, enter the following command:
$ route delete default 16.20.0.173

4.2.2. Manually Defining Static Routes

To create a static route, use the SET ROUTE command. The command has the following effects:
  • If TCP/IP Services is not active, SET ROUTE modifies the permanent database.

  • If TCP/IP Services is active, SET ROUTE modifies the volatile database.

  • If TCP/IP Services is active, SET ROUTE/PERMANENT updates the permanent database.

The SET ROUTE command requires the following information:
  • The IP address or domain name of the destination host or network

  • The IP address or host name of a gateway that can reach the destination host

VSI strongly recommends that you do not specify alias names with the destination parameter or the /GATEWAY= host qualifier.

To define a route to any host on a specific network, enter:
TCPIP> SET ROUTE network_IP_address /GATEWAY="gateway" /NETWORK
To define a route to a specific host on a specific network, enter:
TCPIP> SET ROUTE remote_host /GATEWAY="gateway"

4.2.2.1. Examples

  1. In the following example, the network is active. The SET ROUTE command adds a route to the volatile routes database. TCPIP starts directing communication for flamingo through gateway francolin.
    TCPIP> SET ROUTE "flamingo" /GATEWAY="francolin"
  2. In the following example, the network is active. The SET ROUTE command defines a routing path in the volatile routes database. The command specifies that traffic for the network with IP address 128.30.0.0 uses gateway francolin.
    TCPIP> SET ROUTE 128.30.0.0 /NETWORK /GATEWAY="francolin"
  3. In the following example, the network is not active. The SET ROUTE command adds the new route to the permanent routes database. The next time the product starts up, packets for NENE will go through a gateway called bird.of.paradise.
    TCPIP> SET ROUTE NENE /GATEWAY="bird.of.paradise"

    At startup, the information in the permanent routes database, if any exists, is loaded into the volatile routes database. You can add permanent routes while the product is stopped or while it is running. If it is running, use the /PERMANENT qualifier.

  4. The following command permanently sets routing for host albatross to go through gateway birdygate.
    TCPIP> SET ROUTE "albatross" /GATEWAY="birdygate" /PERMANENT

    A default route is a route used to direct data that is addressed to an unidentifiable network address. To define a default route, use the /DEFAULT qualifier.

  5. The following command sets a default route. NIGHTINGALE is the default gateway.
    TCPIP> SET ROUTE /DEFAULT /GATEWAY=NIGHTINGALE

    To check that your routes are set up correctly, use either the LOOP or PING command.

4.2.3. Displaying Manually Defined Routes

To display static routes, use the SHOW ROUTE command. To see the permanent database, specify the /PERMANENT qualifier.

The display shows the following types of routes:
  • A — Active route (A route that was created manually or associated with an interface.)

  • D — Dynamic route. (A route that was dynamically created by the ROUTED or GATED routing daemon.)

  • H — Host route (A route to a host.)

  • N — Network route (A route to a network.)

  • P — Permanent route (A route from the route database.)

To display a route that was defined by an address, specify either its address or a wildcard.

Some examples of displaying routes are listed below.
  1. The following example displays information about all the manually defined routes.
    TCPIP> SHOW ROUTE /FULL
                                 DYNAMIC
    Type           Destination               Gateway
    
    AN   11.111.0.0   destin_host1   11.110.5.118   gate_host
    AH   22.111.4.10  destin_host2   22.110.5.120   gate_host_2
  2. The following example displays the permanent static routes that were defined with SET ROUTE/PERMANENT.
    TCPIP> SHOW ROUTE /PERMANENT 
    
                           PERMANENT 
    
    Type        Destination            Gateway
    
    PN    0.0.0.0            11.20.208.100   pterodactyl.extinct.com
    PN    1.1.1.1            22.2.2.2
Another way to display route information is by using the netstat UNIX command. For example, to display the routes, and suppress conversion of network numbers to names, enter the following commands:
$ @SYS$MANAGER:TCPIP$DEFINE_COMMANDS.COM

$ netstat -rn
Routing tables
Destination      Gateway          Flags     Refs     Use  Interface

Route Tree for Protocol Family 26:

Route Tree for Protocol Family 2:
default          16.20.0.173        UG          0        0  WE1
default          16.20.0.173        UG          0        0  WE0
16.20/16         16.20.208.161      U           2       56  WE1
16.20/16         16.20.208.160      U           1        9  WE0
16.20.208.160    16.20.208.160      UHL         0        0  WE0
16.20.208.161    16.20.208.161      UHL         0        0  WE1
127.0.0.1        127.0.0.1          UHL         1        1  LO0
This example shows a multihomed host with two interface adapters. For more information about the netstat utility, enter the following command:
TCPIP> HELP NETSTAT

4.3. Enabling and Disabling Dynamic Routing

Use the configuration procedure TCPIP$CONFIG to enable dynamic routing and configure your host to receive routing protocol messages as follows:
  1. Select the Routing option from the Core Environment menu.

  2. Answer Yes to the question "Do you want to configure dynamic ROUTED or GATED routing [NO]:"

  3. You are asked whether you want to enable GATED.
    Do you want to enable GATED routing configuration?

    If you answer Yes to this question, GATED will be enabled. If you answer No, ROUTED will be enabled.

  4. If you choose to enable ROUTED, indicate whether you want your host to supply RIP updates to other hosts on the network (in addition to receiving RIP updates) and the default network route.

  5. If you choose to enable GATED, you must also configure the routing protocols in the GATED configuration file TCPIP$GATED.CONF. See Section 4.4 for more information about configuring GATED.

To disable dynamic routing:
  1. Select the Routing option from the CORE ENVIRONMENT menu.

  2. Answer Yes to the following questions:
    Do you want to reconfigure dynamic ROUTED or GATED routing [NO]: Y
    
    Do you want to disable dynamic ROUTED or GATED routing configuration
    [NO]: Y

    Alternatively, enter the TCP/IP management command STOP ROUTING.

When you disable GATED routing, the GATED routes are preserved. To disable GATED and remove all GATED routes from the routing table, enter the command STOP ROUTING/GATED.

4.4. Configuring GATED

You must configure the GATED protocols before starting GATED routing. Edit a copy of the sample file TCPIP$GATED.TEMPLATE (located in the SYS$SYSDEVICE:[TCPIP$GATED] directory) to add statements that select routing protocols, manage routing information, manage independent system routing, and control tracing options.
  1. Use TCPIP$CONFIG to enable GATED.

  2. Edit the TCPIP$GATED.TEMPLATE file.

  3. Save the file TCPIP$GATED.CONF in the SYS$SYSDEVICE:[TCPIP$GATED] directory.

  4. If GATED is already running, stop it by entering the command STOP ROUTING/GATED.

  5. Start GATED by entering the command START ROUTING/GATED.

    See the VSI TCP/IP Services for OpenVMS Management Command Reference manual for detailed descriptions of the SET GATED and START ROUTING/GATED commands.

If you do not format the configuration file correctly, GATED terminates.

For specific information about how to edit the GATED configuration file, see Appendix A.

4.4.1. Datagram Reassembly Time

Reassembly is the process of reconstructing a complete data message from received fragments. The reassembly timer determines the length of time allowed for the reassembly process. You can modify the reassembly timer to ensure that IP datagram fragments are optimally reassembled at the destination host.

Consider the following when setting the reassembly timer:
  • If the timer expires before the host receives all the fragments, they are discarded.

  • An inappropriately small interval might result in too many datagrams being discarded.

  • An excessive interval might degrade internet performance.

Enter the following commands to reset the reassembly timer:
  • For the current session:
    TCPIP> SET PROTOCOL IP /REASSEMBLY_TIMER=n
  • To reset at the next TCP/IP Services startup:
    TCPIP> SET CONFIGURATION PROTOCOL IP /REASSEMBLY_TIMER=n

In the following example, the first command changes the IP reassembly time to 20 seconds on the running system. This new setting remains in effect until the next TCP/IP Services startup.

The second command makes the change permanent by modifying the configuration database, TCPIP$CONFIGURATION.DAT.
TCPIP> SET PROTOCOL IP /REASSEMBLY_TIMER=20

TCPIP> SET CONFIGURATION PROTOCOL IP /REASSEMBLY_TIMER=20

4.4.2. Enabling Forwarding

To enable packet forwarding between networks, enter the following TCP/IP management command:
TCPIP> SET PROTOCOL IP /FORWARD
To ensure this is set up the next time TCP/IP Services is restarted, enter the following command:
TCPIP> SET CONFIGURATION PROTOCOL IP /FORWARD
Display the setting using the following command:
TCPIP> SHOW PROTOCOL /PARAMETERS
Or use the sysconfig utility to enable forwarding. First, define foreign commands:
$ @SYS$MANAGER:TCPIP$DEFINE_COMMANDS.COM
Enter the following sysconfig command:
$ sysconfig -r inet ipforwarding=1 ipgateway=1

To make sure forwarding is enabled after restarting TCP/IP Services, define these attributes in the SYSCONFIGTAB.DAT database file, as described in the VSI TCP/IP Services for OpenVMS Tuning and Troubleshooting guide.

To view the setting, use the following command:
$ sysconfig -q inet ipforwarding ipgateway

When multiple networks share the same physical media and the host has just one interface, it is still possible to forward packets between these networks by creating a network alias, as described in Section 2.3.3.

For example, consider a network in which two networks have network addresses of 16.20.1/24 and 16.20.2/24, and the host address is 180. If the host has a single Ethernet interface, WE0, create the interface and pseudointerfaces as follows:
TCPIP> SET CONFIGURATION INTERFACE WE0 /HOST=16.20.1.180 -
_TCPIP> /NETWORK_MASK=255.255.255.0 /BROADCAST_MASK=16.20.1.255

TCPIP> SET CONFIGURATION INTERFACE WEA0 /HOST=16.20.2.180 -
_TCPIP> /NETWORK_MASK=255.255.255.0 /BROADCAST_MASK=16.20.2.255

TCPIP> SET CONFIGURATION PROTOCOL IP /FORWARD

When TCP/IP Services is restarted, the host will forward packets between these networks.

Alternatively, you can add the following commands to TCPIP$SYSTARTUP.COM and then restart TCP/IP Services:
$ ifconfig we0 aliaslist 16.20.1-2.180/24

$ sysconfig -r inet ipforwarding=1 ipgateway=1

4.4.3. Extending Routing

To use extended routing, define pseudointerfaces. A pseudointerface is a data structure that extends routing. Like an interface, the name of an internet pseudointerface is three alphabetic characters, followed by the pseudointerface unit number in the range of 0 through 255.

The first two characters are the same as the two characters in the internet interface name (interface type and interface class). See Section 2.3.1 for more information about interface names.

The third character identifies the controller letter that corresponds to the OpenVMS hardware controller.

For example, for an OpenVMS Alpha system with two Ethernet controllers, EZA0 and EZB0, you can define the following internet interfaces and pseudointerfaces:
  • Internet interfaces:
    • ZE0

    • ZE1

  • Internet pseudointerfaces, each with its own IP address, network mask, and broadcast mask:
    • SEA

    • SEA0

    • SEA1

      .

      .

      .

    • SEA254

    • SEB255

To extend routing, follow these steps:
  1. Define the pseudointerfaces using the SET INTERFACE and SET CONFIGURATION INTERFACE commands:
    TCPIP> SET NOINTERFACE interface
    
    TCPIP> SET INTERFACE interface /HOST=host -
    _TCPIP> /NETWORK_MASK=mask /BROADCAST_MASK=b_mask
    
    TCPIP> SET CONFIGURATION INTERFACE interface /HOST=host -
    _TCPIP> /NETWORK_MASK=mask /BROADCAST_MASK=b_mask
    For example, to specify the pseudointerface FFA0 on host KESTREL, with network mask 255.255.0.0 and broadcast mask to 128.30.0.0, enter:
    TCPIP> SET NOINTERFACE FFA0
    
    TCPIP> SET INTERFACE FFA0 /HOST=KESTREL /NETWORK_MASK=255.255.0.0 -
    _TCPIP> /BROADCAST_MASK=128.30.0.0
  2. Enter the same information into the configuration database to set up the interfaces at startup. For example:
    TCPIP> SET CONFIGURATION INTERFACE FFA0 /HOST=KESTREL -
    _TCPIP> /NETWORK_MASK=255.255.0.0 /BROADCAST_MASK=128.30.0.0

    To display information about the network interfaces, use the SHOW INTERFACE command. To remove the interface from the configuration database, use the SET CONFIGURATION NOINTERFACE command.

4.4.4. Interface Routes

If you have a configuration in which multiple networks share the same physical LAN, you can communicate directly with hosts in other networks without the need of a pseudointerface for each network.

You can use a broadcast address to designate an interface route, also called a metric 0 route.

To create interface routes, follow these steps:
  1. As the gateway for the route, enter either one of the host's own addresses or the broadcast address associated with an interface.

    TCP/IP Services recognizes this route as an interface route.

  2. Configure the hosts in the other network to recognize that your network is present on their LAN.

For example, network 99.0.0.0 is on the same cable as network 192.199.199.0. On host 99.1.2.3, specify network 192.199.199.0 as directly reachable:
TCPIP> SET ROUTE 192.199.199.0 /NETWORK /GATEWAY=99.1.2.3
On the hosts in network 192.199.199.0, enter:
TCPIP> SET ROUTE 99.0.0.0 /NETWORK /GATEWAY=192.199.199.255

4.4.5. Manually Configuring a Hardware Address

Network hosts require manual configuration of a hardware address for a remote IP address under the following conditions:
  • The remote host does not support the Address Resolution Protocol (ARP). You need static mapping of IP addresses to hardware addresses.

  • The remote host is running ARP, but a change was made to the internet interface on that host.

    To notify your system about the change, flush the address mapping tables. Use the SET NOARP command to do this.

For example, to map the Ethernet address AA-02-04-05-06-07 of host ROOK, add the hardware address to the ARP table by entering the following command:
TCPIP> SET ARP AA-02-04-05-06-07 ROOK

Chapter 5. Configuring and Managing failSAFE IP

failSAFE IP is an optional service provided by TCP/IP Services to allow IP addresses to fail over when interfaces cease functioning on a system where multiple interfaces have been configured. When the same IP address is configured on multiple interfaces, network connections can be maintained when:
  • The network interface card (NIC) fails.

  • A cable is disconnected or broken.

  • A switch for a port fails.

  • The node or the TCP/IP Services software is shut down.

This chapter reviews key concepts and describes:

5.1. Key Concepts

The failSAFE service monitors an interface and takes appropriate action upon detecting interface failure or recovery. failSAFE IP provides IP address redundancy by requiring the same IP address to be configured on multiple interfaces. Only one instance of each IP address is active at any time; the other duplicate IP addresses are in standby mode.

Standby IP addresses can be configured on multiple interfaces within the same node or across an OpenVMS Cluster. The interfaces are monitored by the failSAFE IP service. When an interface fails, each active IP address on the failed interface is removed and the standby IP address becomes active. If an address is not preconfigured with a standby, then the address is removed from the failed interface until it recovers.

Static routes on the failed interface are also removed and are configured on any interface where their network is reachable.

When an interface recovers, it can request that its IP addresses be returned to it when the interface is configured as the home interface for one or more addresses. When the home interface recovers, it requests that the current holder of the address give it up. (For more information about home interfaces, see Section 5.2.3.)

The current holder of an address does not release an address if this action will result in dropped connections, or if the current holder is also designated as a home interface for that address.

Management intervention can be taken to force the removal of an address.

5.2. Configuring failSAFE IP

Configuring failSAFE IP requires two steps:
  1. Assign the same IP address to multiple interfaces. Only one instance of that address is active; all other instances are in standby mode. For simple configurations, use the TCPIP$CONFIG Core Interface menu to assign an IP address to multiple interfaces. Alternatively, use the ifconfig utility, which provides a greater degree of management control. For more information, see Section 5.2.1.

  2. Use the TCPIP$CONFIG.COM command procedure to enable the failSAFE IP service, which monitors the health of interfaces and takes appropriate action when it detects interface failure or recovery. This service is available from the Optional Components menu.

5.2.1. Configuring failSAFE IP Manually

A failSAFE IP address can be configured by using the TCPIP$CONFIG.COM command procedure, or manually by using the TCP/IP management command SET INTERFACE.

For instance, to create an IP address of 10.10.10.1 on interface IE0 and a standby alias address on interface IE1 (pseudointerface IEB0), use the following commands:
$ TCPIP 
TCPIP> SET INTERFACE IE0/HOST=10.10.10.1
TCPIP> SET INTERFACE IEB0/HOST=10.10.10.1
Alternatively, you can use the ifconfig utility to configure an interface manually. For example:
$ ifconfig ie0 10.10.10.1 
$ ifconfig ie1 alias 10.10.10.1
To view the standby addresses, use the ifconfig utility. For example:
$ ifconfig -a 
IE0: flags=c43
<UP,BROADCAST,RUNNING,MULTICAST,SIMPLEX> 
   *inet 10.10.10.1 netmask ff000000 broadcast 10.255.255.255
IE1: flags=c03
<UP,BROADCAST,MULTICAST,SIMPLEX> 
     failSAFE IP Addresses: 
        inet 10.10.10.1 netmask ff000000 broadcast 10.255.255.255 (on HUFFLE IE0)
In this example, interface IE1 displays a failSAFE IP address that is active on node HUFFLE, interface IE0.

Note

In an OpenVMS Cluster, an IP address with active connections cannot be reassigned to another node in the cluster. Therefore, you should always configure a standby interface on the same node as the home interface.

DNS-controlled primary addresses should be placed under the control of the BIND/DNS load broker to make sure that the DNS alias continues to be available.

The ifconfig utility provides greater control of failSAFE IP addresses. Table 5.1 describes the ifconfig options that support failSAFE IP.
Table 5.1. ifconfig Options for failSAFE IP

Option

Description

[-] fail

Forces an interface to fail. You can recover the interface using the -fail command.

[-] home

Forces an alias address to be created with a home interface. This option is used when creating IP addresses. By default, all primary IP addresses are created with a home interface.

[-] fs

Creates an address that is not managed by failSAFE IP. All IP addresses are created as failSAFE addresses by default, except for addresses assigned to the loopback interface LO0 (for instance, the local host address 127.0.0.1).

5.2.2. Modifying the failSAFE IP Configuration Parameters

By default, the failSAFE IP service monitors all TCP/IP interfaces on a system, periodically polling each interface using default polling intervals. You can override the defaults by editing the configuration file. To change the name or location of the configuration file, define the logical name TCPIP$FAILSAFE. Be sure to include the /SYSTEM and /EXECUTIVE qualifiers, and make sure that the failSAFE process is stopped, or your changes will not take effect. By default, the configuration file name and location are:
SYS$SYSDEVICE:[TCPIP$FSAFE]TCPIP$FAILSAFE.CONF
Table 5.2 describes the configuration parameters.
Table 5.2. failSAFE IP Configuration Parameters

Parameter

Description

Default

GENERATE_TRAFFIC

Enables failSAFE IP to periodically generate either MAC-level broadcasts or gratuitous ARP packets. ARP traffic requires an active IP address on the NIC. MAC-level traffic is sent regardless of the NIC configured with IP. You can also use this parameter to turn off traffic generation.

This parameter allows three settings:
  • MAC

  • ARP

  • OFF

For example,to generate periodic ARP packets, enter the following parameter in the configuration file:
GENERATE_TRAFFIC: ARP

MAC

MAC_PTY

If MAC-level broadcast traffic is being generated, the MAC protocol type may also be specified as a two-byte hexadecimal number. For example, from the Web site, http://www.iana.org/assignments/ethernet-numbers, the DEC Diagnostic protocol type has a value of 6005.

For example, to generate MAC protocol packets of the DEC Diagnostic protocol, enter the following parameter in the configuration file:
MAC_PTY: 6005

If this parameter is not specified, an available protocol type is selected.

LOGFILE

Specifies the name and location of the log file. The logical name TCPIP$FAILSAFE_LOGFILE points to the log file. For example, to specify an alternate location, enter the following parameter in the configuration file:
LOGFILE: DEV1:[STATS]FAILSAFE.LOG
SYS$SYSDEVICE:[TCPIP$FSAFE] -
TCPIP$FAILSAFE_nodename.LOG

INTERFACE_LIST

The list of interfaces that failSAFE monitors.

All interfaces

INFO_POLL

Specifies the polling interval used when the interface is known to be functional. It requires two INFO_POLL timeouts to determine that an interface is not responding, at which time the polling frequency is set to the WARN_POLL period.

3 seconds

WARN_POLL

Specifies the polling interval used when the interface first stops responding. It will continue polling the interface for RETRY_WARN attempts before the interface is deemed to be malfunctioning, at which time the polling frequency is set to ERROR_POLL and failover occurs.

2 seconds

RETRY_WARN

Specifies the number of warning polls before the interface is deemed to be malfunctioning and the IP addresses associated with it are removed. A value of zero skips the WARN_POLL cycle.

1 retry

ERROR_POLL

Specifies the polling interval used when the interface is deemed to be malfunctioning. failSAFE monitors a malfunctioning interface at this frequency until it determines that the interface has recovered, at which time the polling frequency is set back to the INFO_POLL period.

30 seconds

5.2.3. Creating and Displaying Home Interfaces

failSAFE IP addresses can be created with a designated home interface. By default, all primary IP addresses are created with a home interface. A home interface provides a preferential failover and recovery target in an effort to always migrate IP addresses to their home interface, thereby limiting the disruption to users.

You can use the ifconfig utility to create and display addresses configured with home interfaces. For example, to create three addresses, enter the following commands:
$ ifconfig ie0 10.10.10.1            ! primary has home interface by default 
$ ifconfig ie0 alias 10.10.10.2      ! alias does not 
$ ifconfig ie0 home alias 10.10.10.3 ! create alias with home interface

Although the TCP/IP management command SET INTERFACE can be used to create primary and alias addresses, it does not allow you to create the home alias address. You must use the ifconfig utility to do this.

When addresses are displayed by the ifconfig utility, those addresses with a home interface are marked with an asterisk (*). For example:
$ ifconfig ie0 
IE0: flags=c43
<UP,BROADCAST,RUNNING,MULTICAST,SIMPLEX> 
   *inet 10.10.10.1 netmask ff000000 broadcast 10.255.255.255 
    inet 10.10.10.2 netmask ff000000 broadcast 10.255.255.255 
   *inet 10.10.10.3 netmask ff000000 broadcast 10.255.255.255
The asterisk indicates that the addresses 10.10.10.1 and 10.10.10.3 have a home interface of IE0.

Note

The TCP/IP management command SHOW INTERFACE does not identify addresses with a home interface.

Creating IP addresses with home interfaces spreads the IP addresses across multiple interfaces. This is useful for load-balancing and gaining higher aggregate throughput. If a home interface recovers after a failure, the addresses may return to their recovered home interface, thus maintaining the spread of addresses across the available interfaces.

Note

The IP address will not migrate toward a home interface while that address has active connections.

5.3. Managing failSAFE IP

The failSAFE IP service monitors the state of interfaces and, upon detecting a failure or recovery, takes the appropriate action. To start and stop the failSAFE IP service, run the following command procedures:
  • SYS$STARTUP:TCPIP$FAILSAFE_STARTUP.COM

  • SYS$STARTUP:TCPIP$FAILSAFE_SHUTDOWN.COM

The failSAFE IP service performs the following actions:
  1. Monitors the state of interfaces by periodically reading their Bytes Received counter.

  2. When required, marks an interface as failed or recovered.

  3. Maintains static routes to ensure they are preserved after interface failure or recovery.

  4. Logs all messages to TCPIP$FAILSAFE_RUN.LOG. Important events are additionally sent to OPCOM.

  5. Invokes a site-specific command procedure. For more information about the site-specific command procedures, see Section 20.1.1.

  6. Generates traffic to help avoid phantom failures, as described in Section 5.3.5.3.

If the failSAFE IP service is not enabled, configuring a failSAFE IP address across nodes provides identical functionality to the IP cluster alias, as described in Section 1.4.

5.3.1. failSAFE IP Logical Names

You can use logical names to customize the operating environment of failSAFE IP. The logical names must be defined in the LNM$SYSTEM_TABLE for them to take effect.

Table 5.3 describes the failSAFE IP logical names.
Table 5.3. failSAFE IP Logical Names

Logical Name

Description

TCPIP$FAILSAFE

Specifies the configuration file that is read by TCPIP$FAILSAFE during startup. This logical must be defined prior to starting the failSAFE IP service. The default file specification is
SYS$SYSDEVICE:[TCPIP$FSAFE] -
TCPIP$FAILSAFE.CONF.

TCPIP$FAILSAFE_FAILED_ ifname

Simulates a failure for the named interface (ifname). This logical name is translated each time failSAFE IP reads the LAN counters.

To determine the interface name, use the TCP/IP management command SHOW INTERFACE.

TCPIP$SYFAILSAFE

Specifies the name of a site-specific command procedure that is invoked when one of three conditions occurs: interface failure, retry failure, or interface recovery. The default file specification is SYS$MANAGER:TCPIP$SYFAILSAFE.COM.

TCPIP$FAILSAFE_LOG_LEVEL

Controls the volume of log messages sent to OPCOM and the log file. This logical is translated each time failSAFE IP logs a message. The default value is 0.

TCPIP$FSACP_LOG_LEVEL

Controls the volume of log messages sent to OPCOM by the ACP. This logical should be used only when directed by customer support. The default value is 0.

5.3.2. Customizing failSAFE IP

You can create a site-specific command procedure to be invoked under specified circumstances, such as when an interface fails. You can customize the command procedure to handle the following circumstances:
  • When the interface first appears to have stopped responding. This is the first warning that a problem may exist, but no action to failover IP addresses has been taken yet.

  • When an attempt to generate traffic on the interface fails. After the retry limit is reached, the interface is deemed as malfunctioning, and IP addresses are removed from the interface. Failover occurs.

  • When the interface recovers.

The default site-specific command procedure is:
SYS$MANAGER:TCPIP$SYFAILSAFE.COM

To modify the location or file name, define the logical name TCPIP$SYFAILSAFE.

Use the following text strings as parameters to the command procedure:
  • P1 is the interface name (for example, IE0)

  • P2 is the state. The states are:
    • INFO_STATE

    • WARN_STATE

    • ERROR_STATE

The TCPIP$SYFAILSAFE procedure is invoked by the TCPIP$FSAFE account, which by default has minimum privileges and quotas. It is necessary to ensure the TCPIP$SYFAILSAFE procedure is both readable and executable by the TCPIP$FSAFE account. In addition, the TCPIP$FSAFE account may require additional quotas and privileges so that it can execute all the commands contained within the TCPIP$SYFAILSAFE procedure.

5.3.3. Reestablishing Static and Dynamic Routing

When an interface fails, failSAFE IP removes all addresses and static routes from the failed interface. The static routes are reestablished on every interface where the route's network is reachable. This action can result in the creation of a static route on multiple interfaces and is most often observed with the default route.

You may need to restart dynamic routing to ensure that the dynamic routing protocol remains current with changes in the interface availability. If this is necessary, restart the routing process using the following TCP/IP management commands:
TCPIP> STOP ROUTING /GATED
TCPIP> START ROUTING /GATED
For GATED, failSAFE IP can be configured to scan the interfaces periodically for any changes. Use the GATED configuration option scaninterval. You can scan the interfaces manually using the following TCP/IP management command:
$ TCPIP SET GATED/CHECK_INTERFACES

For more information about routing protocols, see Chapter 4.

5.3.4. Displaying the Status of Interfaces

The failSAFE IP service periodically reads the network interface card (NIC) Bytes Received counter to determine the status of an interface. You can display the Bytes Received counter using the LANCP utility. For example, to view the Bytes Received counters for all interfaces, enter the following command:
$ pipe mcr lancp show device/count | search sys$pipe "Bytes received"/exact
The types of events that prevents the Bytes Received counter from changing include:
  • Failing interface hardware

  • Disconnected physical link

  • Shutting the interface down using TCP/IP management commands

  • Shutting down TCP/IP Services

  • Shutting down a node

5.3.5. Guidelines for Configuring failSAFE IP

This section describes guidelines that can help avoid common pitfalls in configuring failSAFE IP.

5.3.5.1. Validating failSAFE IP

Most contemporary networks are highly stable and rarely suffer from the problems that require failSAFE IP. Consequently, on the few occasions where failSAFE IP is required, it is critical that the service be validated in the environment where it is being deployed. Failure to do this can result in unexpected problems at the critical moment.

Since real failures are rare and sometimes difficult to simulate, the logical name TCPIP$FAILSAFE_FAILED_ ifname is provided. After configuring failSAFE IP addresses and starting the failSAFE IP service, validate the configuration using the following procedure:
  1. Establish connections and generate IP traffic.

    Using TELNET or FTP, create incoming and outgoing TCP connections to the multihomed host from inside and outside the subnet. Verify that these connections are established by using the following commands:
    $ @SYS$MANAGER:TCPIP$DEFINE_COMMANDS.COM
    $ ifconfig -a  ! Check the interface addresses
    $ netstat -nr  ! Check the routing table
    $ netstat -n   ! identify which interfaces are being used
  2. Simulate a failure and observe.

    Simulate a failure and observe OPCOM and log file messages. Use the following command to simulate a failure:
    $ DEFINE/SYSTEM TCPIP$FAILSAFE_FAILED_ifname 1  ! or disconnect the cable

    Wait long enough for failover to occur, which is signaled by OPCOM messages. Then observe the effects of failover and verify that TCP connections are still established and can transfer data. For example, TELNET sessions should respond to keyboard input.

    Use the following commands to see how IP addresses and routing have changed:
    $ ifconfig -a  ! Observe how the addresses have migrated
    $ netstat -nr  ! Observe how the routing table has changed
  3. Recover from the simulated failure and observe the OPCOM messages.
    $ DEASSIGN/SYSTEM TCPIP$FAILSAFE_FAILED_ifname  ! or reconnect the cable
    $ ifconfig -a ! Observe how the addresses have migrated
    $ netstat -nr ! Observe how the routing table has changed

    Again, ensure that TCP connections are still established and can transfer data.


Note

Simulating a failure with the logical name TCPIP$FAILSAFE_FAILED_ ifname does not disrupt physical connections and therefore is not an accurate indicator of whether the services will survive a real failover situation. Consequently, this procedure should be repeated by physically removing a network cable from one or more of the interfaces. Since this action might be disruptive to network services, it should be scheduled during a maintenance period, when disruption can be tolerated.

5.3.5.2. Configuring Failover Time

The key concern for configuring the failSAFE IP service is the time it takes to detect a failure and for the standby IP address to become active. One goal of a failSAFE IP configuration is to avoid disrupting existing connections, so the failover time must be within the connection timeout.

The minimum failover time is calculated as:
INFO_POLL + (WARN_POLL * RETRY)
The maximum failover time is calculated as:
(2 * INFO_POLL) + (WARN_POLL * RETRY) 

For explanations of the variables, see Table 5.2. The default values (INFO_POLL=3, WARN_POLL=2, RETRY=1) result in a failover range of 5 to 8 seconds. Note that this does not take into account the system load.

The recovery time will be less than the ERROR_POLL period, which is, by default, 30 seconds.

5.3.5.3. Avoiding Phantom Failures

The health of a NIC is determined by monitoring the NIC's Bytes Received counter. This provides a protocol-independent view of the NIC counters. However, in a quiet network, there may be insufficient traffic to keep the Bytes Received counter changing within the failover detection time, thus causing a phantom failure. To counteract this, the failSAFE service attempts to generate MAC-layer broadcast messages, which are received on every interface on the LAN except for the sending interface.

Consequently, in a quiet network with only two interfaces being monitored by the failSAFE IP service, a single NIC failure can also result in a phantom failure of the other NIC, since the surviving NIC is not able to increase its own Bytes Received counter.

You can reduce phantom failures in a quiet network by configuring the failSAFE IP service for at least three interfaces on the LAN. If one interface fails, the surviving interfaces continue to maintain one another's Bytes Received counters.

5.3.5.4. Creating IP Addresses with Home Interfaces

By default, the interface on which a primary IP address is created is its home interface, whereas an IP alias address is created without a home interface. To create an alias address with a home interface, use the ifconfig command, which should be added to the SYS$STARTUP:TCPIP$SYSTARTUP.COM procedure. For example, use the following command to create an alias address of 10.10.10.3 on interface IE0 and to designate IE0 as its home interface:
$ ifconfig ie0 home alias 10.10.10.3/24

5.3.5.5. Private Addresses Should Not Have Clusterwide Standby Interfaces

Private addresses are those that are used for network administration and are not published as well-known addresses for well-known services. A standby interface for a private address should be configured on the same node as the home interface. This avoids a situation in which a node cannot assign any addresses to its interfaces if they have active connections on another node in the cluster.

If you want to associate the list of private addresses with a public DNS alias name, you should use the load broker to provide high availability of the DNS alias. The load broker is described in Chapter 7.

Chapter 6. Configuring and Managing BIND Version 9

The Domain Name System (DNS) maintains and distributes information about Internet hosts. DNS consists of a hierarchical database containing the names of entities on the Internet, the rules for delegating authority over names, and mail routing information; and the system implementation that maps the names to Internet addresses.

In OpenVMS environments, DNS is implemented by the Berkeley Internet Name Domain (BIND) software. TCP/IP Services implements a BIND server based on the Internet Software Consortium's (ISC) BIND Version 9.

Note

In this version of TCP/IP Services, the BIND Server and related utilities have been updated to use the OpenSSL shareable image SSL$LIBCRYPTO_SHR32.EXE. There is now a requirement that this shareable image from OpenSSL V1.2 or higher be installed on the system prior to starting the BIND Server.

This chapter contains the following topics:

6.1. Key Concepts

This section serves as a review only and assumes you are acquainted with the InterNIC, that you applied for an IP address, and that you registered your domain name. You should also be familiar with BIND terminology, and you should have completed your preconfiguration planning before using this chapter to configure and manage the BIND software.

If you are not familiar with DNS and BIND, see the VSI TCP/IP Services for OpenVMS Concepts and Planning guide. If you need more in-depth knowledge, see O'Reilly's DNS and BIND, Fourth Edition. You can find the BIND 9 Administrator Reference Manual at http://www.isc.org/.

6.1.1. How the Resolver and Name Server Work Together

BIND is divided conceptually into two components: a resolver and a name server. The resolver is software that queries a name server; the name server is the software process that responds to a resolver query.

Under BIND, all computers use resolver code, but not all computers run the name server process.

The BIND name server runs as a distinct process called TCPIP$BIND. On UNIX systems, the name server is called named (pronounced name-dee). Name servers are typically classified as master (previously called primary), slave (previously called secondary), and caching-only servers, depending on their configurations.

6.1.2. Common BIND Configurations

You can configure BIND in several different ways. The most common configurations are resolver-only systems, master servers, slave servers, forwarder servers, and caching-only servers. A server can be any of these configurations or can combine elements of these configurations.

Servers use a group of database files containing BIND statements and resource records. These files include:
  • The forward translation file, domain_name.DB

    This file maps host names to IP addresses.

  • The reverse translation file, address.DB

    This file maps the address back to the host names. This address name lookup is called reverse mapping. Each domain has its own reverse mapping file.

  • Local loopback forward and reverse translation files, LOCALHOST.DB, 127_0_0.DB, and 0_0_0_0_0_0_IP6.ARPA (for IPv6).

    These local host databases provide forward and reverse translation for the widely used LOCALHOST name. The LOCALHOST name is always associated with IPv4 address 127.0.0.1 and IPv6 address ::1, and is used for loopback traffic.

  • The hint file, ROOT.HINT

    This file contains the list of root name servers.

A configuration file, TCPIP$BIND.CONF, contains statements that pull all the database files together and governs the behavior of the BIND server.

6.1.2.1. Master Servers

A master server is the server from which all data about a domain is derived. Master servers are authoritative, which means they have complete information about their domain and that their responses are always accurate.

To provide central control of host name information, the master server loads the domain's information directly from a disk file created by the domain administrator. When a new system is added to the network, only the database on the master server needs to be modified.

A master server requires a complete set of configuration files: forward translation, reverse translation, configuration, hint, and loopback files.

6.1.2.2. Slave Servers

Slave servers receive authority and their database from the master server.

A particular domain's database file is called a zone file; copying this file to a slave server is called a zone file transfer . A slave server assures that it has current information about a domain by periodically transferring the domain's zone file from the master. Slave servers are also authoritative for their domains.

Configuring a slave server is similar to configuring a master server. The only difference is that, for the slave server, you need to provide the name of the master server from which to transfer zone data.

Note

If you create a master, slave, or forwarder server for the same domain on which your local host resides, you should reconfigure your BIND resolver so that it uses this system (LOCALHOST) as its name server.

Slave servers require a configuration file, a hint file, and loopback files.

6.1.2.3. Caching-Only Servers

Caching-only servers get the answers to all name service queries from other name servers. Once a caching server receives an answer to a query, it saves the information and uses it in the future to answer queries itself. Most name servers cache answers and use them in this way but a caching-only server depends on this for all its server information. It does not keep name server database files as other servers do. Caching-only servers are nonauthoritative, which means that their information is secondhand and can be incomplete.

Caching-only servers require a hint file and loopback files.

6.1.2.4. Forwarder Servers

The forwarding facility can be used to create a large, sitewide cache on a few servers, thereby reducing traffic over links to external name servers. Forwarder servers process requests that slave servers cannot resolve locally (for example, because they do not have access to the Internet).

Forwarding occurs on only those queries for which the server is not authoritative and for which it does not have the answer in its cache.

A master or slave server specifies a particular host to which requests outside the local zone are sent. This is a form of Internet courtesy that limits the number of hosts that actually communicate with the root servers listed in the ROOT.HINT file.

If you configure a forwarder server, you must provide the name of the host to which requests outside your zones of authority are forwarded.

6.2. Security Considerations

BIND Version 9 provides the following security enhancements:
  • Access control lists allow you to control access to the name server. See Section 6.2.1 for more information.

  • Dynamic Update Security controls access to the dynamic update facility. See Section 6.2.2 for more information.

  • Transaction Signatures (TSIG) provide key-based access to the dynamic update facility. See Section 6.2.3 for more information.

  • TKEY automatically generates a shared secret between two hosts. See Section 6.2.4 for more information.

  • SIG(0) is another method for signing transactions. See Section 6.2.5 for more information.

  • DNSSEC provides cryptographic authentication of DNS information. See Section 6.2.6 for more information.

6.2.1. Access Control Lists

Access control lists (ACLs) are address match lists that you can set up and name for use in configuring the following options:
  • allow-notify

  • allow-query

  • allow-recursion

  • blackhole

  • allow-transfer

Using ACLs, you can control who can access your name server without cluttering your configuration files with huge lists of IP addresses.

It is a good idea to use ACLs and to control access to your server. Limiting access to your server by outside parties can help prevent unwanted use of your server.

Here is an example of how to apply ACLs properly:
// Set up an ACL named "bogusnets" that will block RFC1918 space,
// which is commonly used in spoofing attacks.
acl bogusnets { 0.0.0.0/8; 1.0.0.0/8; 2.0.0.0/8; 192.0.2.0/24;
  224.0.0.0/3; 10.0.0.0/8; 172.16.0.0/12; 192.168.0.0/16;
};
// Set up an ACL called our-nets. Replace this with the real IP numbers.
acl our-nets { x.x.x.x/24; x.x.x.x/21; };
options {
  ...
  ...
  allow-query { our-nets; };
  allow-recursion { our-nets; };
  ...
  blackhole { bogusnets; };
  ...
};
zone "example.com" {
  type master;
  file "example_com.db";
  allow-query { any; };
};

This example allows recursive queries of the server from the outside, unless recursion has been previously disabled. For more information about how to use ACLs to protect your server, see Section 6.4.2.

6.2.2. Dynamic Update Security

Access to the dynamic update facility should be strictly limited. In earlier versions of BIND, the only way to do this was to include an IP address or network prefix in the allow-update zone option. This method is insecure because the source address of the update UDP packet is easily forged. Also, if the IP addresses allowed by the allow-update option include the address of a slave server that performs forwarding of dynamic updates, the master can be trivially attacked by sending the update to the slave, which will forward it to the master with its own source IP address. This causes the master to approve the update without question.

For these reasons, updates should be authenticated cryptographically by means of transaction signatures (TSIG). That is, the allow-update option should list only TSIG key names, not IP addresses or network prefixes. Alternatively, you can use the new update-policy option.

Some sites choose to keep all dynamically updated DNS data in a subdomain and to delegate that subdomain to a separate zone. This way, the top-level zone containing critical data, such as the IP addresses of public web and mail servers, need not allow dynamic updates at all.

For information about setting up dynamic updates, see Section 6.4.7.

6.2.3. TSIG

This section describes how to set up Transaction Signatures (TSIG) transaction security in BIND. It describes changes to the configuration file as well as the changes that are required for different features, including the process of creating transaction keys and how to use transaction signatures with BIND.

BIND primarily supports TSIG for server-to-server communication. This includes zone transfer, notify, and recursive query messages.

TSIG is useful for dynamic updating. A primary server for a dynamic zone should use access control to control updates, but IP-based access control is insufficient. The cryptographic access control provided by TSIG is far superior. To use TSIG with the nsupdate utility, specify either the -k or -y option on the NSUPDATE command line. For more information about using the nsupdate utility, see Section 6.4.7.3.

Use the following procedure to implement TSIG:
  1. Generate shared keys for each pair of hosts.

    You can generate shared keys automatically, or you can specify them manually. In the example that follows, a shared secret is generated to be shared between HOST1 and HOST2. The key name is host1-host2. The key name must be the same on both hosts.

    Longer keys are better, but shorter keys are easier to read. The maximum key length is 512 bits; keys longer than that will be digested with MD5 to produce a 128-bit key. Use the dnssec-keygen utility to generate keys automatically.

    The following command generates a 128-bit (16-byte) HMAC-MD5 key:
    $ dnssec_keygen -a hmac-md5 -b 128 -n HOST host1-host2.
    In this example, the key is in the file KHOST1-HOST2.157-00000_PRIVATE. Nothing uses this file directly, but the base-64 encoded string following Key: can be extracted from the file and can be used as a shared secret. For example:
    Key: La/E5CjG9O+os1jq0a2jdA==

    The string La/E5CjG9O+os1jq0a2jdA== can be used as the shared secret.

    Keys can also be specified manually. The shared secret is a random sequence of bits, encoded in base-64. Most ASCII strings are valid base-64 strings (assuming the length is a multiple of 4 and that only valid characters are used).

  2. Copy the shared secret to both hosts.

    Use a secure transport mechanism like a floppy disk, or a physically secure network, to copy the shared secret between hosts.

  3. Inform the servers of the key's existence.

    In the following example, HOST1 and HOST2 are both servers. Add the following to each server's TCPIP$BIND.CONF file:
    key host1-host2. {
      algorithm hmac-md5;
      secret "La/E5CjG9O+os1jq0a2jdA==";
    };

    The HMAC-MD5 algorithm is the only one supported by BIND. It is recommended that either TCPIP$BIND.CONF not be world readable, or that the key statement be added to a nonworld readable file that is included by TCPIP$BIND.CONF. For information about the key statement, see Section 6.4.3.4.

    Once the configuration file is reloaded, the key is recognized. This means that if the server receives a message signed by this key, it can verify the signature. If the signature is successfully verified, the response is signed by the same key.

  4. Instruct the server to use the key.

    Because keys are shared only between two hosts, the server must be told when keys are to be used. Add the following to the TCPIP$BIND.CONF file for HOST1. The IP address of HOST2 is 10.1.2.3.
    server 10.1.2.3 {
      keys { host1-host2. ;};
    };

    Multiple keys can be present, but only the first is used. This statement does not contain any secrets, so you can include it in a world-readable file.

    If HOST1 sends a message that is a request to that address, the message will be signed with the specified key. HOST1 will expect any responses to signed messages to be signed with the same key.

    A similar statement must be present in HOST2's configuration file (with HOST1's address) for HOST2 to sign request messages to HOST1.

  5. Implement TSIG key-based access control.

    You can specify TSIG keys in ACL definitions and in the following configuration options:
    • allow-query

    • allow-transfer

    • allow-update

    For the key named HOST1-HOST2., specify the following allow-update option:
    allow-update { key host1-host2. ;};

    This statement allows dynamic updates to succeed only if the request was signed by a key named HOST1-HOST2.

  6. Reload the configuration file.

    Changes to the configuration file will not take effect until the configuration file is reloaded. You can use one of several methods to reload the configuration file:
    • The rndc utility

    • The TCP/IP management command SET NAME/INITIALIZE

    • Stopping and restarting the BIND server

  7. Handle any errors.

    The processing of TSIG-signed messages can result in several types of errors. If a signed message is sent to a non-TSIG aware server, an error is returned because the server will not understand the record. This is a result of misconfiguration; the server must be configured explicitly to send a TSIG-signed message to a specific server.

    If a TSIG-aware server receives a message signed by an unknown key, the response is unsigned and an error is returned.

    If a TSIG-aware server receives a message with a signature that is not validated, the response is unsigned and an error is returned.

    If a TSIG aware server receives a message with a time outside of the allowed range, the response is signed, an error is returned, and the time values are adjusted so that the response can be successfully verified.

6.2.4. TKEY

TKEY is a mechanism for automatically generating a shared secret between two hosts. There are several modes of TKEY that specify how the key is generated or assigned. BIND implements only the Diffie-Hellman key exchange. Both hosts are required to have a Diffie-Hellman KEY record (although this record is not required to be present in a zone). The TKEY process must use messages signed either by TSIG or SIG(0). The result of TKEY is a shared secret that can be used to sign messages with TSIG. TKEY can also be used to delete shared secrets that it had previously generated.

The TKEY process is initiated by a client or server by sending a signed TKEY query (including any appropriate KEYs) to a TKEY-aware server. The server response, if it indicates success, contains a TKEY record and any appropriate keys. After this exchange, both participants have enough information to determine the shared secret. When Diffie-Hellman keys are exchanged, the shared secret is derived by both participants.

6.2.5. SIG(0)

BIND 9 partially supports DNSSEC SIG(0) transaction signatures as specified in RFC 2535 and RFC2931.

SIG(0) uses public and private keys to authenticate messages. Access control is performed in the same manner as TSIG keys; privileges can be granted or denied based on the key name. When a SIG(0) signed message is received, it is verified only if the key is known and trusted by the server; the server does not attempt to locate and validate the key.

SIG(0) signing of multiple-message TCP streams is not supported. The only tool shipped with BIND Version 9 that generates SIG(0) signed messages is nsupdate.

6.2.6. DNSSEC

Cryptographic authentication of DNS information is implemented using the DNS Security (DNSSEC) extensions (defined in RFC's 4033, 4034, 4035).

BIND Version 9 provides several tools that are used in the process of creating and using DNSSEC signed zones. These tools include:
  • The dnssec_keygen utility, which generates keys for DNSSEC (secure DNS) and TSIG (transaction signatures).

  • The dnssec_signzone utility, which signs a zone and produces keyset and dsset files.

For detailed information about these utilities, see Section 6.9. In all cases, the -h option displays a full list of parameters. Note that the DNSSEC tools require the keyset files to be in the working directory.

Note

The tools shipped with TCP/IP Services V5.5 and earlier are not compatible with the current ones.

There must be communication with the administrators of the parent and/or child zone to transmit keys. A zone's security status must be indicated by the parent zone for a DNSSEC-capable resolver to trust its data. This is done through the presence or absence of a DS record at the delegation

For other servers to trust data in this zone, they must be statically configured either with this zone's zone key or with the zone key of another zone above this one in the DNS tree.

Use the following procedure to set up DNSSEC secure zones:
  1. Generate keys.

    To generate keys, use the dnssec_keygen program.

    A secure zone must contain one or more zone keys. The zone keys sign all other records in the zone, as well as the zone keys of any secure delegated zones. Zone keys must have the same name as the zone, must have a name type of ZONE, and must be usable for authentication.

    The following command generates a 768-bit DSA key for the child.example zone:
    $ $ dnssec_keygen -a DSA -b 768 -n ZONE child.example.

    Two output files are produced: KCHILD_EXAMPLE.003-12345_KEY and KCHILD_EXAMPLE.003-12345_PRIVATE (where 12345 is the key tag). The key file names contain the key name ( child_example. ), the algorithm (3 is DSA, 1 is RSAMD5, 5 is RSASHA1), and the key tag (12345, in this case). The private key (in the _PRIVATE file) is used to generate signatures, and the public key (in the _KEY file) is used to verify signatures.

    To generate another key with the same properties (but with a different key tag), repeat the preceding command.

    It is good practice to use zone-signing keys (ZSK) as well as key-signing keys (KSK). The key-signing keys are usually the first keys from your zone that are used to build a chain of authority to the data that needs to be validated. Therefore, these keys are often called a secure entry point (SEP) key. These SEP keys are the ones that you should exchange with your parents or that verifying resolvers configure as their trust anchors. Create keys with the SEP bit set by specifying the -f KSK flag:
    $dnssec_keygen -f KSK -a RSASHA1 -b 768 -n ZONE child.example
    Insert the public ZSK and KSK keys into the zone file using $INCLUDE statements that specify the _KEY files. For example, in the ZONE_CHILD_EXAMPLE.DB file add the following two lines:
    $INCLUDE KCHILD_EXAMPLE.005-39677_KEY
    $INCULDE KCHILD_EXAMPLE.005-39678_KEY

    where

    KCHILD_EXAMPLE.005-39677_KEY is the public file containing the ZSK and KCHILD_EXAMPLE.005-39678_KEY is the public file containing the KSK.

  2. Sign the zone.

    To sign a zone, use the dnssec_signzone utility.

    Any keyset files corresponding to secure subzones should be present. The zone signer will generate NSEC and RRSIG records for the zone, as well as DS for the child zones if -d is specified. If -d is not specified then DS RRsets for the secure child zones need to be added manually.

    The following command signs the zone, assuming it is in a file called ZONE_CHILD_EXAMPLE.DB.
    $ dnssec_signzone -o child.example -k KCHILD_EXAMPLE.005-39678_KEY
    ZONE_CHILD_EXAMPLE.DB KCHILD_EXAMPLE.005-39677_KEY

    Above, -o specifies the zone origin, -k specifies the file containing the KSK, followed by the name of the zone database, then the file containing the ZSK.

    One output file is produced: ZONE_CHILD_EXAMPLE.DB_SIGNED. This file should be referenced by TCPIP$BIND.CONF as the input file for the zone.

    dnssec_signzone will also produce a keyset and dsset files and optionally a dlvset file. These are used to provide the parent zone administrators with the DNSKEYs (or their corresponding DS records) that are the secure entry point to the zone.

  3. Configure the servers.

    Signatures are not verified when the BIND Version 9 software is loaded. Therefore, zone keys for authoritative zones do not need to be specified in the configuration file. The public key for any security root must be present in the configuration file's trusted-keys, as described in Section 6.4.

6.2.6.1. DNSSEC Restrictions

BIND Version 9 has the following restrictions when using DNSSEC:
  • Certain BIND server implementations do not support AAAA (IPv6 address) records. When queried for a AAAA (IPv6) record type by the BIND resolver, these name servers will return an NXDOMAIN status, even if an A (IPv4) record exists for the same domain name. These name servers should be returning NOERROR as the status for such a query. This problems can result in delays during host name resolution.

    BIND Version 9.3.1, which is supported with this version of TCP/IP Services does not exhibit this problem.

  • Serving secure zones

    When acting as an authoritative name server, BIND Version 9 includes KEY, SIG, and NXT records in responses as specified in RFC 2535 when the request has the DO flag set in the query.

    Response generation for wildcard records in secure zones is not fully supported. Responses indicating the nonexistence of a name include a NXT record proving the nonexistence of the name itself, but do not include any NXT records to prove the nonexistence of a matching wildcard record. Positive responses resulting from wildcard expansion do not include the NXT records to prove the nonexistence of a non-wildcard match or a more specific wildcard match.

  • Secure resolution

    Basic support for validation of DNSSEC signatures in responses has been implemented but should be considered experimental.

    When acting as a caching name server, BIND Version 9 is capable of performing basic DNSSEC validation of positive as well as nonexistence responses. This functionality is enabled by including a trusted-keys clause containing the top-level zone key of the DNSSEC tree in the configuration file.

    Validation of wildcard responses is not currently supported. In particular, a "name does not exist" response will validate successfully even if the server does not contain the NXT records to prove the nonexistence of a matching wildcard.

    Proof of insecure status for insecure zones delegated from secure zones works when the zones are completely insecure. Privately secured zones delegated from secure zones will not work in all cases, such as when the privately secured zone is served by the same server as an ancestor (but not parent) zone.

    Handling of the CD bit in queries is now fully implemented. Validation is not attempted for recursive queries if CD is set.

  • Secure dynamic update

    Dynamic updating of secure zones has been partially implemented. Affected NXT and SIG records are updated by the server when an update occurs. Use the update-policy statement in the zone definition for advanced access control.

  • Secure zone transfers

    BIND Version 9 does not implement the zone transfer security mechanisms of RFC 2535 because they are considered inferior to the use of TSIG or SIG(0) to ensure the integrity of zone transfers.

6.3. BIND Service Startup and Shutdown

The BIND service can be shut down and started independently of TCP/IP Services. The following files are provided for this purpose:
  • SYS$STARTUP:TCPIP$BIND_STARTUP.COM allows you to start the BIND service.

  • SYS$STARTUP:TCPIP$BIND_SHUTDOWN.COM allows you to shut down the BIND service.

To preserve site-specific parameter settings and commands, create the following files. These files are not overwritten when you reinstall TCP/IP Services.
  • SYS$STARTUP:TCPIP$BIND_SYSTARTUP.COM can be used as a repository for site-specific definitions and parameters to be invoked when the BIND service is started.

  • SYS$STARTUP:TCPIP$BIND_SYSHUTDOWN.COM can be used as a repository for site-specific definitions and parameters to be invoked when the BIND service is shut down.

6.4. Configuring the BIND Server

This section describes how to configure the BIND name server on your local host.

BIND Version 9 stores configuration information in a text file called TCPIP$BIND.CONF. The TCP/IP Services product provides a template for this file in the SYS$SPECIFIC:[TCPIP$BIND] directory. Before starting BIND, edit this template to reflect your site-specific configuration requirements.

6.4.1. Configuration File Elements

Table 6.1 lists the elements used throughout the BIND Version 9 configuration file documentation.
Table 6.1. Name Server Configuration File Elements

Element

Description

acl_name

The name of an address_match_list as defined by the acl statement.

address_match_list

A list of one or more of the following elements:
  • ip_addr

  • ip_prefix

  • key_id

  • acl_name

See Section 6.4.2 for more information.

domain_name

A quoted string that will be used as a DNS name. For example:
"my.test.domain"

dotted_decimal

One to four integers valued 0 through 255 and separated by dots, such as 123, 45.67 or 89.123.45.67.

ip4_addr

An IPv4 address with exactly four elements in dotted decimal notation.

ip6_addr

An IPv6 address, such as 2001:db8::1234. IPv6 scoped addresses that have ambiguity on their scope zones must be disambiguated by an appropriate zone ID with the percent character (`%') as delimiter. HP strongly recommends using string zone names rather than numeric identifiers, in order to be robust against system configuration changes. However, because there is no standard mapping for such names and identifier values, currently only interface names as link identifiers are supported, assuming one-to-one mapping between interfaces and links. For example, a link-local address fe80::1 on the link attached to the interface ne0 can be specified as fe80::1%ne0. Note that on most systems link-local addresses always have the ambiguity, and need to be disambiguated.

ip_addr

An ip4_addr or ip6_addr.

ip_port

An IP port number from 0 to 65535. Values below 1024 are restricted to well-known processes. In some cases, an asterisk (*) character can be used as a placeholder to select a random high-numbered port.

ip_prefix

An IP network specified as an ip_addr, followed by a slash (/) and then the number of bits in the netmask. Trailing zeros in an ip_addr can be omitted. For example, 127/8 is the network 127.0.0.0 with netmask 255.0.0.0 and 1.2.3.0/28 is network 1.2.3.0 with netmask 255.255.255.240.

key_id

A domain name representing the name of a shared key, to be used for transaction security.

key_list

A list of one or more key_ids, separated by semicolons and ending with a semicolon.

number

A nonnegative integer with an entire range limited by the range of a C language signed integer (2,147,483,647 on a machine with 32-bit integers). Its acceptable value might be limited further by the context in which it is used.

path_name

A quoted string that will be used as a path name. For example:
"SYS$SPECIFIC:[TCPIP$BIND]"

size_spec

A number, the word unlimited, or the word default. The maximum value of size_spec is that of unsigned long integers on the machine. An unlimited size_spec requests unlimited use, or the maximum available amount. A default size_spec uses the limit that was in force when the server was started. A number can optionally be followed by a scaling factor:
  • K (or k) for kilobytes, which scales by 1024

  • M (or m) for megabytes, which scales by 1024*1024

  • G (or g) for gigabytes, which scales by 1024*1024*1024

Integer storage overflow is silently ignored during conversion of scaled values, resulting in values less than intended, possibly even negative. Using the unlimited keyword is the best way to safely set a really large number.

yes_or_no

Either yes or no. The words true and false are also accepted, as are the numbers 1 and 0.

dialup_option

One of the following:
  • yes

  • no

  • notify

  • notify-passive

  • refresh

  • passive

When used in a zone, notify-passive, refresh, and passive are restricted to slave and stub zones.

6.4.2. Address Match Lists

Address match lists are primarily used to determine access control for various server operations. They are also used in the listen-on and sortlist statements. The following example shows the syntax of the address match list:
address_match_list = address_match_list_element ;
  [ address_match_list_element; ... ]
address_match_list_element = [ ! ] (ip_address [/length] |
   key key_id | acl_name | { address_match_list } )
The elements that constitute an address match list can be any of the following:
  • An IP address (IPv4 or IPv6)

  • An IP prefix (in the / notation)

  • A key ID, as defined by the key statement

  • The name of an address match list previously defined with the acl statement

  • A nested address match list enclosed in braces

Elements can be negated with a leading exclamation mark (!). The match list names any, none, localhost, and localnets are predefined. More information on those names can be found in the description of the acl statement (see Section 6.4.3.1).

When a given IP address or prefix is compared to an address match list, the list is traversed in order until an element matches. The interpretation of a match depends on whether the list is being used for access control, defining listen-on ports, or as a topology, and whether the element was negated. Specifically:
  • When used as an access control list, a non-negated match allows access and a negated match denies access. If there is no match, access is denied. The following options use address match lists for this purpose:
    • allow-notify

    • allow-query

    • allow-update-forwarding

    • allow-transfer

    • allow-update

    • blackhol

    The listen-on option causes the server not to accept queries on any of the machine's addresses that do not match the list.

Because of the first-match aspect of the algorithm, an element that defines a subset of another element in the list should come before the broader element, regardless of whether either is negated. For example, in 1.2.3/24; ! 1.2.3.13;, the 1.2.3.13 element is ignored, because the algorithm will match any lookup for 1.2.3.13 to the 1.2.3/24 element. Using ! 1.2.3.13; 1.2.3/24 corrects that problem by having 1.2.3.13 blocked by the negation, while all other 1.2.3.* hosts fall through.

6.4.3. Configuration File Format

A BIND configuration file consists of statements and comments. Statements end with a semicolon. Many statements contain a block of substatements that also end with a semicolon. Table 6.2 describes the configuration statements.
Table 6.2. BIND Name Server Configuration Statements

Statement

Description

acl

Specifies a named IP address matching list, for access control and other uses.

controls

Declares control channels to be used by the rndc utility.

include

Includes a file.

key

Specifies key information for use in authentication and authorization using TSIG. See Section 6.2.3 for more information.

logging

Specifies what the server logs, and where the log messages are sent.

masters

Defines a named masters list for inclusion in stub and slave zone masters clauses.

options

Controls global server configuration options and sets defaults for other statements.

server

Sets configuration options, and sets defaults for other statements.

trusted-keys

Specifies trusted DNSSEC keys.

view

Specifies a view.

zone

Specifies a zone.

The following sample is a configuration file for a master server:
options {
        directory "SYS$SPECIFIC:[TCPIP$BIND]";
};

zone "FRED.PARROT.BIRD.COM" in {
        type master;
        file "FRED_PARROT_BIRD_COM.DB";
};


zone "0.0.127.IN-ADDR.ARPA" in {
        type master;
        file "127_0_0.DB";
};

zone "LOCALHOST" in {
        type master;
        file "LOCALHOST.DB";
};

zone "208.20.16.IN-ADDR.ARPA" in {
        type master;
        file "208_20_16_IN-ADDR_ARPA.DB";
};

zone "." in {
        type hint;
        file "ROOT.HINT";
};


The following comment styles are valid in a BIND configuration file. Comments can appear anywhere in the file.
  • C-style comments that start with /* and end with */

  • C++ style comments that start with // and continue to the end of the physical line

  • Shell or Perl-style comments that start with # and continue to the end of the physical line


Note

Do not use a semicolon (;) as a comment character in your configuration file. The semicolon indicates the end of a configuration statement; whatever follows is interpreted as the start of the next statement.

6.4.3.1. The ACL Statement

The acl statement assigns a symbolic name to an address match list. It gets its name from a primary use of address match lists: access control lists (ACLs).

Note

The access control lists used by the BIND service and OpenVMS ACLs are different structures with different purposes.

The acl statement is formatted as follows:
acl acl-name {
    address_match_list
};

Note that the address match list must be defined with acl before it can be used elsewhere; forward references are not allowed.

The following ACLs are created automatically:

ACL

Matches

any

All hosts

none

No hosts

localhost

The IPv4 and IPv6 addresses of all interfaces on the system

localnets

Any host on an IPv4 or IPv6 network for which the system has an interface.

6.4.3.2. The CONTROLS Statement

The controls statement declares control channels to be used by system administrators to affect the operation of the local name server. These control channels are used by the rndc utility to send commands to, and retrieve non-DNS results from, a name server. The controls statement is formatted as follows:
controls {
   inet (ip_addr | * ) [ port ip_port ] allow {  address_match_list  }
                keys {  key_list  };
   [ inet ...; ]
};

An inet control channel is a TCP/IP socket listening at the specified ip_port on the specified ip_addr, which can be either an IPv4 or IPv6 address. The asterisk character (*) is interpreted as the IPv4 wildcard address; connections are accepted on any of the system's IPv4 addresses. To listen on the IPv6 wildcard address, use :: for the ip_addr. If you use the rndc utility only on the local host, use the local loopback address (127.0.0.1, or ::) for maximum security.

If no port is specified, port 953 is used. * cannot be used for ip_port.

The ability to issue commands over the control channel is restricted by the allow and keys clauses. Connections to the control channel are permitted based on the address match list. This is for simple IP address based filtering only; any key_id elements of the address_match_list are ignored.

The primary authorization mechanism of the command channel is the key_list, which contains a list of key_ids. Each key_id in the key_list is authorized to execute commands over the control channel. See the section called “Format of the RNDC.CONF File” for information about configuring keys in rndc.

If no controls statement is present, the BIND server will set up a default control channel listening on the loopback address 127.0.0.1 and its IPv6 counterpart ::1. In this case, and also when the controls statement is present but does not have a keys clause, the BIND server attempts to load the command channel key from the file RNDC.KEY in TCPIP$ETC. To create a RNDC.KEY file, use the following command: rndc_confgen -a

See Section 6.9 for more information about using the rndc utility.

The RNDC.KEY feature eases the transition of systems from BIND Version 8, which did not have digital signatures on its command channel messages and thus did not have a keys clause. You can use an existing BIND Version 8 configuration file in BIND Version 9 unchanged, and rndc will work the same way that ndc worked in BIND Version 8.

Because the RNDC.KEY feature is only intended to allow the backward-compatible usage of BIND Version 8 configuration files, this feature does not have a high degree of configurability. You cannot easily change the key name or the size of the secret. You should make a RNDC.CONF file with your own key if you wish to change those things.

The UNIX control channel type of BIND Version 8 is not supported in BIND Version 9 and is not expected to be added in future releases. If it is present in the controls statement from a BIND Version 8 configuration file, it is ignored and a warning is logged.

To disable the command channel, use an empty controller statement. For example:
controls { };

6.4.3.3. The INCLUDE Statement

The include statement inserts the specified file at the point that the include statement is encountered. The include statement facilitates the administration of configuration files by permitting the reading or writing of some things but not others. For example, the statement could include private keys that are readable only by a name server. The following example shows the format of the include statement:
include filename;

6.4.3.4. The KEY Statement

The key statement defines a shared secret key for use with TSIG (see Section 6.2.3) or the command channel (see Section 6.4.3.2). The following example shows the format of the key statement:
key key_id {
    algorithm algorithm-id;
    secret secret-string;
};

The key statement can occur at the top level of the configuration file or inside a view statement. Keys defined in top-level key statements can be used in all views. Keys intended for use in a controls statement must be defined at the top level.

Table 6.3 describes the elements of the key statement.
Table 6.3. Key Statement Elements

Element

Description

key_id

Specifies a domain name that uniquely identifies the key (also known as the key name). It can be used in a server statement to cause requests sent to that server to be signed with this key, or in address match lists to verify that incoming requests have been signed with a key matching this name, algorithm, and secret.

algorithm-id

Specifies an authentication algorithm. The only algorithm currently supported with TSIG authentication is HMAC-MD5.

secret-string

Specifies the secret to be used by the algorithm; treated as a Base-64 encoded string.

6.4.3.5. The LOGGING Statement

The logging statement configures a wide variety of logging options for the name server. Its channel phrase associates output methods, format options and severity levels with a name that can then be used with the category phrase to select the way each class of message is logged. The following example shows the format of the logging statement:
logging {
   [ channel channel_name {
     (file path_name
             [size size_spec]
       | syslog | stderr | null );
     [ severity (critical | error | warning | notice |
                 info | debug [ level ] | dynamic ); ]
     [ print-category yes_or_no; ]
     [ print-severity yes_or_no; ]
     [ print-time yes_or_no; ]
   }; ]
   [ category category_name {
     channel_name ; [ channel_name ; ... ]
   }; ]
   ...
};
Use one logging statement to define as many channels and categories as you want. If there is no logging statement, the logging configuration defaults to the following:
logging {
     category default { default_syslog; default_debug; };
     category unmatched { null; };
     };

In BIND Version 9, the logging configuration is only established after the entire configuration file has been parsed. When the server is starting up, all logging messages regarding syntax errors in the configuration file go to the default channels.

6.4.3.5.1. The Channel Phrase

All log output goes to one or more channels; you can make as many of them as you want. Every channel definition must include a destination clause that says whether messages selected for the channel go to a file (by default, TCPIP$BIND_RUN.LOG), or are discarded. It can optionally also limit the message severity level that is accepted by the channel (the default is info); and can specify whether to include a time stamp, the category name and severity level (the default is not to include any).

The null destination clause causes all messages sent to the channel to be discarded; in that case, other options for the channel are meaningless.

The file destination clause directs the channel to a disk file. The size option for files is used to limit log file growth. The parameter (size_spec) is specified in bytes, but shorthand notation can be used (for example, 100K, or 2M for 2 MB). If the file exceeds the size, the BIND server stops writing to the file; no file version rollover occurs. After that, no data is written to the file until the server is restarted, reloaded, or until the file is truncated manually.

On OpenVMS, the syslog and stderr destination clauses direct the channel to the TCPIP$BIND_RUN.LOG file.

The severity clause allows you to specify the level of diagnostic messages to be logged.

The server can supply extensive debugging information when it is in debugging mode. If the server's global debug level is greater than zero, then debugging mode is activated. The global debug level is set by one of the following:
  • Starting the BIND server with the -d flag followed by a positive integer.

  • Entering the trace command with the rndc utility. To set the global debug level to zero and turn off debugging mode, enter the notrace command.

All debugging messages in the server have a debug level; higher debug levels give more detailed output. Channels that specify a debug severity level get the specified debugging output and less any time the server is in debugging mode, regardless of the global debugging level. For example, to produce debugging output at level 3 and less, enter the following:
channel specific_debug_level {
    file "foo";
    severity debug 3;
};

Channels with dynamic severity use the server's global level to determine what messages to display.

If print-time is turned on, the date and time are logged. If print-category is requested, then the category of the message is logged as well. Finally, if print-severity is turned on, then the severity level of the message is logged. The print- options can be used in any combination and are always displayed in the following order:
  1. Time

  2. Category

  3. Severity

The following example specifies all three print- options:
28-Feb-2000 15:05:32.863 general: notice: running
Four predefined channels are used for the BIND server's default logging, as shown in the following example. Section 6.4.3.5.2 describes how these channels are used.
channel default_syslog {
    syslog daemon;                 // send to TCPIP$BIND_RUN.LOG

    severity info;                 // only send priority info
                                   // and higher
};

channel default_debug {
    file "TCPIP$BIND_RUN.LOG";     // write to the TCPIP$BIND_RUN.LOG

    severity dynamic;              // log at the server's
                                   // current debug level
};

channel default_stderr {
    stderr;                        // write to TCPIP$BIND_RUN.LOG
    severity info;                 // only send priority info
                                   // and higher
};

channel null {
   null;                           // discard anything sent to
                                   // this channel
};

The default_debug channel only produces output when the server's debug level is not zero. By default, the BIND server writes to the TCPIP$BIND_RUN.LOG file.

Once a channel is defined, it cannot be redefined. Thus, you cannot alter the built-in channels directly, but you can modify the default logging by pointing categories at channels you have defined.

6.4.3.5.2. The Category Phrase
There are many categories, so you can send the logs you want to see anywhere, without seeing logs you do not want. If you do not specify a list of channels for a category, then log messages in that category are sent to the default category instead. If you do not specify a default category, the following definition is used:
category default { default_syslog; default_debug; };
For example, if you want to log security events to a file but you also want to preserve the default logging behavior, specify the following:
channel my_security_channel {
    file "my_security_file";
    severity info;
};
category security {
    "my_security_channel";
    default_syslog;
    default_debug;
};
To discard all messages in a category, specify the null channel:
category lame-servers { null; };
category cname { null; };
Table 6.4 describes the logging categories.
Table 6.4. Logging Categories

Category

Meaning

default

The logging options for those categories where no specific configuration has been defined.

general

The default category for messages that are not classified.

database

Messages relating to the databases used internally by the name server to store zone and cache data.

security

Approval and denial of requests.

config

Configuration file parsing and processing.

resolver

DNS resolution, such as the recursive lookups performed on behalf of clients by a caching name server.

xfer-in

Zone transfers the server is receiving.

xfer-out

Zone transfers the server is sending.

notify

The NOTIFY protocol.

client

Processing of client requests.

unmatched

Messages for which the BIND server was unable to determine the class, or for which there was no matching view. A one-line summary is also logged to the client category.

network

Network operations.

update

Dynamic updates.

update-security

Approval and denial of update requests.

queries

Queries. Specify where queries should be logged to. At startup, specifying the category queries will also enable query logging unless querylog option has been specified. The query log entry reports the client's IP address and port number. The query name, class and type. It also reports whether the Recursion Desired flag was set (+ if set, - if not set), EDNS was in use (E) or if the query was signed (S).
client 127.0.0.1#62536: query: www.example.com IN AAAA +SE
client ::1#62537: query: www.example.net IN AAAA -SE

dispatch

Dispatching of incoming packets to the server modules where they are to be processed.

dnssec

DNSSEC and TSIG protocol processing.

lame-servers

Lame servers (misconfigurations in remote servers, discovered by BIND 9 when trying to query those servers during resolution).

delegation-only

Delegation only. Logs queries that have been forced to NXDOMAIN as the result of a delegation-only zone or a delegation-only in a hint or stub zone declaration.File

queries

Specifies where queries should be logged to. At startup, specifying the category queries will also enable query logging unless the querylog option has been specified. The query log entry reports the client's IP address and port number. The query name, class and type. It also reports whether the Recursion Desired flag was set (+ if set, - if not set), EDNS was in use (E), or if the query was signed (S).
client 127.0.0.1#62536: query: www.example.com IN AAAA +SE
client ::1#62537: query: www.example.net IN AAAA -SE

dispatch

Dispatching of incoming packets to the server modules where they are to be processed.

dnssec

DNSSEC and TSIG protocol processing.

lame-servers

Lame servers (misconfiguraitons in remote servers, discovered by BIND 9 when trying to query those servers during resollution).

delegation-only

Delegation only. Logs queries that have been forced to NXDOMAIN as the result of a delegation-only zone or a delegation-only in a hint or stub zone declaration.

6.4.3.6. The MASTERS Statement

The masters statement allows for a common set of masters to be easily used by multiple stub and slave zones.

The masters statement has the following syntax:
masters name [port ip_port] { (masters_list | ip_addr [port ip_port]
[key key] ) ; [...] } ;

6.4.3.7. The OPTIONS Statement

The options statement sets up global options to be used by BIND. This statement should appear only once in a configuration file. If there is no options statement, an options block with each option set to its default is used.

The options statement has the following syntax:
options {
  [ version version_string; ]
  [ hostname hostname_string; ]
  [ server-id server_id_string; ]
  [ directory path_name; ]
  [ key-directory path_name; ]
 
  [ named-xfer path_name; ]
  [ tkey-domain domainname; ]
  [ tkey-dhkey key_name key_tag; ]
  [ dump-file path_name; ]
  [ memstatistics-file path_name; ]
  [ pid-file path_name; ]
  [ statistics-file path_name; ]
  [ zone-statistics yes_or_no; ]
  [ auth-nxdomain yes_or_no; ]
  [ deallocate-on-exit yes_or_no; ]
  [ dialup dialup_option; ]
  [ fake-iquery yes_or_no; ]
  [ fetch-glue yes_or_no; ]
  [ flush-zones-on-shutdown yes_or_no; ]
  [ has-old-clients yes_or_no; ]
  [ host-statistics yes_or_no; ]
  [ host-statistics-max number; ]
  [ minimal-responses yes_or_no; ]
  [ multiple-cnames yes_or_no; ]
  [ notify yes_or_no | explicit; ]
  [ recursion yes_or_no; ]
  [ rfc2308-type1 yes_or_no; ]
  [ use-id-pool yes_or_no; ]
  [ maintain-ixfr-base yes_or_no; ]
  [ dnssec-enable yes_or_no; ]
  [ dnssec-lookaside domain trust-anchor domain; ]
  [ dnssec-must-be-secure domain yes_or_no; ]
  [ forward (only | first ); ]
  [ forwarders { ip_addr [port ip_port] ; [ ip_addr [port ip_port] ;  ... ]
  }; ]
  [ dual-stack-servers [port ip_port] { (domain_name [port ip_port] | 
  ip_addr
  [port ip_port] ) ; ... }; ]
  [ check-names (master | slave |  response )(warn | fail | ignore ); ]
  [ allow-notify { address_match_list }; ]
  [ allow-query { address_match_list }; ]
  [ allow-transfer { address_match_list }; ]
  [ allow-recursion { address_match_list }; ]
  [ allow-update-forwarding { address_match_list }; ]
  [ allow-v6-synthesis { address_match_list }; ]
  [ blackhole { address_match_list }; ]
  [ avoid-v4-udp-ports { port_list }; ]
  [ avoid-v6-udp-ports { port_list }; ]
  [ listen-on [ port ip_port ] { address_match_list }; ]
  [ listen-on-v6 [ port ip_port ] { address_match_list }; ]
  [ query-source [ address (ip_addr | * ) ] [ port (ip_port | * ) ];  ]
  [ query-source-v6 [ address (ip_addr | * ) ] [ port (ip_port | * ) ];  ]
  [ max-transfer-time-in number; ]
  [ max-transfer-time-out number; ]
  [ max-transfer-idle-in number; ]
  [ max-transfer-idle-out number; ]
  [ tcp-clients number; ]
  [ recursive-clients number; ]
  [ serial-query-rate number; ]
  [ serial-queries number; ]
  [ tcp-listen-queue number; ]

  [ transfer-format (one-answer | many-answers ); ]
  [ transfers-in  number; ]
  [ transfers-out number; ]
  [ transfers-per-ns number; ]
  [ transfer-source (ip4_addr | *) [port ip_port] ; ]
  [ transfer-source-v6 (ip6_addr | *) [port ip_port] ; ]
  [ alt-transfer-source (ip4_addr | *) [port ip_port] ; ]
  [ alt-transfer-source-v6 (ip6_addr | *) [port ip_port] ; ]
  [ use-alt-transfer-source yes_or_no; ]
  [ notify-source (ip4_addr | *) [port ip_port] ; ]
  [ notify-source-v6 (ip6_addr | *) [port ip_port] ; ]
  [ also-notify { ip_addr [port ip_port] ; [ ip_addr [port ip_port] ;  ... ]
  };
  ]
  [ max-ixfr-log-size number; ]
  [ max-journal-size size_spec; ]
  [ cleaning-interval number; ]
  [ heartbeat-interval number; ]
  [ interface-interval number; ]
  [ statistics-interval number; ]
  [ topology { address_match_list }];
  [ sortlist { address_match_list }];
  [ rrset-order { order_spec ; [ order_spec ; ... ] ] };
  [ lame-ttl number; ]
  [ max-ncache-ttl number; ]
  [ max-cache-ttl number; ]
  [ sig-validity-interval number ; ]
  [ min-roots number; ]
  [ use-ixfr yes_or_no ; ]
  [ provide-ixfr yes_or_no; ]
  [ request-ixfr yes_or_no; ]
  [ treat-cr-as-space yes_or_no ; ]
  [ min-refresh-time number ; ]
  [ max-refresh-time number ; ]
  [ min-retry-time number ; ]
  [ max-retry-time number ; ]
  [ port ip_port; ]
  [ additional-from-auth yes_or_no ; ]
  [ additional-from-cache yes_or_no ; ]
  [ random-device path_name ; ]
  [ max-cache-size size_spec ; ]
  [ match-mapped-addresses yes_or_no; ]
  [ preferred-glue (A | AAAA | NONE ); ]
  [ edns-udp-size number; ]
  [ root-delegation-only [ exclude { namelist } ] ; ]
  [ querylog yes_or_no ; ]
  [ disable-algorithms domain { algorithm; [ algorithm; ] }; ]
};
Table 6.5 through Table 6.14 describe the BIND server configuration options.
Table 6.5. BIND Server Configuration Options

Option

Description

version

The version the server should report using a query of name version.bind in class CHAOS. The default is the real version number of this server.

directory

The working directory of the server. Any nonabsolute path names in the configuration file is assumed to be relative to this directory. The default location for the server output file (TCPIP$BIND_RUN.LOG) is this directory. If a directory is not specified, the working directory defaults to SYS$SPECIFIC:[TCPIP$BIND]. If you are configuring a BIND failover environment in an OpenVMS Cluster, the working directory is defined by the logical TCPIP$BIND_COMMON.

key-directory

When performing dynamic update of secure zones, the directory where the public and private key files should be found, if different than the current working directory. The directory specified must be an absolute path.

named-xfer

This option is obsolete. In BIND 9, no separate named-xfer program is needed; its functionality is built into the name server.

tkey-domain

The domain appended to the names of all shared keys generated with TKEY. When a client requests a TKEY exchange, it may or may not specify the desired name for the key. If present, the name of the shared key is formatted as follows:
client specified part + 
tkey-domain
If it is not present, the name of the shared key is formatted as follows:
random hex digits + 
tkey-domain

In most cases, the domain name should be the server's domain name.

tkey-dhkey

The Diffie-Hellman key used by the server to generate shared keys with clients using the Diffie-Hellman mode of TKEY. The server must be able to load the public and private keys from files in the working directory. In most cases, the key name should be the server's host name.

dump-file

The path name of the file the server dumps the database to when instructed to do so with the rndc dumpdb command. If not specified, the default is TCPIP$BIND_DUMP.DB.

memstatistics-file

The path name of the file the server writes memory usage statistics to on exit. If not specified, the default is TCPIP$BIND.MEMSTATS.

pid-file

The path name of the file in which the server writes its process ID.If the path name is not specified, the default is TCPIP$BIND.PID. The PID file is used by programs that want to send signals to the running name server. Specifying pid-file none disables the use of a PID file - no file will be written and any existing one will be removed. Note that none is a keyword, not a file name, and therefore is not enclosed in double quotes.

statistics-file

The path name of the file to which the server appends statistics when instructed to do so with the rndc stats command. If not specified, the default is TCPIP$BIND.STATS in the server's current directory. The format of the file is described in Section 6.4.3.7.16.

port

The UDP/TCP port number the server uses for receiving and sending DNS protocol traffic. The default is 53. This option is intended mainly for server testing; a server using a port other than 53 cannot communicate with the global DNS.

preferred-glue

If specified the listed type (A or AAAA) will be emitted before other glue in the additional section of a query response. The default is not to preference any type (NONE).

root-delegation-only

Turn on enforcement of delegation-only in TLDs and root zones with an optional exclude list. Note some TLDs are NOT delegation only (e.g. "DE", "LV", "US" and "MUSEUM").
options
{
             root-delegation-only exclude { "de"; "lv"; "us"; "museum"; };
};

disable-algorithms

Disable the specified DNSSEC algorithms at and below the specified name. Multiple disable-algorithms statements are allowed. Only the most specific will be applied.

dnssec-lookaside

When set dnssec-lookaside provides the validator with an alternate method to validate DNSKEY records at the top of a zone. When a DNSKEY is at or below a domain specified by the deepest dnssec-lookaside, and the normal dnssec validation has left the key untrusted, the trust-anchor will be append to the key name and a DLV record will be looked up to see if it can validate the key. If the DLV record validates a DNSKEY (similarly to the way a DS record does) the DNSKEY RRset is deemed to be trusted.

dnssec-must-be-secure

Specify heirarchies which must or may not be secure (signed and validated). If yes, then the BIND server will only accept answers if they are secure. If no, then normal dnssec validation applies allowing for insecure answers to be accepted. The specified domain must be under a trusted-key or dnssec-lookaside must be active.

random-device

The source of entropy to be used by the server. Entropy is needed primarily for DNSSEC operations, such as TKEY transactions and dynamic update of signed zones. This option specifies the file from which to read entropy. Operations requiring entropy fail when the file has been exhausted. If this option is not specified, entropy does not take place.

The random-device option takes effect during the initial configuration load at server startup time and is ignored on subsequent reloads.

6.4.3.7.1. Boolean Options
Table 6.6 describes the Boolean BIND server configuration options.
Table 6.6. BIND Server Boolean Configuration Options

Option

Description

auth-nxdomain

If YES, then the AA bit is always set on NXDOMAIN responses, even if the server is not actually authoritative.

The default is NO.

deallocate-on-exit

BIND Version 9 ignores this option and always performs the checks.

dialup

If YES, then the server treats all zones as if they are doing zone transfers across a dial-on-demand dialup link, which can be brought up by traffic originating from this server. This has different effects according to zone type, and it concentrates the zone maintenance so that it all happens in a short interval, once every heartbeat-interval and during the one call. It also suppresses some of the normal zone maintenance traffic. The default is NO.

The dialup option can also be specified in the view and zone statements. In these cases, it overrides the global dialup option.

If the zone is a master zone then the server will send out a NOTIFY request to all the slaves (default). This should trigger the zone serial number check in the slave (providing it supports NOTIFY) allowing the slave to verify the zone while the connection is active. The set of servers to which NOTIFY is sent can be controlled by notify and also-notify.

If the zone is a slave or stub zone, then the server will suppress the regular "zone up to date" (refresh) queries and only perform them when the heartbeat-interval expires in addition to sending NOTIFY requests.

Finer control can be achieved by using notify which only sends NOTIFY messages, notify-passive which sends NOTIFY messages and suppresses the normal refresh queries, refresh which suppresses normal refresh processing and sends refresh queries when the heartbeat-interval expires, and passive, which just disables normal refresh processing. Note that normal NOTIFY processing is not affected by dialup.

Dialup Mode

Normal Refresh

Heart-beat Refresh

Heart-beat Notify

no (default)

yes

no

no

yes

no

yes

yes

notify

yes

no

yes

refresh

no

yes

no

passive

no

no

no

notify-passive

no

no

yes

flush-zones-on-shutdown

When the nameserver exits due to receiving SIGTERM, flush or do not flush any pending zone writes. The default is flush-zones-on-shutdown no.

fetch-glue

This option is obsolete. In BIND Version 9, the server does not fetch glue resource records.

has-old-clients

This option is ignored by BIND Version 9.

host-statistics

This option is not implemented in BIND Version 9.

maintain-ixfr-base

This option is obsolete. BIND Version 9 maintains a transaction log whenever possible. To disable outgoing incremental zone transfers, set the provide-ixfr option to NO. See Section 6.4.3.8 for more information.

minimal-responses

Specifies that when the server generates responses, it adds records to the authority and additional data sections only when they are required (for example, for delegations and negative responses). This might improve the performance of the server. The default is NO.

multiple-cnames

This option was used in BIND Version 8 to allow a domain name to allow multiple CNAME records in violation of the DNS standards. BIND Version 9 strictly enforces the CNAME rules, both in master files and dynamic updates.

notify

Sends DNS NOTIFY messages when a zone changes for which the server is authoritative (see Section 6.4.5). The messages are sent to the servers listed in the zone's NS records (except the master server identified in the SOA MNAME field) and to any servers listed in the also-notify option. If this option is explicitly set (the default), notifications are sent only to servers explicitly listed using also-notify. If it is set to NO, notifications are not sent.

The notify option can also be specified in the zone statement. This overrides the notify option in the options statement.

recursion

When a DNS query requests recursion, specifies that the server will attempt to do all the work required to answer the query. If the recursion option is off and the server does not already know the answer, it returns a referral response. The default is YES. Note that setting the recursion option to NO does not prevent clients from getting data from the server's cache; it only prevents new data from being cached as an effect of client queries. Caching can still occur as an effect of the server's internal operation, such as NOTIFY address lookups.

rfc2308-type1

Setting this option to YES causes the server to send NS records along with the SOA record for negative answers. The default is NO.

This option is not yet implemented.

use-id-pool

This option is obsolete. BIND Version 9 always allocates query IDs from a pool.

zone-statistics

Collects statistical data on all zones in the server (unless specifically turned off on a per-zone basis by specifying zone-statistics no in the zone statement).

use-ixfr

This option is obsolete. If you need to disable IXFR to a particular server, see the information about the provide-ixfr option in Section 6.4.3.8.

additional-from-auth

additional-from-cache

These options control the behavior of an authoritative server when answering queries that have additional data or when following CNAME and DNAME chains.

When both of these options are set to YES (the default) and a query is being answered from authoritative data (a zone configured into the server), the additional data section of the reply is filled in using data from other authoritative zones and from the cache. In some situations this is undesirable, such as when there is concern over the correctness of the cache, or in servers where slave zones can be added and modified by untrusted third parties. Also, avoiding the search for this additional data speeds up server operations at the possible expense of additional queries to resolve what otherwise would be provided in the additional section.

For example, if a query asks for an MX record for host FOO.EXAMPLE.COM, the following record is found:
MX 10 mail.example.net

The address records (A and AAAA) for MAIL.EXAMPLE.NET are provided as well, if they are known, even though they are not in the example.com zone.

Setting these options to NO disables this behavior and makes the server only search for additional data in the zone it answers from.

These options are intended for use in authoritative-only servers or in authoritative-only views. If you attempt to set these options to NO without also specifying recursion no, the server ignores the options and log a warning message.

Specifying additional-from-cache no disables the use of the cache not only for additional data lookups, but also when looking up the answer. This is usually the desired behavior in an authoritative-only server where the correctness of the cached data is an issue.

When a name server is nonrecursively queried for a name that is not below the apex of any served zone, it normally answers with an upward referral to the root servers or to the servers of some other known parent of the query name. Because the data in an upward referral comes from the cache, the server cannot provide upward referrals when additional-from-cache no has been specified. Instead, the server responds to such queries with REFUSED. This should not cause any problems, because upward referrals are not required for the resolution process.

match-mapped-addresses

When this option is set, an IPv4-mapped IPv6 address matches any address match list entries that match the corresponding IPv4 address. Use of this option is not necessary on OpenVMS systems.

ixfr-from-differences

When 'yes' and the server loads a new version of a master zone from its zone file or receives a new version of a slave file by a non-incremental zone transfer, it will compare the new version to the previous one and calculate a set of differences. The differences are then logged in the zone's journal file such that the changes can be transmitted to downstream slaves as an incremental zone transfer.

By allowing incremental zone transfers to be used for non-dynamic zones, this option saves bandwidth at the expense of increased CPU and memory consumption at the master. In particular, if the new version of a zone is completely different from the previous one, the set of differences will be of a size comparable to the combined size of the old and new zone version, and the server will need to temporarily allocate memory to hold this complete difference set.

multi-master

This should be set when you have multiple masters for a zone and the addresses refer to different machines. If 'yes' BIND will not log when the serial number on the master is less than what named currently has. The default is no.

dnssec-enable

Enable DNSSEC support in the BIND Server. Unless set to yes BIND behaves as if it does not support DNSSEC. The default is no.

querylog

Specify whether query logging should be started when the BIND server starts. If querylog is not specified then the query logging is determined by the presence of the logging category queries.

check-names

This option is used to restrict the character set and syntax of certain domain names in master files and/or DNS responses received from the network. The default varies according to usage area. For master zones the default is fail. For slave zones the default is warn. For answer received from the network (response) the default is ignore.

The rules for legal hostnames/mail domains are derived from RFC 952 and RFC 821 as modified by RFC 1123.

check-names applies to the owner names of A, AAAA, and MX records. It also applies to the domain names in the RDATA of NS, SOA and MX records. It also applies to the RDATA of PTR records where the owner name indicated that it is a reverse lookup of a hostname. The owner name ends in IN-ADDR.ARPA, IP6.ARPA, IP6.INT.

6.4.3.7.2. Forwarding Options

The forwarding facility helps you create a large, sitewide cache on a few servers, thereby reducing traffic over links to external name servers. It can also be used to allow queries by servers that do not have direct access to the Internet but that want to look up exterior names anyway. Forwarding occurs only on those queries for which the server is not authoritative and does not have the answer in its cache.

Table 6.7 describes the forwarding options.
Table 6.7. Forwarding Options

Option

Description

forward

Meaningful only if the forwarders list is not empty. A value of first (the default) causes the server to query the forwarders first, and if that does not answer the question, the server then looks for the answer itself. If only is specified, the server queries only the forwarders.

forwarders

Specifies the IP addresses to be used for forwarding. The default is the empty list (no forwarding).

Forwarding can also be configured on a per-domain basis, allowing for the global forwarding options to be overridden in a variety of ways. You can set particular domains to use different forwarders, or have a different forward only/first behavior, or not to forward at all. See Section 6.4.3.11 for more information.

6.4.3.7.3. Dual-stack Servers

Dual-stack servers are used as servers of last resort to work around problems in reachability due the lack of support for either IPv4 or IPv6 on the host machine.

Table 6.8 describes the dual-stack server options.
Table 6.8. Dual-stack Server Options

Option

Description

dual-stack-servers

Specifies host names/addresses of machines with access to both IPv4 and IPv6 transports. If a hostname is used the server must be able to resolve the name using only the transport it has.

6.4.3.7.4. Access Control Options

Access to the server can be restricted based on the IP address of the requesting system. See Section 6.4.2 for details on how to specify IP address lists.

Table 6.9 describes the access control options.
Table 6.9. Access Control Options

Option

Description

allow-notify

Specifies which hosts are allowed to notify this server, a slave, of zone changes in addition to the zone masters. The allow-notify option can also be specified in the zone statement; in this case, it overrides the allow-notify option in the options statement. The allow-notify option is meaningful only for a slave zone. If this option is not specified, the default is to process notify messages from only a zone's master.

allow-query

Specifies which hosts are allowed to ask ordinary DNS questions. The allow-query option can also be specified in the zone statement; in this case, it overrides the allow-query option in the options statement. If this option is not specified, the default is to allow queries from all hosts.

allow-recursion

Specifies which hosts are allowed to make recursive queries through this server. If this option is not specified, the default is to allow recursive queries from all hosts. Note that disallowing recursive queries for a host does not prevent the host from retrieving data that is already in the server's cache.

allow-update-forwarding

Specifies which hosts are allowed to submit Dynamic DNS updates to slave zones to be forwarded to the master. The default is { none; }, which means that no update forwarding will be performed. To enable update forwarding, specify allow-update-forwarding { any; };. Specifying values other than {none; } or { any; } is usually counterproductive, since the responsibility for update access control should rest with the master server, not the slaves.

Note that enabling the update forwarding feature on a slave server may expose master servers relying on insecure IP address based access control to attacks.

allow-v6-synthesis

This option was introduced for the smooth transition from AAAA to A6 and from "nibble labels" to binary labels. However, since both A6 and binary labels were then deprecated, this option was also deprecated. It is now ignored with some warning messages.

allow-transfer

Specifies which hosts are allowed to receive zone transfers from the server. The allow-transfer option can also be specified in the zone statement; in this case, it overrides the allow-transfer statement in the options statement. If this option is not specified, the default is to allow transfers to all hosts.

blackhole

Specifies a list of addresses from which the server will not accept queries or will not use to resolve a query. The server will not respond queries from these addresses. The default is NONE.

6.4.3.7.5. Interfaces Options
The interfaces and ports from which the server answers queries can be specified using the listen-on options. Table 6.10 describes the listen-on options.
Table 6.10. Interfaces Options

Option

Description

listen-on

Specifies the port for listening for queries sent using IPv4 addresses.

The listen-on option takes an optional port number and an address_match_list. The server listens on all interfaces allowed by the address match list. If a port is not specified, port 53 is used.

Multiple listen-on statements are allowed. For example:
listen-on { 5.6.7.8; };
listen-on port 1234 { !1.2.3.4; 1.2/16; };

These statements enable the name server on port 53 for the IP address 5.6.7.8, and on port 1234 of an address on the machine in net 1.2 that is not 1.2.3.4.

If the listen-on option is not specified, the server listens on port 53 on all interfaces.

listen-on-v6

Specifies the interfaces and the ports on which the server will listen for incoming queries sent using IPv6.

When { any; } is specified as the address_match_list for the listen-on-v6 option, the server does not bind a separate socket to each IPv6 interface address as it does for IPv4. Instead, it listens on the IPv6 wildcard address.

A list of particular IPv6 addresses can also be specified, in which case the server listens on a separate socket for each specified address, regardless of whether the desired API is supported by the system.

Multiple listen-on-v6 options can be used. For example,

listen-on-v6 { any; };
listen-on-v6 port 1234 { !2001:db8::/32; any; };

will enable the name server on port 53 for any IPv6 addresses (with a single wildcard socket), and on port 1234 of IPv6 addresses that is not in the prefix 2001:db8::/32 (with separate sockets for each matched address.)

To make the server not listen on any IPv6 address, use
listen-on-v6 { none; };

If no listen-on-v6 option is specified, the server will not listen on any IPv6 address.

6.4.3.7.6. The Query Address Options

If the server does not know the answer to a question, it queries other name servers. The query address options allow you to specify the address and port for these queries.

Table 6.11 describes the query address options.
Table 6.11. Query Address Options

Option

Description

query-source
Specifies the IPv4 address and port used for such queries. If the address is a wildcard character or is omitted, a wildcard IP address (INADDR_ANY) is used. If the port is a wildcard character or is omitted, a random unprivileged port is used. avoid-v4-udp-ports and avoid-v6-udp-ports can be used to prevent named from selecting certain ports. The default is:
query-source address * port *;
query-source-v6
Specifies the IPv6 address and port used for such queries. The default is:
query-source-v6 address * port *

The address specified in the query-source option is used for both UDP and TCP queries, but the port applies only to UDP queries. TCP queries always use a random, unprivileged port.

6.4.3.7.7. Zone Transfer Options
BIND includes mechanisms to facilitate zone transfers and to limit the amount of load that transfers place on the system. Table 6.12 describes the zone transfer options.
Table 6.12. Zone Transfer Options

Option

Description

also-notify

Defines a global list of IP addresses of name servers that are also sent NOTIFY messages whenever a fresh copy of the zone is loaded, in addition to the servers listed in the zone's NS records. This helps to ensure that copies of the zones will quickly converge on stealth servers. If an also-notify list is given in a zone statement, that list overrides the also-notify options in the options statement. When a zone notify statement is set to NO, the IP addresses in the global also-notify list are not sent NOTIFY messages for that zone. The default is the empty list (no global notification list).

max-transfer-time-in

Inbound zone transfers running longer than this many minutes are terminated. The default is 120 minutes (2 hours). The maximum value is 28 days (40320 minutes).

max-transfer-idle-in

Inbound zone transfers making no progress in this many minutes are terminated. The default is 60 minutes. The maximum value is 28 days (40320 minutes).

max-transfer-time-out

Outbound zone transfers running longer than this many minutes are terminated. The default is 120 minutes. The maximum value is 28 days (40320 minutes).

max-transfer-idle-out

Outbound zone transfers making no progress in this many minutes are terminated. The default is 60 minutes. The maximum value is 28 days (40320 minutes).

alt-transfer-source

An alternate transfer source if the one listed in transfer-source fails and use-alt-transfer-source is set.

alt-transfer-source-v6

An alternate transfer source if the one listed in transfer-source-v6 fails and use-alt-transfer-source is set.

use-alt-transfer-source

Use the alternate transfer sources or not. If views are specified this defaults to no otherwise it defaults to yes (Ignored in BIND 9).

serial-query-rate

Slave servers periodically query master servers to find out whether zone serial numbers have changed. Each such query uses a minute amount of the slave server's network bandwidth. To limit the amount of bandwidth used, BIND 9 limits the rate at which queries are sent. The value of the serial-query-rate option is the maximum number of queries sent per second. The default is 20.

serial-queries

BIND 9 does not limit the number of outstanding serial queries and ignores the serial-queries option. Instead, it limits the rate at which the queries are sent as defined by the serial-query-rate option.

transfer-format

Specifies whether zone transfers are sent using the one-answer format or the many-answers format. The transfer-format option is used on the master server to determine which format it sends. When set to one-answer, it uses one DNS message per resource record transferred. When set to many-answers, it packs as many resource records as possible into a message. many-answers is more efficient, but it is supported only by relatively new slave servers, such as BIND Version 9. The default is many-answers.

The transfer-format option can be overridden on a per-server basis by using the server statement.

transfers-in

Specifies the maximum number of inbound zone transfers that can be running concurrently. The default value is 10. Increasing the transfers-in value might speed up the convergence of slave zones, but it also might increase the load on the local system.

transfers-out

Specifies the maximum number of outbound zone transfers that can be running concurrently. Zone transfer requests in excess of the limit are refused. The default value is 10.

transfers-per-ns

Specifies the maximum number of inbound zone transfers that can be concurrently transferring from a given remote name server. The default value is 2. Increasing the value of the transfers-per-ns option might speed up the convergence of slave zones, but it also might increase the load on the remote name server. This option can be overridden on a per-server basis by using the transfers phrase of the server statement.

transfer-source

Determines which local address is bound to IPv4 TCP connections used to fetch zones transferred inbound by the server. It also determines the source IPv4 address and, optionally, the UDP port used for the refresh queries and forwarded dynamic updates. If not set, this option defaults to a system-controlled value, which is usually the address of the interface closest to the remote end. This address must appear in the remote end's allow-transfer option for the zone being transferred, if one is specified. This statement sets the transfer source for all zones, but it can be overridden on a per-view or per-zone basis by including a transfer-source statement within the view or zone statement in the configuration file.

transfer-source-v6

Determines which local address is bound to IPv6 TCP connections used to fetch zones transferred inbound by the server. This is the same as the transfer-source option, except zone transfers are performed using IPv6.

notify-source

Determines which local source address and, optionally, UDP port is used to send NOTIFY messages. This address must appear in the slave server's masters clause in the zone statement or in an allow-notify clause.

This statement sets the notify-source for all zones, but it can be overridden on a per-zone or per-view basis by including a notify-source statement within the zone or view statement in the configuration file.

notify-source-v6

Determines which local source address and, optionally, UDP port is used to send NOTIFY messages. This option is identical to notify-source, but it applies to NOTIFY messages sent to IPv6 addresses.

6.4.3.7.8. Bad UDP Port Lists

avoid-v4-udp-ports and avoid-v6-udp-ports specify a list of IPv4 and IPv6 UDP ports that will not be used as system assigned source ports for UDP sockets. These lists prevent the BIND server from choosing as its random source port a port that is blocked by your firewall. If a query went out with such a source port, the answer would not get by the firewall and the name server would have to query again.

6.4.3.7.9. Server Resource Limits
Table 6.13 describes options that limit the server's resource consumption and are enforced internally by the server rather than by the operating system.
Table 6.13. Server Resource Limit Options

Option

Description

max-ixfr-log-size

This option is obsolete; it is accepted and ignored.

max-journal-size

Sets a maximum size for each journal file (see Section 6.4.7.1). When the journal file approaches the specified size, some of the oldest transactions in the journal will be automatically removed. The default is unlimited.

host-statistics-max

Not implemented in BIND 9.

recursive-clients

Specifies the maximum number of simultaneous recursive lookups the server performs on behalf of clients. The default is 1000. Because each recursing client uses about 20 kilobytes of memory, the value of the recursive-clients option might have to be decreased on hosts with limited memory.

tcp-clients

Specifies the maximum number of simultaneous client TCP connections that the server accepts. The default is 100.

max-cache-size

Specifies the maximum amount of memory (in bytes) to use for the server's cache. When the amount of data in the cache reaches this limit, the server causes records to expire prematurely so that the limit is not exceeded. In a server with multiple views, the limit applies separately to the cache of each view. The default is unlimited, which means that records are purged from the cache only when their TTL (time-to-live) values expire.

tcp-listen-queue

The listen queue depth. The default and minimum is 3. Values less than 3 will be silently raised.

6.4.3.7.10. Periodic Task Intervals Options
Table 6.14 describes the options that control the intervals for periodic tasks.
Table 6.14. Periodic Task Intervals Options

Option

Description

cleaning-interval

The server removes expired resource records from the cache every cleaning-interval minutes. The default is 60 minutes. The maximum value is 28 days (40320 minutes). If set to 0, periodic cleaning does not occur.

heartbeat-interval

The server performs zone maintenance tasks for all zones marked as dialup whenever this interval expires. The default is 60 minutes.

Reasonable values are up to 1 day (1440 minutes). The maximum value is 28 days (40320 minutes). If set to 0, no zone maintenance for these zones will occur.

interface-interval

The server scans the network interface list every interface-interval minutes. The default is 60 minutes.

The maximum value is 28 days (40320 minutes). If set to 0, interface scanning will only occur when the configuration file is loaded. After the scan, the server will begin listening for queries on any newly discovered interfaces (provided they are allowed by the listen-on configuration), and will stop listening on interfaces that have gone away.

statistics-interval

Name server statistics are logged every statistics-interval minutes. The default is 60. The maximum value is 28 days (40320 minutes). If set to 0, no statistics will be logged.

This option is not yet implemented.

6.4.3.7.11. The TOPOLOGY Statement
When the server chooses a name server to query from a list of name servers, it prefers the one that is topologically closest to itself. The topology statement takes an address match list and interprets it in a special way. Each top-level list element is assigned a distance. Nonnegated elements get a distance based on their position in the list; the closer the match is to the start of the list, the shorter the distance between it and the server. A negated match is assigned the maximum distance from the server. If there is no match, the address gets a distance that is further than any nonnegated list element and closer than any negated element. For example:
topology {
    10/8;
    !1.2.3/24;
    { 1.2/16; 3/8; };
};
The example configuration prefers servers on network 10 the most, followed by hosts on network 1.2.0.0 (netmask 255.255.0.0) and network 3, with the exception of hosts on network 1.2.3 (netmask 255.255.255.0), which is the least preferred. The default topology is:
    topology { localhost; localnets; };

Note

The topology statement is not implemented in BIND Version 9.

6.4.3.7.12. The SORTLIST Statement

The response to a DNS query can consist of multiple resource records (RRs) forming a resource record set (RRset). The name server normally returns the RRs within the RRset in an indeterminate order. (See Section 6.4.3.7.13.)

The client resolver code should rearrange the RRs as appropriate, that is, by using any addresses on the local network in preference to other addresses. However, not all resolvers can do this or are correctly configured. When a client is using a local server the sorting can be performed in the server, based on the client's address. This requires configuring only the name servers, not all the clients.

The sortlist statement takes an address match list and interprets it even more specifically than the topology statement does (see Section 6.4.3.7.11). Each top-level statement in the sortlist must itself be an explicit address match list with one or two elements. The first element (which can be an IP address, an IP prefix, an ACL name, or a nested address match list) of each top-level list is checked against the source address of the query until a match is found.

Once the source address of the query is matched, if the top-level statement contains only one element, the actual primitive element that matched the source address is used to select the address in the response to move to the beginning of the response. If the statement is a list of two elements, then the second element is treated the same as the address match list in a topology statement. Each top-level element is assigned a distance and the address in the response with the minimum distance is moved to the beginning of the response.

Example 1
In the following example, any queries received from any of the addresses of the host itself gets responses that prefer addresses on any of the locally connected networks. The next-most-preferred are addresses on the 192.168.1/24 network, and after that either the 192.168.2/24 or 192.168.3/24 network with no preference shown between these two networks. Queries received from a host on the 192.168.1/24 network prefers other addresses on that network to the 192.168.2/24 and 192.168.3/24 networks. Queries received from a host on the 192.168.4/24 or the 192.168.5/24 network prefer only other addresses on their directly connected networks.
sortlist {
    { localhost;                         // IF the local host
        { localnets;                     // THEN first fit on the
            192.168.1/24;                // following nets
            { 192.168.2/24; 192.168.3/24; }; }; };
    { 192.168.1/24;                      // IF on class C 192.168.1
        { 192.168.1/24;                  // THEN use .1, or .2 or .3
            { 192.168.2/24; 192.168.3/24; }; }; };
    { 192.168.2/24;                      // IF   on class C 192.168.2
        { 192.168.2/24;                  // THEN use .2, or .1 or .3
            { 192.168.1/24; 192.168.3/24; }; }; };
    { 192.168.3/24;                      // IF on class C 192.168.3
        { 192.168.3/24;                  // THEN use .3, or .1 or .2
            { 192.168.1/24; 192.168.2/24; }; }; };
    { { 192.168.4/24; 192.168.5/24; };   // if .4 or .5, prefer that net
    };
};
Example 2
The following example illustrates reasonable behavior for the local host and for hosts on directly connected networks. Responses sent to queries from the local host favor any of the directly connected networks. Responses sent to queries from any other hosts on a directly connected network prefer addresses on that same network. Responses to other queries are not sorted.
sortlist {
           { localhost; localnets; };
           { localnets; };
};
6.4.3.7.13. RRset Ordering

When multiple records are returned in an answer, it might be useful to configure the order of the records placed into the response. The rrset-order statement permits configuration of the ordering of the records in a multiple-record response.

An order_spec is defined as follows:
[ class class_name ][ type type_name ][ name "domain_name"]
 order ordering

If no class is specified, the default is ANY. If no type is specified, the default is ANY. If no name is specified, the default is wildcard.

The legal values for ordering are:
  • fixed (Records are returned in the order they are defined in the zone file.)

  • random (Records are returned in random order.)

  • cyclic (Records are returned in round-robin order.)

For example:
rrset-order {
   class IN type A name "host.example.com" order random;
   order cyclic;
};

This example causes any responses for type A records in class IN that have host.example.com as a suffix to always be returned in random order. All other records are returned in cyclic order.

If multiple rrset-order statements appear, they are not combined; the last one applies.

Note

The rrset-order statement is not yet fully implemented. BIND currently does not support "fixed" ordering.

6.4.3.7.14. Tuning Options
Table 6.15 describes the options provided for tuning the BIND server.
Table 6.15. Tuning Options

Options

Description

lame-ttl

Sets the number of seconds to cache a lame server indication. A value of zero disables caching. (This is not recommended.) The default is 600 (10 minutes); the maximum value is 1800 (30 minutes).

max-ncache-ttl

To reduce network traffic and increase performance, the server stores negative answers. The max-ncache-ttl option is used to set a maximum retention time for these answers in the server in seconds. The default is 10800 seconds (3 hours). The value of max-ncache-ttl cannot exceed 7 days and is silently truncated to 7 days if set to a greater value.

max-cache-ttl

Sets the maximum time for which the server caches ordinary (positive) answers. The default is one week (7 days).

min-roots

The minimum number of root servers that is required for a request for the root servers to be accepted. The default is 2.

This option is not yet implemented.

sig-validity-interval

Specifies the number of days into the future when DNSSEC signatures automatically generated as a result of dynamic updates will expire. (See Section 6.4.7 for more information.) The default is 30 days. The maximum value is 10 years (3660 days). The signature inception time is unconditionally set to one hour before the current time to allow for a limited amount of clock skew.

edns-udp-size

Sets the advertised EDNS UDP buffer size. Valid values are 512 to 4096 (values outside this range will be silently adjusted). The default value is 4096. The usual reason for setting edns-udp-size to a non default value it to get UDP answers to pass through broken firewalls that block fragmented packets and/or block UDP packets that are greater than 512 bytes.

min-refresh-time

max-refresh-time

min-retry-time

max-retry-time

Controls the server's behavior when refreshing a zone (querying for SOA changes) or when retrying failed transfers. Usually the SOA values for the zone are used, but these values are set by the master, giving slave server administrators little control over their contents.

These options allow the administrator to set a minimum and maximum refresh and retry time either per-zone, per-view, or globally. These options are valid for slave and stub zones, and clamp the SOA refresh and retry times to the specified values.

6.4.3.7.15. Built-in Server Information Zone
The server provides some helpful diagnostic information through a number of built-in zones under the pseudo-top-level-domain bind in the CHAOS class. These zones are part of a built-in view (see Section 6.2.21) of class CHAOS which is separate from the default view of class IN; therefore, any global server options such as allow-query do not apply the these zones. If you feel the need to disable these zones, use the options below, or hide the built-in CHAOS view by defining an explicit view of class CHAOS that matches all clients.
Table 6.16. Built-in Server Information Zones

Options

Description

version

The version the server should report via a query of the name version.bind with type TXT, class CHAOS. The default is the real version number of this server. Specifying version none disables processing of the queries.

hostname

The hostname the server should report via a query of the name hostname.bind with type TXT, class CHAOS. This defaults to the hostname of the machine hosting the name server as found by gethostname(). The primary purpose of such queries is to identify which of a group of anycast servers is actually answering your queries. Specifying hostname none; disables processing of the queries.

server-id

The ID of the server should report via a query of the name ID.SERVER with type TXT, class CHAOS. The primary purpose of such queries is to identify which of a group of anycast servers is actually answering your queries. Specifying server-id none; disables processing of the queries. Specifying server-id hostname; will cause BIND to use the hostname as found by gethostname(). The default server-id is none.

6.4.3.7.16. The Statistics File
The statistics dump begins with the following line:
+++ Statistics Dump +++ (973798949)
The number in parentheses is a standard UNIX time stamp, measured as seconds since January 1, 1970. Following that line are a series of lines containing a counter type, the value of the counter, a zone name (optional), and a view name (optional). The lines without view and zone listed are global statistics for the entire server. Lines with a zone and view name apply to the given view and zone (the view name is omitted for the default view). The statistics dump ends with the following line:
— Statistics Dump — (973798949)

The time stamp is identical to the one in the beginning line.

Table 6.17 describes the statistics counters that are maintained.
Table 6.17. Statistics Counters

Counter

Description

success

The number of successful queries made to the server or zone. A successful query is defined as query which returns a NOERROR response with at least one answer RR.

referral

The number of queries that resulted in referral responses.

nxrrset

The number of queries that resulted in NOERROR responses with no data.

nxdomain

The number of queries that resulted in NXDOMAIN responses.

recursion

The number of queries that caused the server to perform recursion in order to find the final answer.

failure

The number of queries that resulted in a failure response other than those described in the preceding counters.

Each query received by the server will cause exactly one of success, referral, nxrrset, nxdomain, or failure to be incremented, and may additionally cause the recursion counter to be incremented.

6.4.3.8. The SERVER Statement

The server statement defines characteristics to be associated with a remote name server. The server statement has the following syntax:
server ip_addr {
    [ bogus yes_or_no ; ]
    [ provide-ixfr yes_or_no ; ]
    [ request-ixfr yes_or_no ; ]
    [ edns yes_or_no ; ]
    [ transfers number ; ]
    [ transfer-format (one-answer | many-answers ) ; ]]
    [ keys { string ; [ string ; [...]] } ; ]
 
    [ transfer-source (ip4_addr | *) [port ip_port] ; ]
    [ transfer-source-v6 (ip6_addr | *) [port ip_port] ; ]
};

The server statement can occur at the top level of the configuration file or inside a view statement. If a view statement contains one or more server statements, only those apply to the view, and any top-level ones are ignored. If a view contains no server statements, any top-level server statements are used as defaults.

Table 6.18 describes the clauses in the server statement.
Table 6.18. Server Statement Clauses

Clause

Description

bogus

If you discover that a remote server is giving out bad data, marking it as bogus prevents further queries to it. The default value of bogus is NO.

provide-ixfr

Determines whether the local server, acting as master, responds with an incremental zone transfer when the given remote server, a slave, requests it. If this option is set to YES, incremental transfer is provided whenever possible. If set to NO, all transfers to the remote server are nonincremental. If not set, the value of the provide-ixfr option in the global options statement is used as a default.

request-ixfr

Determines whether the local server, acting as a slave, requests incremental zone transfers from the given remote server, a master. If this option is not set, the value of the request-ixfr option in the global options statement is used as a default.

IXFR requests to servers that do not support IXFR automatically falls back to AXFR. Therefore, you do not need to list manually which servers support IXFR and which ones do not; the global default of YES should always work. The purpose of the provide-ixfr and request-ixfr clauses is to make it possible to disable the use of IXFR, even when both master and slave claim to support it; for example, if one of the servers crashes or corrupts data when IXFR is used. See Section 6.4.6 for more information.

edns

Determines whether the local server attempts to use EDNS when communicating with the remote server. The default is YES.

transfer-format
Specifies the zone transfer method:
  • one-answer uses one DNS message per resource record transferred.

  • many-answers packs as many resource records as possible into a message.

The many-answers mode is more efficient, but it is understood only by BIND Version 9, BIND Version 8, and later versions of BIND Version 4. If transfer-format is not specified, the transfer format specified by the options statement is used.

transfers

Limits the number of concurrent inbound zone transfers from the specified server. If no transfers clause is specified, the limit is set according to the transfers-per-ns option, as described in Table 6.12.

keys

Specifies a key_id defined by the key statement, to be used for transaction security when talking to the remote server. The key statement must come before the server statement that references it. When a request is sent to the remote server, a request signature is generated using the key specified here and appended to the message. A request originating from the remote server is not required to be signed by this key.

Use only one key for each server.

transfer-source

Specifies the IPv4 source address to be used for zone transfer with the remote server. For an IPv4 remote server, only transfer-source can be specified.

transfer-source-v6

Specifies the IPv6 source address to be used for zone transfer with the remote server. For an IPv6 remote server, only transfer-source-v6 can be specified.

6.4.3.9. The TRUSTED-KEYS Statement

The trusted-keys statement defines DNSSEC security roots. (DNSSEC is described in Section 6.2.6.)

A security root is defined when the public key for a nonauthoritative zone is known but cannot be securely obtained through DNS, either because it is the DNS root zone or because its parent zone is unsigned. Once a key has been configured as a trusted key, it is treated as if it had been validated and proven secure. The resolver attempts DNSSEC validation on all DNS data in subdomains of a security root.

The trusted-keys statement can contain multiple key entries. The trusted-keys statement has the following syntax:
trusted-keys {
    string number number number string ;
    [ string number number number string ; [...]]
};

Each statement contains the key's domain name, flags, protocol, algorithm, and base-64 representation of the key data.

The base-64 representation of the key data must be enclosed in quotation marks.

6.4.3.10. The VIEW Statement

The view statement allows a name server to answer a DNS query differently, depending on who is asking. It is particularly useful for implementing split DNS setups without having to run multiple servers.

The view statement has the following syntax:
view view_name [class] {
      match-clients { address_match_list } ;
      match-destinations { address_match_list } ;
      match-recursive-only yes_or_no ;
      [ view_option; ...]
      [ zone_statement; ...]
};
The parameters to the view statement are:
  • view-name, which specifies the name of this view.

  • class, which specifies the class for this view. If no class is given, class IN is assumed.

    Note

    All non-IN views must contain a hint zone. Only the IN class has compiled-in default hints.

Table 6.19 describes the clauses you can include in the view statement.
Table 6.19. View Statement Clauses

Clause

Description

match-clients
match-destinations

Each view statement defines a view of the DNS name space that is seen by a subset of clients. A client matches a view if its source IP address matches the address match list of the view's match-clients clause and its destination IP address matches the address match list of the view's match-destinations clause. If they are not specified, both match-clients and match-destinations default to matching all addresses. In addition to checking IP addresses match-clients and match-destinations can also take keys which provide an mechanism for the client to select the view.

match-recursive-only

Only recursive requests from matching clients match that view.

view-options

Many of the options given in the options statement can also be used in a view statement, and then apply only when resolving queries with that view. When no view statement value is given, the value in the options statement is used as the default.

zone-statement

Specifies the zone information for this view. See Section 6.4.3.11 for more information.

The order of the view statements is significant. A client request is resolved in the context of the first view that it matches. Zones defined within a view statement are accessible only to clients that match the view.

By defining a zone of the same name in multiple views, different zone data can be given to different clients; for example, internal and external clients in a split DNS setup. Also, zone statement options can have default values specified in the view statement; these view-specific defaults take precedence over those in the options statement.

If there are no view statements in the configuration file, a default view that matches any client is automatically created in class IN. Any zone statements specified on the top level of the configuration file are considered to be part of this default view, and the options statement will apply to the default view. If any explicit view statements are present, all zone statements must occur inside view statements.

Note

If any explicit view statements are present, all zone statements must occur inside view statements.

The following example shows a typical split DNS setup implemented using view statements:
view "internal" {
               // This should match our internal networks.
      match-clients { 10.0.0.0/8; };
               // Provide recursive service to internal clients only.
      recursion yes;
               // Provide a complete view of the example.com zone
               // including addresses of internal hosts.
      zone "example.com" {
            type master;
            file "example-internal.db";
      };
};
view "external" {
      match-clients { any; };
               // Refuse recursive service to external clients.
      recursion no;
               // Provide a restricted view of the example.com zone
               // containing only publicly accessible hosts.
      zone "example.com" {
            type master;
            file "example-external.db";
      };
};

6.4.3.11. The ZONE Statement

The zone statement specifies options for a specific zone. Note that if view statements are included in the configuration file, the zone statements must be included in view statements.

The zone statement has the following syntax:
zone zone_name [class] [{
 
    type (master | slave | hint | stub | forward | delegation-only) ;
    [ allow-notify { address_match_list } ; ]
    [ allow-query { address_match_list } ; ]
    [ allow-transfer { address_match_list } ; ]
    [ allow-update { address_match_list } ; ]
    [ update-policy { update_policy_rule [...] } ; ]
    [ allow-update-forwarding { address_match_list } ; ]
    [ also-notify { ip_addr [port ip_port] ; [ ip_addr [port ip_port] ;  ... ]
    };
    ]
    [ check-names (warn|fail|ignore) ; ]
    [ dialup dialup_option ; ]
 
    [ delegation-only yes_or_no ; ]
    [ file string ; ]
    [ forward (only|first) ; ]
    [ forwarders { ip_addr [port ip_port] ; [ ip_addr [port ip_port] ;  ... ]
    }; ]
    [ ixfr-base string ; ]
    [ ixfr-tmp-file string ; ]
    [ maintain-ixfr-base yes_or_no ; ]
 
    [ masters [port ip_port] { (masters_list | ip_addr [port ip_port] [key
    key] ) ; [...] } ;
    [ max-transfer-idle-in number ; ]
    [ max-transfer-idle-out number ; ]
    [ max-transfer-time-in number ; ]
    [ max-transfer-time-out number ; ]
    [ notify yes_or_no | explicit ; ]
    [ pubkey number number number string ; ]
    [ transfer-source (ip4_addr | *) [port ip_port] ; ]
    [ transfer-source-v6 (ip6_addr | *) [port ip_port] ; ]
 
    [ alt-transfer-source (ip4_addr | *) [port ip_port] ; ]
    [ alt-transfer-source-v6 (ip6_addr | *) [port ip_port] ; ]
    [ use-alt-transfer-source yes_or_no; ]
    [ notify-source (ip4_addr | *) [port ip_port] ; ]
    [ notify-source-v6 (ip6_addr | *) [port ip_port] ; ]
    [ zone-statistics yes_or_no ; ]
    [ sig-validity-interval number ; ]
    [ database string ; ]
    [ min-refresh-time number ; ]
    [ max-refresh-time number ; ]
    [ min-retry-time number ; ]
    [ max-retry-time number ; ]
 
    [ multi-master yes_or_no ; ]
    [ key-directory path_name; ]
}];
6.4.3.11.1. Type of Zone
Table 6.20 describes the types of zones that you can specify in the type clause.
Table 6.20. Zone Types

Type

Description

master

The server that has a master copy of the data for the zone and that can provide authoritative answers for it.

slave

A replica of a master zone. The masters list specifies one or more IP addresses of master servers that the slave contacts to update its copy of the zone. Masters list elements can also be names of other masters lists. By default, transfers are made from port 53 on the servers; this can be changed for all servers by specifying a port number before the list of IP addresses, or on a per-server basis after the IP address. Authentication to the master can also be done with per-server TSIG keys. If a file is specified, then the replica will be written to this file whenever the zone is changed, and reloaded from this file on a server restart. Use of a file is recommended, since it often speeds server start-up and eliminates a needless waste of bandwidth.

stub

Similar to a slave zone, except that it replicates only the NS records of a master zone instead of the entire zone. Stub zones are not a standard part of the DNS; they are a feature specific to the BIND implementation.

Stub zones can be used to eliminate the need for glue NS record in a parent zone at the expense of maintaining a stub zone entry and a set of name server addresses in TCPIP$BIND.CONF. This usage is not recommended for new configurations, and BIND Version 9 supports it only in a limited way. In BIND Version 8, zone transfers of a parent zone included the NS records from stub children of that zone. This made it possible to configure child stubs only in the master server for the parent zone. BIND Version 9 never mixes together zone data from different zones in this way. Therefore, if a BIND Version 9 master serving a parent zone has child stub zones, all the slave servers for the parent zone also need to have the same child stub zones.

Stub zones can also be used as a way of forcing the resolution of a given domain to use a particular set of authoritative servers. For example, the caching name servers on a private network using RFC1981 addressing may be configured with stub zones for 10.in-addr.arpa to use a set of internal name servers as the authoritative servers for that domain.

forward

A forward zone allows you to configure forwarding on a per-domain basis. A zone statement of type forward can contain forward and forwarders statements, which applies to queries within the domain specified by the zone name. If no forwarders statement is present or if an empty list for forwarders is specified, then forwarding is not done for the domain, thereby canceling the effects of any forwarders in the options statement.

If you want to use this type of zone to change the behavior of the global forward option (using the first value to specify the zone to which to forward first, or the only value to specify forwarding to this zone only), and you want to use the same servers that are set globally, you need to respecify the global forwarders.

hint

The initial set of root name servers is specified using a hint zone. When the server starts up, it uses the root hints to find a root name server and to get the most recent list of root name servers. If no hint zone is specified for class IN, the server uses a default set of root servers hints. Classes other than IN have no built-in defaults hints.

delegation-only

Used to enforce the delegation only status of infrastructure zones (e.g., COM, NET, ORG). Any answer that is received without a explicit or implicit delegation in the authority section will be treated as NXDOMAIN. This does not apply to the zone apex. This SHOULD NOT be applied to leaf zones.

delegation-only has no effect on answers received from forwarders.

6.4.3.11.2. The Zone Class

The zone name can optionally be followed by a class. If the class is not specified, class IN (for Internet) is assumed. This is correct for the vast majority of cases.

The hesiod class is named for an information service from MIT's Project Athena. It is used to share information about various systems databases, such as users, groups, printers, and so on. The keyword HS is a synonym for hesiod.

Another MIT development is CHAOSnet, a LAN protocol created in the mid-1970s. Zone data for CHAOSnet can be specified with the CH class.

6.4.3.11.3. Zone Options
Table 6.21 describes the options you can include in the zone statement.
Table 6.21. Zone Options

Option

Description

allow-notify

See the description of allow-notify in Section 6.4.3.7.4.

allow-query

See the description of allow-query in Section 6.4.3.7.4.

allow-transfer

See the description of allow-transfer in Section 6.4.3.7.4.

allow-update

Specifies which hosts are allowed to submit dynamic DNS updates for master zones. The default is to deny updates from all hosts. Note that allowing updates based on the requestor's IP address is insecure.

update-policy

Specifies an update policy, as described in Section 6.4.7.2.

allow-update-forwarding

See the description of allow-update-forwarding in Table 6.9.

also-notify

Meaningful only if notify is active for this zone. The set of machines that receives a NOTIFY message for this zone is made up of all the listed name servers (other than the primary master) for the zone, plus any IP addresses specified with the also-notify statement. A port can be specified with each also-notify address to send the notify messages to a port other than the default of 53. also-notify is not meaningful for stub zones. The default is the empty list.

check-names

This option is used to restrict the character set and syntax of certain domain names in master files and/or DNS responses received from the network. The default varies according to zone type. For master zones the default is fail. For slave zones the default is warn.

database

Specifies the type of database to be used for storing the zone data. The string following the database keyword is interpreted as a list of space-delimited words. The first word identifies the database type; any subsequent words are passed as arguments to the database to be interpreted in a way specific to the database type.

The default is rbt, the native database used by BIND 9. This database does not take arguments.

dialup

See the description of the dialup option in Section 6.4.3.7.1.

delegation-only

The flag only applies to hint and stub zones. If set to yes then the zone will also be treated as if it is also a delegation-only type zone.

forward

Meaningful only if the zone has a forwarders list. The only keyword causes the lookup to fail after trying the forwarders and getting no answer. The first keyword allows attempts at normal lookups.

forwarders

Overrides the list of global forwarders.

If the zone type is not forward, forwarding is not done for the zone, and the global options are not used.

ixfr-base

BIND 9 ignores this option and constructs the name of the journal file by appending _JNL to the name of the zone file.

ixfr-tmp-file

Ignored in BIND 9.

masters

Specifies one or more IP addresses of master servers that the slave contacts to update its copy of the zone.

By default, transfers are made from port 53 on the servers; this can be changed for all servers by specifying a port number before the list of IP addresses, or on a per-server basis after the IP address. Authentication to the master can also be done with per-server TSIG keys. If a file is specified, then the replica is written to this file whenever the zone is changed and is reloaded from this file on a server restart. Use of a file is recommended because it often speeds server startup and eliminates a waste of bandwidth.

max-transfer-time-in

See the description of max-transfer-time-in in Section 6.4.3.7.7.

max-transfer-idle-in

See the description of max-transfer-idle-in in Section 6.4.3.7.7.

max-transfer-time-out

See the description of max-transfer-time-out in Section 6.4.3.7.7.

max-transfer-idle-out

See the description of max-transfer-idle-out in Section 6.4.3.7.7.

notify

See the description of notify in Section 6.4.3.7.

pubkey

BIND Version 9 does not verify signatures on loading and ignores the option.

zone-statistics

If YES, the server keeps statistical information for this zone, which can be dumped to the statistics file defined in the server options. See Section 6.4.3.7.

sig-validity-interval

See the description of sig-validity-interval in Section 6.4.3.7.14.

transfer-source

See the description of transfer-source in Section 6.4.3.7.7.

transfer-source-v6

See the description of transfer-source-v6 in Section 6.4.3.7.7.

alt-transfer-source

See the description of alt-transfer-source in Table 6.12.

alt-transfer-source-v6

See the description of alt-transfer-source-v6 in Table 6.12.

use-alt-transfer-source

See the description of use-alt-transfer-source in Table 6.12.

notify-source

See the description of notify-source in Section 6.4.3.7.7.

notify-source-v6

See the description of notify-source-v6 in Section 6.4.3.7.7.

min-refresh-time

max-refresh-time

min-retry-time

max-retry-time

See the descriptions of these options in Section 6.4.3.7.14.

ixfr-from-differences

See the description of ixfr-from-differences in Table 6.6.

key-directory

See the description of key-directory in Table 6.6.

multi-master

See the description of multi-master in Table 6.6.

6.4.4. IPv6 Support in BIND Version 9

BIND supports all forms of IPv6 name-to-address and address-to-name lookups. It also uses IPv6 addresses to make queries when running on an IPv6-capable system. For information about configuring the BIND server for IPv6, see the VSI TCP/IP Services for OpenVMS Guide to IPv6.

For forward lookups, BIND 9 supports only AAAA records. The use of A6 records is deprecated by RFC 3363, and the support for forward lookups in BIND 9 is removed accordingly. However, authoritative BIND 9 name servers still load zone files containing A6 records correctly, answer queries for A6 records, and accept zone transfer for a zone containing A6 records.

For IPv6 reverse lookups, BIND 9 supports the traditional "nibble" format used in the ip6.arpa domain, as well as the older, deprecated ip6.int domain. BIND 9 formerly supported the "binary label" (also known as "bitstring") format. The support of binary labels, however, is now completely removed according to the changes in RFC 3363. Any applications in BIND 9 do not understand the format any more, and will return an error if given. In particular, an authoritative BIND 9 name server rejects to load a zone file containing binary labels.

6.4.4.1. Address Lookups Using AAAA Records

The AAAA record is a parallel to the IPv4 A record. It specifies the entire address in a single record. For example:
$ORIGIN example.com.
host            3600    IN      AAAA    3ffe:8050:201:1860:42::1

6.4.4.2. Address-to-Name Lookups Using Nibble Format

As in IPv4, when looking up an address in nibble format, the address components are simply reversed and ip6.arpa. is appended to the resulting name. For example, the following provides reverse name lookup for a host with address 3ffe:8050:201:1860:42::1:
$ORIGIN 0.6.8.1.1.0.2.0.0.5.0.8.e.f.f.3.ip6.arpa.
1.0.0.0.0.0.0.0.0.0.0.0.2.4.0.0   14400 IN      PTR     host.example.com.

6.4.5. DNS Notify

DNS Notify allows master name servers to notify their slave servers of changes to a zone's data. In response to a NOTIFY message from a master server, the slave checks to see whether its version of the zone is the current version. If it is not, the slave initiates a transfer. For more information, see the description of the notify option in Table 6.6.

6.4.6. Incremental Zone Transfers (IXFR)

The incremental zone transfer (IXFR) protocol is a way for slave servers to transfer only changed data instead of having to transfer the entire zone. The IXFR protocol is documented in RFC 1995.

When acting as a master, BIND Version 9 supports IXFR for those zones in which the necessary change history information is available. These include master zones maintained by dynamic update and slave zones whose data was obtained by IXFR. For manually maintained master zones, and for slave zones obtained by performing a full zone transfer (AXFR), IXFR is supported only if the option ixfr-from-differences is set to yes.

When acting as a slave, BIND attempts to use IXFR unless it is explicitly disabled. For more information about disabling IXFR, see the description of the request-ixfr clause of the server statement in Section 6.4.3.8.

6.4.7. Dynamic Updates

With dynamic updates, the BIND server can add, modify, or delete records or RRsets in the master zone files.

Dynamic updating is enabled on a zone-by-zone basis by including an allow-update or update-policy clause in the zone statement. Dynamic updating is described in RFC 2136.

Updating of secure zones (zones using DNSSEC) is presented in RFC 3007. RRSIG and NSEC records affected by updates are automatically regenerated by the server using an online zone key. Update authorization is based on transaction signatures and an explicit server policy.

6.4.7.1. The Journal File

All changes made to a zone using dynamic update are stored in the zone's journal file. This file is automatically created by the server when the first dynamic update takes place. The name of the journal file is formed by appending _JNL to the name of the corresponding zone file. The journal file is in a binary format and should not be edited manually.

The server also occasionally writes (or dumps) the complete contents of the updated zone to its zone file. This is not done immediately after each dynamic update; that would be too slow when a large zone is updated frequently. Instead, the dump is delayed by up to 15 minutes, allowing additional updates to take place.

When a server is restarted after a shutdown or failure, it replays the journal file to incorporate into the zone any updates that took place after the last zone dump. Changes that result from incoming incremental zone transfers are journaled in a similar way.

The zone files of dynamic zones should not be edited because they are not guaranteed to contain the most recent dynamic changes – those are only in the journal file.

If you have to make changes to a dynamic zone manually, use the following procedure:
  1. Disable dynamic updates to the zone using the following command:
    $ rndc freeze zone

    This will also remove the zone's .jnl file and update the master file.

  2. Edit the zone file.

  3. Reload the changed zone and re-enable dynamic updates using the following command:
    $ rndc unfreeze zone

Removing the _JNL file is necessary because the manual edits are not present in the journal, rendering it inconsistent with the contents of the zone file.

6.4.7.2. Dynamic Update Policies

BIND Version 9 supports two methods of granting clients the right to perform dynamic updates to a zone. You can configure them using either the allow-update option or the update-policy option.

The allow-update clause works the same way as in previous versions of BIND. It grants given clients the permission to update any record of any name in the zone.

The update-policy clause is new in BIND 9 and allows more fine-grained control over what updates are allowed. A set of rules is specified, where each rule either grants or denies permissions for one or more names to be updated by one or more identities. The rules apply to master zones only.

The update-policy statement only examines the signer of a message; the source address is not relevant. If the dynamic update request message is signed (that is, it includes either a TSIG or SIG(0) record), the identity of the signer can be determined.

If an allow-update statement appears when the update-policy statement is present, a configuration error occurs.

Use the following format to define rules:
(grant | deny ) identity nametype name [ types ]

Each rule grants or denies privileges. Once a message has successfully matched a rule, the operation is immediately granted or denied and no further rules are examined. A rule is matched when the signer matches the identity field, the name matches the name field in accordance with the nametype field, and the type matches the types specified in the type field.

The rule definition includes the following fields:
  • grant or deny specifies whether to grant or deny privileges.

  • identity specifies the signer of the message. Use a name or a wildcard in the identity field. Normally, this is the name of the TSIG or SIG(0) key used to sign the update request. When a TKEY exchange has been used to create a shared secret, the identity of the shared secret is the same as the identity of the key used to authenticate the TKEY exchange. When the identity field specifies a wildcard name, it is subject to DNS wildcard expansion, so the rule will apply to multiple identities. The identity field must contain a fully qualified domain name.

  • name specifies the name to be updated.

  • nametype specifies one of the following:
    • name, exact-match semantics. This rule matches when the name being updated is identical to the contents of the name field.

    • subdomain, which matches when the name being updated is a subdomain of, or identical to, the contents of the name field.

    • wildcard, the name field is subject to DNS wildcard expansion, and this rule matches when the name being updated name is a valid expansion of the wildcard.

    • self, which matches when the name being updated matches the contents of the identity field. The name field is ignored, but should be the same as the identity field. The self nametype is most useful when allowing using one key per name to update, where the key has the same name as the name to be updated. The identity would be specified as * in this case.

      In all cases, the name field must specify a fully qualified domain name.

    • types specifies the types of resource records.

    If no types are specified, the rule matches all types except RRSIG, NS, SOA, and NSEC. Types can be specified by name, including ANY. ANY matches all types except NXT, which can never be updated.

6.4.7.3. Creating Updates Manually

If the name server for the domain is configured to accept dynamic updates, you can manually create updates to the domain database file using the nsupdate utility.

Note

Zones that are under dynamic control using nsupdate or a DHCP server should not be edited by hand. Manual edits could conflict with dynamic updates and could cause loss of data.

You start the utility using the NSUPDATE command, which is defined when you run the TCPIP$DEFINE_COMMANDS.COM procedure.

You can enter commands to the nsupdate utility interactively, or you can specify a file that contains nsupdate commands.

Transaction signatures can be used to authenticate update requests, as described in Section 6.2.3. Signatures rely on a shared secret that should be known to only the nsupdate utility and the name server. TSIG uses the HMAC-MD5 encryption algorithm. It is important to specify the encryption algorithm because additional algorithms will be made available in the future. Use the appropriate configuration options in the server and key statements in TCPIP$BIND.CONF to ensure the name server associates the secret key and algorithm with the IP address of the client application that uses TSIG authentication. The nsupdate utility does not read the TCPIP$BIND.CONF file.

6.4.8. Configuring Cluster Failover and Redundancy

In the same OpenVMS Cluster, multiple BIND master servers can share a common database, thereby providing redundancy and a failover mechanism when one of the servers becomes unavailable.

To configure a DNS cluster failover and redundancy environment, perform the following steps on each node that acts as a BIND master server.
  1. Run the TCPIP$CONFIG command procedure, and from the Servers menu enable the BIND service.

  2. Edit the BIND configuration file, SYS$SPECIFIC:[TCPIP$BIND]TCPIP$BIND.CONF.
    1. Configure the node as a master server.

    2. Add or edit the options statement. The directory substatement should be as follows:
      options {
               directory "TCPIP$BIND_COMMON:[TCPIP$BIND]";
      };
    TCPIP$BIND_COMMON is a logical name defined in the TCPIP$BIND_COMMON_STARTUP.COM command procedure as a search list. The search list consists of the SYS$SPECIFIC:[TCPIP$BIND] directory and the common directory. In the next step, the setup command procedure prompts you to specify the device on which the common directory is to reside. If you do not specify a device, the default device and directory is common_device:[TCPIP$BIND], where common_device is generated automatically in the following manner:
    • If the SYSUAF logical is defined, the common disk is determined from its definition.

    • If the SYSUAF logical is not defined, the system uses SYS$SYSDEVICE as the default device.

  3. Run the SYS$MANAGER:TCPIP$BIND_CLUSTER_SETUP.COM command procedure.

    This procedure creates two other command procedures that manage the startup and shutdown processes of the BIND component in a cluster environment:
    • SYS$MANAGER:TCPIP$BIND_COMMON_STARTUP.COM

    • SYS$MANAGER:TCPIP$BIND_COMMON_SHUTDOWN.COM

    These files define the BIND system logicals and accounting information. To remove the failover setup from your system, first shut down the BIND server by using the TCPIP$BIND_SHUTDOWN.COM command procedure, then delete these two files.

  4. Place any database files to be shared in the common directory.

    Note

    Remove from SYS$SPECIFIC:[TCPIP$BIND] any databases that are to be shared. Using the search list logical, BIND finds any SYS$SPECIFIC:[TCPIP$BIND] databases first and uses those. This might not be the result you want.

  5. Start up BIND by entering the following command:
    $ @SYS$MANAGER:TCPIP$BIND_STARTUP.COM
  6. Configure the resolver on clients to point to the DNS master servers. You can accomplish this by listing each one. For example, issue the following command:
    TCPIP> SET NAME /SYSTEM /SERVER=(master1, master2)

    For master1 and master2, you can specify a node name or an IP address. For further redundancy, master1 and master2 may be a failSAFE IP address.


Caution

The use of dynamic updates in conjunction with a master BIND server that is participating in cluster failover and redundancy is not supported and might cause serious problems.

6.4.8.1. Changing the BIND Database

If multiple master BIND servers are running in a cluster, and a change is made to the common BIND database, the database must be reloaded on each node that is running the master BIND server. To reload the BIND database on every node in the cluster where the master BIND server is running, enter the following command:
TCPIP> SET NAME_SERVICE /INITIALIZE /CLUSTER=dev:[directory]
The /CLUSTER qualifier takes the directory specification of the common BIND directory as a value. If you omit the device and directory, they default to:
common_device:[TCPIP$BIND_COMMON]
In this case, common_device is generated automatically in the following manner:
  • If the SYSUAF logical is defined, the common disk is determined from its definition.

  • If SYSUAF logical is not defined, the system uses SYS$SYSDEVICE as the default device.

6.5. Populating the BIND Server Databases

To populate the BIND server database files, use one of the following methods:
  • Convert an existing host database with the CONVERT/UNIX BIND command.

  • Manually edit the ZONE.DB files.

6.5.1. Using Existing Databases

To populate the BIND server database by copying information from the local hosts database and other database files, enter the CONVERT/UNIX BIND command. This command:
  • Creates a BIND server database (if needed).

  • Extracts data from the local hosts database. (The BIND server uses UNIX style formatted files.)

  • Extracts Mail Exchange (MX) information from the routes database.

  • Populates the BIND server database with the host and MX records.

  • Creates a forward translation file with the following characteristics:
    • It has address, canonical name, and MX entries.

    • If a file with the same name as the output file already exists, the serial number from that file's start-of-authority (SOA) entry increments and becomes the serial number of the new output file.

    • If no previous version of the output file exists, the serial number for the new file is 1.

    When you specify forward translation (by omitting the /DOMAIN qualifier), any host in the local hosts database that is not qualified with a domain is included in the target domain. For example, if the local domain is x.y.z., the CONVERT/UNIX BIND command includes: a, b.x.y.z, c.x.y.z.z but does not include d.x.y.h.

  • Creates a reverse translation file if you specify /DOMAIN=(domain.name) and the end of domain.name is IN-ADDR.ARPA.

    The created reverse translation file has the following characteristics:
    • Only records applicable to the domain you specify are placed into the output file.

    • The output file has domain name pointer entries.

    • If a file with the same name as the output file already exists, the serial number from that file's SOA entry increments and becomes the serial number of the new output file.

    • If no previous version of the output file exists, the serial number for the new file is 1.

    • The file selects hosts with IP addresses that match the partial IP address from domain.name. For example, /DOMAIN=16.99.IN-ADDR.ARPA does a reverse translation and selects hosts whose addresses begin with 99.16.

If the BIND server's directory is SYS$SPECIFIC:[TCPIP$BIND] and you have specified domain abc.def.com, the default output file is named SYS$SPECIFIC:[TCPIP$BIND]ABC_DEF_COM.DB.

VSI suggests that you do not change the default directory name. If you do, the file is created in your current directory.

On the command line, specify the full OpenVMS file specification. Do not specify a version number, and do not use wildcards. The following example uses the domain ucx.ern.sea.com, creates a UCX_ERN_SEA_COM.DB file, creates a 208_20_9_IN-ADDR_ARPA.DB file, and checks the results by displaying directory listings with the new file.
TCPIP> CONVERT/UNIX BIND /DOMAIN=UCX.ERN.SEA.COM
TCPIP> CONVERT/UNIX BIND /DOMAIN=208.20.9.IN-ADDR.ARPA


TCPIP> SET DEFAULT SYS$SPECIFIC:[TCPIP$BIND]
$ DIRECTORY

Directory SYS$SPECIFIC:[TCPIP$BIND]

127_0_0.DB;1        208_20_9_IN-ADDR_ARPA.DB;1
LOCALHOST.DB;1
LOGIN.COM;1         ROOT.HINT;1         TCPIP$BIND.CONF;1
TCPIP$BIND_CONF.TEMPLATE;1              TCPIP$BIND_RUN.LOG;4339
TCPIP$BIND_SERVER.PID;1                 UCX_ERN_SEA_COM.DB;5

6.5.2. Manually Editing Zone Files

All name server zone files use the same type of records to define domain database information. VSI recommends that you review these resource records before you edit any BIND files. Table 6.22 describes the standard resource records (RRs).
Table 6.22. Standard Resource Record Types

Record Type

Description

A

A host address.

A6

An IPv6 address.

AAAA

An IPv6 address.

CERT

A digital certificate.

CNAME

The canonical name of an alias.

DNAME

Delegation of reverse addresses. Replaces the domain name specified with another name to be looked up. (Described in RFC 2672.)

GPOS

The global position. Superseded by LOC.

HINFO

The host's CPU and operating system.

KEY

A public key associated with a DNS name.

KX

A key exchanger for this DNS name.

MX

A mail exchange for the domain.

NAPTR

A name authority pointer.

NSAP

A network service access point.

NS

An authoritative name server for the domain. Limit of 32 per domain.

NXT

Used in DNSSEC to securely indicate that RRs with an owner name in a certain name interval do not exist in a zone and to indicate what RR types are present for an existing name. For more information, see RFC 2535.

PTR

A pointer to another part of the domain name space.

SIG

A signature. Contains data authenticated in the secure DNS. For more information, see RFC 2535.

SOA

The start of an authority zone.

SRV

Information about well-known network services. Replaces WKS.

TXT

Text records.

WKS

Information about the well-known network services, such as SMTP, that a domain supports. Replaced by WKS.

X25

Representation of X.25 network addresses. Experimental.

The format of DNS records is as follows:
[name] [ttl] IN type data
In this format:

name

Specifies the name of the domain object referenced by a resource record. The string entered for name is the current domain unless it ends with a dot. If the name field is blank, the record applies to the domain object last named.

ttl

Defines the length of time, in seconds, that the information in this resource record should be kept in cache. Usually, the time-to-live field is left blank, and the default ttl, set for the entire zone SOA record, is used.

IN

Identifies the record as an Internet DNS resource record.

type

Identifies what kind of resource record this is. (See Table 6.22 for the record types you can specify.)

data

Information specific to this type of resource record. For example, in an A record, this is the field that contains the actual IP address.

6.5.2.1. Setting TTLs

The time to live (TTL) of the RR field is a 32-bit integer that represents the number of seconds that an RR can be cached before it should be discarded. The following types of TTL values are used in a zone file:
  • SOA

    The last field in the SOA is the negative caching TTL. This controls how long other servers cache no-such-domain (NXDOMAIN) responses from you.

    The maximum time for negative caching is 3 hours (3h).

  • $TTL

    The $TTL directive at the top of the zone file (before the SOA) gives a default TTL for every RR without a specific TTL set.

  • RR TTLs

    Each RR can have a TTL as the second field in the RR, which controls how long other servers can cache it.

All of these TTLs default to units of seconds, though units can be explicitly specified (for example, 1h30m for 1 hour and 30 minutes).

6.5.2.2. Zone File Directives

While the master file format itself is class independent, all records in a master file must be of the same class. The master file directives are described in the following list:
  • $ORIGIN domain-name [comment ]

    Sets the domain name that is appended to any unqualified records. When a zone is first read, an implicit $ORIGIN zone-name directive is applied.

    If domain specified is not absolute, the current $ORIGIN is appended to it.

    For example, the following are interpreted the same way:
    $ORIGIN example.com WWW     CNAME   MAIN-SERVER
    And:
    WWW.EXAMPLE.COM. CNAME MAIN-SERVER.EXAMPLE.COM.
  • $INCLUDE filename [ origin ] [ comment ]

    Reads and processes the specified file as if it were included into the file at this point. If origin is specified, the file is processed with $ORIGIN set to that value; otherwise, the current $ORIGIN is used.

    Once the file has been read, the origin and the current domain name revert to the values they had prior to the $INCLUDE.

  • $TTL default-ttl [comment]

    Sets the default time to live (TTL) for subsequent records with undefined TTLs. Valid TTLs are in the range of 0 – 2147483647 seconds.

6.5.3. Saving Backup Copies of Zone Data

A slave name server saves backup copies of the zone data in SYS$SPECIFIC:[TCPIP$BIND]. Do not delete these backup copies. When the master server is down and the slave server is running, the slave server cannot perform a zone transfer until the master server comes back up. However, with backup copies, the slave server has some data (though possibly out of date) to perform its basic tasks.

6.5.4. Sample Database Files

The following sections provide sample BIND database files.

6.5.4.1. Local Loopback

In the LOCALHOST.DB file, the local host address is usually 127.0.0.1. The following sample LOCALHOST.DB file shows the forward translation for the local loopback interface:
;
; File name:      LOCALHOST.DB
; Product:        VSI TCP/IP Services for OpenVMS
; Version:        X6.0-N22NOV16
;
; © Copyright 2014, 2022 VMS Software, Inc. and Hewlett Packard Enterprise Development, LP
;
;
; BIND data file for local loopback interface (forward translation)
;
$ORIGIN localhost.
@                       1D IN SOA       @ root (
                                        42              ; Serial
                                        3H              ; Refresh
                                        15M             ; Retry
                                        1W              ; Expiry
                                        1D )            ; Minimum
;
                        1D IN NS        @
                        1D IN A         127.0.0.1
The following sample 127_0_0.DB file shows the reverse translation for the local loopback interface:
;
; File name:      127_0_0.DB
; Product:        VSI TCP/IP Services for OpenVMS
; Version:        X6.0-N22NOV16
;
; © Copyright 2014, 2022 VMS Software, Inc. and Hewlett Packard Enterprise Development, LP
;
;
; BIND data file for local loopback interface (reverse translation)
;
$ORIGIN 0.0.127.in-addr.arpa.
@                       1D IN SOA       localhost. root.localhost. (
                                        42              ; Serial
                                        3H              ; Refresh
                                        15M             ; Retry
                                        1W              ; Expiry
                                        1D )            ; Minimum
;
                        1D IN NS        localhost.
1                       1D IN PTR       localhost.


These local host databases provide forward and reverse translation for the widely used LOCALHOST name. The LOCALHOST name is always associated with the IP address 127.0.0.1 and is used for local loopback traffic.

6.5.4.2. Hint File

This file contains root name server hints. Any name server running on a host without direct Internet connectivity should list the internal roots in its hint file.

The following sample shows a ROOT.HINT file. In earlier releases, this file was called NAMED.CA:
; File name:      ROOT.HINT
;
;
; DESCRIPTION:
;
;    Data file for initial cache data for root domain servers.
;
;       This file holds the information on root name servers needed to 
;       initialize cache of Internet domain name servers
;       (e.g. reference this file in the "cache  .  <file>"
;       configuration file of BIND domain name servers). 
; 
;       This file is made available by InterNIC 
;       under anonymous FTP as
;           file                /domain/named.cache 
;           on server           FTP.INTERNIC.NET
;       -OR-                    RS.INTERNIC.NET
; 
;       last update:     June 24, 2021 
;       related version of root zone:     2021062401
; 
; FORMERLY NS.INTERNIC.NET 
;
.                        3600000      NS    A.ROOT-SERVERS.NET.
A.ROOT-SERVERS.NET.      3600000      A     198.41.0.4
A.ROOT-SERVERS.NET.      3600000      AAAA  2001:503:ba3e::2:30
; 
; FORMERLY NS1.ISI.EDU 
;
.                        3600000      NS    B.ROOT-SERVERS.NET.
B.ROOT-SERVERS.NET.      3600000      A     199.9.14.201
B.ROOT-SERVERS.NET.      3600000      AAAA  2001:500:200::b
; 
; FORMERLY C.PSI.NET 
;
.                        3600000      NS    C.ROOT-SERVERS.NET.
C.ROOT-SERVERS.NET.      3600000      A     192.33.4.12
C.ROOT-SERVERS.NET.      3600000      AAAA  2001:500:2::c
; 
; FORMERLY TERP.UMD.EDU 
;
.                        3600000      NS    D.ROOT-SERVERS.NET.
D.ROOT-SERVERS.NET.      3600000      A     199.7.91.13
D.ROOT-SERVERS.NET.      3600000      AAAA  2001:500:2d::d
; 
; FORMERLY NS.NASA.GOV
;
.                        3600000      NS    E.ROOT-SERVERS.NET.
E.ROOT-SERVERS.NET.      3600000      A     192.203.230.10
E.ROOT-SERVERS.NET.      3600000      AAAA  2001:500:a8::e
; 
; FORMERLY NS.ISC.ORG
;
.                        3600000      NS    F.ROOT-SERVERS.NET.
F.ROOT-SERVERS.NET.      3600000      A     192.5.5.241
F.ROOT-SERVERS.NET.      3600000      AAAA  2001:500:2f::f
; 
; FORMERLY NS.NIC.DDN.MIL
;
.                        3600000      NS    G.ROOT-SERVERS.NET.
G.ROOT-SERVERS.NET.      3600000      A     192.112.36.4
G.ROOT-SERVERS.NET.      3600000      AAAA  2001:500:12::d0d
; 
; FORMERLY AOS.ARL.ARMY.MIL
;
.                        3600000      NS    H.ROOT-SERVERS.NET.
H.ROOT-SERVERS.NET.      3600000      A     198.97.190.53
H.ROOT-SERVERS.NET.      3600000      AAAA  2001:500:1::53
; 
; FORMERLY NIC.NORDU.NET
;
.                        3600000      NS    I.ROOT-SERVERS.NET.
I.ROOT-SERVERS.NET.      3600000      A     192.36.148.17
I.ROOT-SERVERS.NET.      3600000      AAAA  2001:7fe::53
; 
; OPERATED BY VERISIGN, INC.
;
.                        3600000      NS    J.ROOT-SERVERS.NET.
J.ROOT-SERVERS.NET.      3600000      A     192.58.128.30
J.ROOT-SERVERS.NET.      3600000      AAAA  2001:503:c27::2:30
; 
; OPERATED BY RIPE NCC
;
.                        3600000      NS    K.ROOT-SERVERS.NET.
K.ROOT-SERVERS.NET.      3600000      A     193.0.14.129
K.ROOT-SERVERS.NET.      3600000      AAAA  2001:7fd::1
; 
; OPERATED BY ICANN
;
.                        3600000      NS    L.ROOT-SERVERS.NET.
L.ROOT-SERVERS.NET.      3600000      A     199.7.83.42
L.ROOT-SERVERS.NET.      3600000      AAAA  2001:500:9f::42
; 
; OPERATED BY WIDE
;
.                        3600000      NS    M.ROOT-SERVERS.NET.
M.ROOT-SERVERS.NET.      3600000      A     202.12.27.33
M.ROOT-SERVERS.NET.      3600000      AAAA  2001:dc3::35
; End of file

This cache initialization file contains NS records that name root servers and A records that provide the addresses of root servers.

To create a ROOT.HINT file:
  1. Run TCPIP$CONFIG.

  2. Select the Server Components menu.

  3. Select the BIND server.

  4. Enable the BIND server.

This procedure creates the ROOT.HINT file and places the file in the SYS$SPECIFIC:[TCPIP$BIND] directory.

6.5.4.3. Forward Translation File

The forward translation file, domain_name.DB, stores host-name-to-address mapping. For example, the database file UCX_ERN_SEA_COM.DB is created for the domain UCX.ERN.SEA.COM.

The following example shows a domain_name.DB file:
$TTL 86400
$ORIGIN ucx.ern.sea.com.
@               IN      SOA     owl.ucx.ern.sea.com. pmaster.owl.ern.sea.com.
(
                                23      ; Serial
                                600     ; Refresh
                                300     ; Retry
                                172800  ; Expire
                                43200 ) ; Minimum
;
                IN      NS      owl.ucx.ern.sea.com.
                IN      NS      condor.ucx.ern.sea.com.
;
thrush          IN      A       9.20.208.53
condor          IN      A       9.20.208 or 90
birdy           IN      A       9.20.208.47
                IN      MX      10 birdy.ucx.ern.sea.com.
                IN      MX      100 inet-gw-1.pa.emu.com.
                IN      MX      100 mts-gw.pa.emu.com.
                IN      MX      200 crl.emu.com.
                IN      MX      300 nester.emu.com.
seagull         IN      A       9.20.208.30
                IN      MX      10 seagull.ucx.ern.sea.com.
                IN      MX      100 inet-gw-1.pa.emu.com.
                IN      MX      100 mts-gw.pa.emu.com.
                IN      MX      200 crl.emu.com.
                IN      MX      300 nester.emu.com.
owl             IN      A       9.20.208.72
                IN      MX      10 owl.ucx.ern.sea.com.
                IN      MX      100 inet-gw-1.pa.emu.com.
                IN      MX      100 mts-gw.pa.emu.com.
                IN      MX      200 crl.emu.com.
                IN      MX      300 nester.emu.com.
peacock         IN      A       9.20.208.73
                IN      MX      10 pultdown.ucx.ern.sea.com.
                IN      MX      100 inet-gw-1.pa.emu.com.
                IN      MX      100 mts-gw.pa.emu.com.
                IN      MX      200 crl.emu.com.
                IN      MX      300 nester.emu.com.
redwing         IN      A       9.20.208.79
                IN      MX      10 redwing.ucx.ern.sea.com.
                IN      MX      100 inet-gw-1.pa.emu.com.
                IN      MX      100 mts-gw.pa.emu.com.
                IN      MX      200 crl.emu.com.
                IN      MX      300 nester.emu.com.
robin           IN      A       9.20.208.47
                IN      A       9.20.208.30
                IN      A       9.20.208.72

This file is created only for the master server. All other servers obtain this information from the master server. This file contains most of the domain information and has the following characteristics:
  • Begins with an SOA record and a few NS records that define the domain and its servers.

  • Maps host names to IP addresses.

  • Contains A, MX, CNAME, and other records.

MX records identify the servers in a domain that are used for forwarding mail. Use MX records and preference numbers to define the order in which mail servers are used. The lower the preference number, the more desirable the server.

6.5.4.4. Reverse Translation File

The reverse translation file, address.DB, stores address-to-host-name mapping (reverse mapping) information. For example, the database file 208_20_9_IN-ADDR_ARPA.DB is created for the domain 208.20.9.IN-ADDR.ARPA.

The following example shows an address.DB file:
$TTL 86400
$ORIGIN 208.20.9.in-addr.arpa.
@     IN   SOA   owl.ucx.ern.sea.com. pmaster.owl.ucx.ern.sea.com.
(
                          1       ; Serial
                          600     ; Refresh
                          300     ; Retry
                          172800  ; Expire
                          43200 ) ; Minimum
;
      IN      NS      owl.ucx.ern.sea.com.
      IN      NS      condor.ucx.ern.sea.com.
;
53              IN      PTR     thrush.ucx.ern.sea.com.
10              IN      PTR     condor.ucx.ern.sea.com.
47              IN      PTR     birdy.ucx.ern.sea.com.
30              IN      PTR     seagull.ucx.ern.sea.com.
72              IN      PTR     owl.ucx.ern.sea.com.
73              IN      PTR     peacock.ucx.ern.sea.com.
79              IN      PTR     redwing.ucx.ern.sea.com.

PTR records predominate in this file because they are used to translate addresses to host names.

6.6. Examining Name Server Statistics

The BIND server collects statistics that record server activity. To examine BIND statistics, use one of the following commands:
  • The TCP/IP management command SHOW NAME_SERVICE /STATISTICS

  • The rndc stats command

Statistics are logged to the TCPIP$BIND.STATS file, located in SYS$SPECIFIC:[TCPIP$BIND].

The following sample shows a statistics log:
+++ Statistics Dump +++ (1004986341)
success 17
referral 0
nxrrset 1
nxdomain 1
recursion 6
failure 0
— Statistics Dump — (1004986341)

The statistics dump begins with the line +++ Statistics Dump +++ (973798949). The number in parentheses is a standard UNIX timestamp, measured as seconds since January 1, 1970. Following that line are a series of lines containing a counter type, the value of the counter, a zone name (optional), and a view name (optional).

The lines without view and zone listed are global statistics for the entire server. Lines with a zone and view name are for the given view and zone. (The view name is omitted for the default view.)

The statistics dump ends with the line — Statistics Dump — (973798949) The number in parentheses is identical to the number in the beginning line.

The following statistics counters are maintained:
  • success

    The number of successful queries made to the server or zone. A successful query is defined as query that returns a NOERROR response other than a referral response.

  • referral

    The number of queries that resulted in referral responses.

  • nxrrset

    The number of queries that resulted in NOERROR responses with no data.

  • nxdomain

    The number of queries that resulted in NXDOMAIN responses.

  • recursion

    The number of queries that caused the server to perform recursion in order to find the final answer.

  • failure

    The number of queries that resulted in a failure response other than those described in the previous counters.

6.7. Configuring BIND with the SET CONFIGURATION Command

The following sections describe how to set up BIND servers manually using the TCP/IP management command SET CONFIGURATION BIND.

Note

This command creates a UCX Version 4. x configuration. If you set up your BIND name server using this command, you must also use the TCP/IP management command CONVERT/CONFIGURATION BIND command to convert the databases to the BIND Version 9 format. If you omit this step, your changes will not take effect.

6.7.1. Setting Up a Master Name Server

To instruct the master name server to read the appropriate database files using the information in TCPIP$CONFIGURATION.DAT, use the SET CONFIGURATION BIND command. Use the SHOW CONFIGURATION BIND command to display BIND information from the configuration database (TCPIP$CONFIGURATION.DAT).

The following commands tell the name server to read the appropriate files:
TCPIP> SET CONFIGURATION BIND /CACHE

TCPIP> SET CONFIGURATION BIND -
_TCPIP> /PRIMARY=(DOMAIN:0.0.127.IN-ADDR.ARPA, FILE:NAMED.LOCAL)

TCPIP> SET CONFIGURATION BIND -
_TCPIP> /PRIMARY=(DOMAIN:UCX.ERN.SEA.COM, FILE:UCX_ERN_SEA_COM.DB)

TCPIP> SET CONFIGURATION BIND -
_TCPIP> /PRIMARY=(DOMAIN:208.20.9.IN-ADDR.ARPA, FILE:208_20_9_IN-ADDR_ARPA.DB)

To view these settings, use the SHOW CONFIGURATION BIND command.

6.7.2. Setting Up a Secondary (Slave) Name Server

You can configure a secondary server to populate itself by copying the DNS database files from the master server.

To configure a secondary server, enter the following commands:
TCPIP> SET CONFIGURATION BIND /CACHE

TCPIP> SET CONFIGURATION BIND -
_TCPIP> /PRIMARY=(DOMAIN:0.0.127.IN-ADDR.ARPA, FILE:NAMED.LOCAL)


TCPIP> SET CONFIGURATION BIND -
_TCPIP> /SECONDARY=(DOMAIN:UCX.ERN.SEA.COM, -
_TCPIP> FILE:UCX_ERN_SEA_COM.DB,HOST:OWL)


TCPIP> SET CONFIGURATION BIND -
_TCPIP> /SECONDARY=(DOMAIN:208.20.9.IN-ADDR.ARPA, -
_TCPIP> FILE:208_20_9_IN-ADDR_ARPA.DB, -
_TCPIP> HOST:OWL.UCX.ERN.SEA.COM)

6.7.3. Setting Up a Cache-Only Server

To configure a cache-only server, enter the following command:
TCPIP> SET CONFIGURATION BIND /CACHE

This command points the server to the file NAMED.CA.

6.7.4. Setting Up a Forwarder Name Server

To configure a forwarder server, enter the following command:
TCPIP> SET CONFIGURATION BIND /FORWARDERS=(HOST:host)
In this command, host specifies the forwarding server.

Note

You cannot set up a server to be both a forwarder and a caching server.

6.8. Configuring the BIND Resolver

Your host uses the BIND resolver to obtain information from a name server. When a request for name translation arrives, the resolver first searches the local host database for the host information. If the information is not found, the resolver then queries the BIND name server for host information.

Note

The BIND resolver is based on the BIND Version 9 implementation of DNS.

The resolver is automatically configured by TCPIP$CONFIG when you choose Option 1 — Core Environment. To display your resolver configuration, enter the following TCP/IP management command:
TCPIP> SHOW NAME_SERVICE
TCP/IP Services displays the following data:
BIND Resolver Parameters

 Local domain: ucx.ern.sea.com

 System

  State:     Started, Enabled

  Transport: UDP
  Domain:    ucx.ern.sea.com
  Retry:     2
  Timeout:   5
  Servers:   lark
  Path:      ucx.ern.sea.com,ern.sea.com,sea.com

 Process

  State:     Enabled

  Transport:
  Domain:
  Retry:
  Timeout:
  Servers:
  Path:
Here, host LARK in the current domain is the default name server. To add records to the local hosts database, use the SET HOST command. For example, the following command adds host birdy to the local hosts database. (For more information about using SET commands, see the VSI TCP/IP Services for OpenVMS Management Command Reference manual.)
TCPIP> SET HOST birdy /ADDRESS=9.20.208.47
To delete server entries from the configuration database or to add new entries, enter the following command:
TCPIP> SET NAME_SERVICE /NOSERVER=LARK /SYSTEM

This command modifies the volatile database. To make a change to the permanent database, enter the SET CONFIGURATION NAME_SERVICE command.

To view the results, enter the SHOW CONFIGURATION NAME_SERVICE command.

6.8.1. Changing the Default Configuration Using the TCP/IP Management Command Interface

Note

You can also change the default configuration in the RESOLV.CONF configuration file (described in Section 6.8.3. If you use the configuration file, any BIND resolver configuration changes you make through the TCP/IP management command interface will be ignored.

To add a new server and enable the BIND resolver, enter the following command:
TCPIP> SET NAME_SERVICE /SERVER=host /ENABLE /SYSTEM

For host, specify the host name or IPv4 address of the BIND server or servers that the BIND resolver is to query.

To specify multiple hosts, list them by request preference. A maximum of three BIND servers will be listed. The BIND resolver sends the first lookup request to the first host on the list.

If you define a server list and then add a new server with the SET NAME_SERVICE /SERVER command, the new server is added to the end of the list.

SET commands affect the volatile database. To save your changes to the permanent database, use the SET CONFIGURATION commands. The changes you make with the SET CONFIGURATION commands take effect the next time the software starts up. For example:
TCPIP> SET CONFIGURATION NAME_SERVICE /SERVER=host /ENABLE

TCPIP> SHOW CONFIGURATION NAME_SERVICE

BIND Resolver Configuration

  Transport:  UDP
  Domain:     ucx.ern.sea.com
  Retry:         2
  Timeout:       5
  Servers:    9.20.208.47, 9.20.208.53
  Path:       No values defined

6.8.2. Examples

The following command defines hosts PARROT, SORA, and JACANA as systemwide BIND servers and enables the BIND resolver:
PARROT> TCPIP
TCPIP> SET NAME_SERVICE /SERVER=(PARROT,SORA,JACANA) /SYSTEM /ENABLE
The following example defines, for the current login session, host OSPREY as the BIND server. As a result, the servers that are defined systemwide are not queried.
TCPIP> SET NAME_SERVICE /SERVER=OSPREY

6.8.3. Configuring the Resolver Using RESOLV.CONF

You can configure the BIND resolver using the ASCII configuration file TCPIP$ETC:RESOLV.CONF.

When you configure the resolver using TCPIP$CONFIG.COM (as described in the VSI TCP/IP Services for OpenVMS Installation and Configuration, the template file TCPIP$ETC:RESOLV_CONF.TEMPLATE is created. To configure the BIND resolver, rename this file to TCPIP$ETC:RESOLV.CONF.

The RESOLV.CONF file supersedes any configuration settings you implement with the TCP/IP management command interface (described in Section 6.8.1. The two configuration methods cannot be used in combination with one another.

The following is a sample RESOLV.CONF file:
#
# File name:      RESOLV.CONF
# Product:        VSI TCP/IP Services for OpenVMS
# Version:        X6.0-N22NOV16
#
# © Copyright 2014, 2022 VMS Software, Inc. and Hewlett Packard Enterprise Development, LP
#

#
# DESCRIPTION:
#
#    The RESOLV.CONF file lists name-value pairs that provide information
#    to the BIND resolver.
#
# SYNTAX:
#
#    Caution: White space entered after the domain name is  not  ignored;
#         it is interpreted as part of the domain name.
#
#    domain <domainname>      local domain name
#    nameserver <address>     Internet address of a name server that the
#                 resolver should query
#    search <domainname> ...  search list for host-name lookup
#
#    options <option> ...     list of options separated by a space; must
#                 be all lower case; available options  are:
#
#        debug        turn on resolver diagnostics
#
#        ndots:<N>          the minimum number of dots a  domain  name 
#                 must contain before  an  initial  absolute 
#                 query will be made.  default: 1
#
#        timeout:<N>      amount of time the resolver will wait  for 
#                 a response before retrying the query via a   
#                 different nameserver.  default: 5 seconds
#
#        attempts:<N>     number of times the resolver will  send  a 
#                 query to each nameserver before giving up. 
#                 default: 2
#
#        no-tld-query     do not attempt  to  resolve  a  top  level 
#                 domain name
#                 
#        no-check-names   disables sanity checks for valid characters 
#                 in hostnames
#
#        edns0        attach OPT pseudo-RR  for  EDNS0  extension 
#                 to inform DNS server of our receive  buffer  
#                 size   
#
#        dname        evaluate DNAME records when  querying  IPv6 
#                 addresses
#
#        nibble:<suffix>  determine  the  base  domain  for  reverse- 
#                 resolving IPv6  addresses  in  nibble  mode 
#                 default: ip6.arpa
#
#        nibble2:<suffix> determine  the  base  domain  for  reverse-
#                 resolving IPv6  addresses  in  nibble  mode 
#                 default: ip6.int
#
#        v6revmode:<mode> determine   the   strategy   for   reverse-
#                 resolving IPv6 addresses. <mode> can be one 
#                 of:
#             single  query using a base domain of ip6.arpa
#             both    query using ip6.arpa and ip6.int 
#
#
#    There are two logical names that can override values in this file: 
#
#    LOCALDOMAIN <domainname>          local domain name
#    TCPIP$BIND_RES_OPTIONS <"options ...">  set resolver options
#
#domain a.b.c.d
#nameserver 1.2.3.4
#nameserver 5.6.7.8
#options debug

6.8.3.1. Specifying Nameservers With IPv6 Addresses

You can use RESOLV.CONF to specify nameservers with IPv6 addresses. The BIND resolver then uses the IPv6 transport to contact the nameserver and for subsequent communications.

A maximum of three nameservers may be specified in the RESOLV.CONF file. If you specify nameservers with IPv6 addresses, the TCP/IP management command SHOW HOST will use the IPv6 transport to contact the nameserver, but will not display the IPv6 address of the server queried. Instead it will display:
server: IPv6

To obtain more detailed information, including the name and IP address of the nameserver used for resolution, use the dig utility, described in Section 6.11.1.

6.8.3.2. Resolver Default Retry and Timeout

The BIND resolver searches the local hosts database (TCPIP$HOST.DAT), and then TCPIP$ETC:IPNODES.DAT. If the information is not found, the resolver queries the BIND nameserver for host information.

The timeout is the length of time that the resolver will wait for a response from a nameserver before sending another query. If the resolver encounters an error that indicates the nameserver is actually down or unreachable, or if it times out, it doubles the timeout and queries the nameserver again. This process is repeated up to three more times, until the default of four retry attempts is reached. The default is two retries and a timeout of five seconds. Therefore, only one set of retries (a total of two queries) will be made to each nameserver. This reduces the amount of time a user must wait for the resolver to return if none of the nameservers are responding.

When multiple nameservers are configured, and the resolver has queried all of them with no response, it updates the timeout and cycles through them again. The timeout for this next round of queries is based on the number of configured nameservers. The timeout is ten seconds divided by the total number of configured nameservers, rounded down. After one set of retransmissions (a total of two timeouts for each configured nameserver), the resolver gives up trying to query name servers. The default timeout behavior is expressed in the following table:

Name Servers Configured

Retry

1

2

3

0

5 sec

(2x)5 sec

(3x)5 sec

1

10 sec

(2x)5 sec

(3x)3 sec

Total

15 sec

20 sec

24 sec

Therefore, if you configure three nameservers, the resolver queries the first server with a timeout period of five seconds. If that query times out, the resolver queries the second server with the same timeout, and similarly for the third. If the resolver cycles through all three servers, it doubles the timeout period and divides by three (rounded down), resulting in three seconds, and queries the first nameserver again.

6.8.5. Resolver Search Behavior in Earlier Releases

In previous releases, the resolver performed lookups as follows:
  1. Appended the default domain to the host name and performed a lookup.

  2. If the previous lookup failed, the resolver removed the leftmost label from the default domain name, appended the result to the host name and performed the lookup.

  3. If that lookup failed, the resolver again removed the leftmost label from the default domain name, appended the result to the host name, and performed the lookup.

For each unsuccessful lookup, this procedure was repeated until only two labels remained in the resulting domain name.

If all these attempts failed, the resolver tried just the host name as typed (as long as it contained at least one dot).

For example, suppose you entered the following command:
TCPIP> SHOW HOST OWL
Assuming the default domain was ucx.ern.sea.com, the resolver performed lookups as follows:
  1. On owl.ucx.ern.sea.com.

  2. If the previous lookup was unsuccessful, the resolver searched for owl.ern.sea.com.

  3. If that lookup was unsuccessful, the resolver searched for owl.sea.com.

  4. Finally, if the preceding lookup was unsuccessful, the resolver searched for owl.

6.9. BIND Server Administrative Tools

The following administrative tools play an integral part in the management of a server.
  • The bind_checkconf utility checks the syntax of the BIND server configuration file.

  • The bind_checkzone utility checks a zone file for syntax and consistency.

  • The dnssec_keygen generates keys for DNSSEC (secure DNS) and TSIG (transaction signatures).

  • The dnssec_signzone utility signs a zone.

  • The rndc utility allows you to control the operation of a name server.

  • The rndc_confgen utility generates configuration files for the rndc utility.

To use these utilities, you must have system management privileges. Run the TCPIP$DEFINE_COMMANDS.COM procedure to define the commands described in the following reference sections.

Note

In this version of TCP/IP Services, the BIND Server and related utilities have been updated to use the OpenSSL shareable image SSL$LIBCRYPTO_SHR32.EXE. There is now a requirement that this shareable image from OpenSSL V1.2 or higher be installed on the system prior to starting the BIND Server. It must also be installed prior to using the following BIND utilities:
BIND_CHECKCONF
BIND_CHECKZONE
DIG
DNSSEC_KEYGEN
DNSSEC_SIGNZONE
HOST
NSUPDATE
RNDC_CONFGEN

bind_checkconf

bind_checkconf — Checks the syntax of a BIND server configuration file.

Syntax

bind_checkconf [-v] [-j] [-t directory] filename [-z]

Description

The bind_checkconf utility checks the syntax, but not the semantics, of a BIND server configuration file.

Options

-j

When loading a zonefile, read the journal if it exists.

-z

Perform a test load of the master zonefiles found in TCPIP$BIND.CONF.

-t directory

Looks for filename in the specified directory. The default directory is SYS$SPECIFIC:[TCPIP$BIND].

-v

Displays only the version number of the bind_checkconf utility and exits.

filename

Specifies the name of the configuration file to be checked. The default file is SYS$SPECIFIC:[TCPIP$BIND]TCPIP$BIND.CONF.

bind_checkzone

bind_checkzone — Checks a zone file for syntax and consistency.

Syntax

bind_checkzone [-d] [-j] [-q] [-v] [-c class] [-k mode] [-n mode] [-o filename] [-t directory] [-w directory] [-D] zonename filename

Description

The bind_checkzone utility checks the syntax and integrity of a zone file. It performs the same checks as the BIND server does when it loads a zone. This makes bind_checkzone useful for checking zone files before configuring them into a name server.

Options

-d

Enables debugging mode.

-j

When loading the zonefile, read the journal if it exists.

-q

Enables quiet mode (exit code only).

-v

Displays the version number of bind_checkzone and exits.

-c class

Specifies the class of the zone. If not specified, the default is IN.

-k mode
Perform check-name checks with the specified failure mode. Possible modes are:
  • fail

  • warn (default)

  • ignore

-n mode
Specify whether NS records should be checked to see if they are addresses. Possible modes are:
  • fail

  • warn (default)

  • ignore

-o filename

Write zone output to the specified file. Only valid when used with the -D option.

-t directory

Looks for the zone in the specified directory. The default directory is SYS$SYSPECIFIC:[TCPIP$BIND].

-w directory

Change directory so that relative filenames in master file $INCLUDE directives work. This is similar to the directory clause in the TCPIP$BIND.CONF configuration file.

-D

Dump zone file information in canonical format.

zonename

Specifies the name of the zone being checked.

filename

Specifies the name of the zone file.

dnssec_keygen

dnssec_keygen — Generates keys for DNSSEC.

Syntax

dnssec_keygen -a algorithm -b keysize -n nametype [-c class] [-e] [-f flag] [-g generator] [-h] [-k] [-p protocol] [-r randomfile] [-s strength] [-t type] [-v level] name

Description

The dnssec_keygen utility generates keys for DNSSEC, as defined in RFC 2535. It can also generate keys for use with TSIG (Transaction Signatures), as defined in RFC 2845.

Parameters

name

Specifies the name of the domain.

Options

-a algorithm
Selects the cryptographic algorithm. The value of algorithm must be one of the following:
  • RSAMD5 (RSA)

  • RSASHA1

  • DSA

  • DH (Diffie-Hellman)

  • HMAC-MD5

These values are not case sensitive. HMAC-MD5 and DH automatically set the -k option.

-b keysize
Specifies the number of bits in the key. The choice of key size depends on the algorithm used:
  • RSAMD5/RSASHA1 keys must be between 512 and 4096 bits.

  • DH keys must be between 128 and 4096 bits.

  • DSA keys must be between 512 and 1024 bits and must be an exact multiple of 64.

  • HMAC-MD5 keys must be between 1 and 512 bits.

-n nametype
Specifies the owner type of the key. The value of nametype must one of the following:
  • ZONE (for a DNSSEC zone key (KEY/DNSKEY))

  • HOST or ENTITY (for a key associated with a host (KEY))

  • USER (for a key associated with a user (KEY))

  • OTHER (DNSKEY)

These values are not case sensitive.

-c class

Indicates that the DNS record containing the key should have the specified class. If not specified, class IN is used.

-e

If generating an RSAMD5/RSASHA1 key, specifies the use of a large exponent.

-f flag

Set the specified flag in the flag field of the KEY/DNSKEY record. The only recognized flag is KSK (Key Signing Key) DNSKEY.

-g generator

If generating a Diffie-Hellman key, specifies the generator. Allowed values for generator are 2 and 5. If no generator is specified, a known prime from RFC 2539 is used, if possible; otherwise the default is 2.

-h

Displays a short summary of the options and arguments to the dnssec_keygen command.

-k

Generate KEY records rather than DNSKEY records.

-p protocol

Sets the protocol value for the generated key. The value of protocol is a number between 0 and 255. The default is 3 (DNSSEC). Other possible values for this argument are listed in RFC 2535 and its successors.

-r randomfile
Specifies the source of randomness. The default source of randomness is keyboard input. randomfile specifies the name of a file containing random data to be used instead of the default. The special value keyboard indicates that keyboard input should be used.

Note

When you use the keyboard to generate random data, you must input a large amount of data. Input requiring hundreds of lines of data is not unusual for some algorithms. The string stop typing appears when enough data has been input.

-s strength

Specifies the strength value of the key. The value of strength is a number between 0 and 15. This option is currently not used.

-t type
Indicates the use of the key. The type must be one of the following:
  • AUTHCONF (authenticate and encrypt data)

  • NOAUTHCONF (do not authenticate and do not encrypt data)

  • NOAUTH (do not authenticate data)

  • NOCONF (do not encrypt data)

The default is AUTHCONF.

-v level

Sets the debugging level.

Generated Keys

When dnssec_keygen completes successfully, it displays a string of the following form to standard output:
Knnnn.aaa-iiiii
This is an identification string for the key it has generated. These strings can be used as arguments to the dnssec_makekeyset utility. The string is interpreted as follows:
  • nnnn is the key name.

  • aaa is the numeric representation of the algorithm.

  • iiiii is the key identifier (or footprint).

dnssec_keygen creates two files, with names based on the printed string. The file K nnnn. aaa- iiiii_KEY contains the public key, and K nnnn. aaa- iiiii_PRIVATE contains the private key.

The _KEY file contains a DNS KEY record that can be inserted into a zone file (either directly, or using an $INCLUDE statement).

The _PRIVATE file contains algorithm-specific fields. For security reasons, this file does not have general read permission.

Both _KEY and _PRIVATE files are generated for symmetric encryption algorithms such as HMAC-MD5, even though the public and private key are equivalent.

Examples

To generate a 768-bit DSA key for the domain example.com, enter the following command:
$ dnssec_keygen -a DSA -b 768 -n ZONE example.com
This command displays a string of the form:
Kexample_com.003-26160

In this example, dnssec_keygen creates the files KEXAMPLE_COM.003-26160_KEY and KEXAMPLE_COM.003-26160_PRIVATE.

dnssec_signzone

dnssec_signzone — Signs a zone.

Syntax

dnssec_signzone [-a] [-c class] [-d directory] [-s start-time] [-e end-time] [-f output-file] [-g] [-h] [-i interval] [-k key] [-l domain] [-n nthreads] [-o origin] [-p] [-r randomfile] [-t] [-v level] [-z] zonefile [ key...]

Description

The dnssec_signzone utility signs a zone. It generates NSEC and RRSIG records and produces a signed version of the zone. The security status of delegations from the signed zone (that is, whether the child zones are secure or not) is determined by the presence or absence of a keyset file for each child zone.

Before signing the zone, you must add the KEY record to the zone database file by using the $INCLUDE statement. HP recommends the use of a Zone Signing Key (ZSK) and a Key Signing Key (KSK), in which case you must add two $INCLUDE statements, one for each key. For example, in the zone file example_com.db, add:
$INCLUDE Kexample_com.003-26160_KEY  ; ZSK
$INCLUDE Kexample_com.003-26161_KEY  ; KSK

Parameters

zonefile

Specifies the file containing the zone to be signed.

key...

Specifies the keys used to sign the zone. If no keys are specified, the default is all zone keys that have private key files in the current directory.

Options

-a

Verifies all generated signatures.

-c class

Specifies the DNS class of the zone.

-d directory

Looks for signedkey files in the specified directory.

-s start-time

Specifies the date and time when the generated RRSIG records become valid. This can be either an absolute or relative time. An absolute start time is indicated by a number in YYYYMMDDHHMMSS notation. For example, 20000530144500 denotes 14:45:00 UTC on May 30, 2000. A relative start time is indicated by +N, which is N seconds from the current time. If no start time is specified, the current time minus one hour (to allow for clock skew) is used.

-e end-time

Specifies the date and time when the generated RRSIG records expire. An absolute time is indicated in YYYYMMDDHHMMSS notation. A time relative to the start time is indicated by +N, which is N seconds from the start time. A time relative to the current time is indicated by now+N. If no end time is specified, 30 days from the start time is used as a default.

-f output-file

Specifies the name of the output file containing the signed zone. The default is to append _SIGNED to the input file name.

-g

Generate DS records for child zones from keyset file. Existing DS records will be removed.

-h

Displays a short summary of the options and arguments to the dnssec_signzone command.

-i interval

When a previously signed zone is passed as input, records may be signed again. The interval option specifies the cycle interval as an offset from the current time (in seconds). If an RRSIG record expires after the cycle interval, it is retained. Otherwise, it is considered to be expiring soon, and it will be replaced.

The default cycle interval is one quarter of the difference between the signature end and start times. Therefore, if neither the end time nor the start time is specified, the dnssec_signzone utility generates signatures that are valid for 30 days, with a cycle interval of 7.5 days. Therefore, if any existing RRSIG records are due to expire in less than 7.5 days, they are replaced.

-k key

Treat specified key as a key signing key, ignoring any key flags. This option can be specified multiple times.

-l domain

Generate a DLV set in addition to the key (DNSKEY) and DS sets. The domain is appended to the name of the records.

-n nthreads

Specifies the number of threads to use. By default, one thread is started for each detected CPU.

-o origin

Specifies the zone origin. If this option is not specified, the name of the zone file is assumed to be the origin.

-p

Uses pseudorandom data when signing the zone. This is faster, but less secure, than using real random data. This option can be useful when signing large zones or when the entropy source is limited.

-r randomfile
Specifies the source of randomness. The default source of randomness is keyboard input. randomfile specifies the name of a file containing random data to be used instead of the default. The special value keyboard indicates that keyboard input should be used.

Note

When you use the keyboard to generate random data, you must input a large amount of data. Input requiring hundreds of lines of data is not unusual for some algorithms. The string stop typing appears when enough data has been input.

-t

Displays statistics at completion.

-v level

Sets the debugging level.

-z

Ignore KSK flag on key when determining what to sign.

Examples

The following command signs the example.com zone with the DSA key generated by the dnssec_keygen utility. The zone's keys must be in the zone. If there are keyset files associated with the child zones, they must be in the current directory.
$ dnssec_signzone -o example.com example_com.db Kexample_com.003-26160
In this example, dnssec_signzone creates the file EXAMPLE_COM.DB_SIGNED. This file should be referenced in a zone statement in the TCPIP$BIND.CONF file. This command displays the following:
example_com.db_signed

rndc

rndc — Controls the operation of the BIND server.

Syntax

rndc [-c config] [-k keyfile] [-s server] [-p port] ["-V"] [-y key-id] command

Description

The rndc utility controls the operation of a name server. rndc communicates with the name server over a TCP connection, sending commands authenticated with digital signatures. The only supported authentication algorithm is HMAC-MD5, which uses a shared secret on each end of the connection. This provides TSIG-style authentication for the command request and the name server's response. All commands sent over the channel must be signed by a key_id known to the server.

In Bind Version 9 start, restart, and stop are accomplished using the command procedures as described in Section 6.3.

The rndc utility reads a configuration file to determine how to contact the name server and to decide what algorithm and key it should use.

A configuration file is required, since all communication with the server is authenticated with digital signatures that rely on a shared secret. The default location for the rndc configuration file is TCPIP$ETC:RNDC.CONF, but an alternate location can be specified with the -c option. If the configuration file is not found, rndc also looks in TCPIP$ETC:RNDC.KEY. The RNDC.KEY file is generated by running rndc_confgen -a. This command provides basic functionality, but it offers less configuration flexibility than modifying the RNDC.CONF file.

Note

For the BIND server to recognize a newly generated RNDC.KEY file, you must stop and restart the BIND server.

Format of the RNDC.CONF File

The configuration file for the rndc utility is TCPIP$ETC:RNDC.CONF. The structure of this file is similar to TCPIP$BIND.CONF. Statements are enclosed in braces and are terminated with semicolons. Clauses in the statements are also terminated with semicolons. For example:
options {
    default-server    localhost;
    default-key       samplekey;
};

server localhost {
    key               samplekey;
};

key samplekey {
    algorithm         hmac-md5
    secret            "c3Ryb25nIGVub3VnaCBmb3IgYSBtYW";
};
Three statements are used in the RNDC.CONF file:
  • The options statement contains three clauses:
    • The default-server clause is followed by the name or address of a name server. This host is used when the name server is not specified as an argument to rndc.

    • The default-key clause is followed by the name of a key, which is represented by a key statement and is used when the key-id is not specified on the rndc command line and when no key clause is found in a matching server statement. This key is used to authenticate the server's commands and response.

    • The default-port clause is followed by the port to connect to on the remote name server. This port is used if no -p port statement is supplied on the rndc command line and no port clause is included in a matching server statement.

  • The server statement specifies a host name or address for a name server. The statement may include the key clause and the port clause. The key name must match the name of a key statement in the file. The port number specifies the port to connect to.

  • The key statement specifies the name of a key. The statement has two clauses:
    • algorithm specifies the encryption algorithm for rndc to use (HMAC-MD5).

    • A secret clause containing the 64-bit encoding of the algorithm's encryption key. The base-64 string is enclosed in quotation marks.

      To generate the base-64 string for the secret clause, use the rndc_confgen utility. For example, enter the following command: $ rndc_confgen

      A complete RNDC.CONF file, including the randomly-generated key, is automatically generated. The rndc_confgen command also displays commented key and controls statements for the TCPIP$BIND.CONF file.

Commands

reload

Reloads configuration file and zones.

reload zone [ class [ view]]

Reload the given zone.

refresh zone [ class [ view]]

Schedule zone maintenance for the given zone.

retransfer zone [ class [ view]]

Retransfer the specified zone from the master.

freeze zone [ class [ view]]

Suspend updates to a dynamic zone. This allows manual edits to be made to a zone normally updated by dynamic update. It also causes changes in the journal file to be synchronized into the master and the journal file to be removed. All dynamic update attempts will be refused while the zone is frozen.

unfreeze zone [ class [ view]]

Enable updates to a frozen dynamic zone. This causes the server to reload the zone from disk, and re-enables dynamic updates after the load has completed. After a zone is unfrozen, dynamic updates will no longer be refused.

reconfig

Reloads the configuration file and loads new zones, but does not reload existing zone files even if they have changed. This is faster than a full reload when there is a large number of zones because it avoids the need to examine the modification times of the zones files.

stats

Writes server statistics to the statistics file, TCPIP$BIND.STATS.

querylog

Toggles query logging. Query logging can also be enabled by explicitly directing the queries category to a channel in the logging section of TCPIP$BIND.CONF.

dumpdb

Dumps the server's caches to the dump file, TCPIP$BIND_DUMP.DB.

trace

Increments the servers debugging level by one.

trace level

Sets the server's debugging level to an explicit value.

notrace

Sets the server's debugging level to 0.

flush

Flushes the server's cache.

flush-updates

Saves any pending dynamic updates being stored in the zone journal (_JNL) files to the master zone files. (This command is available on OpenVMS systems only.)

status

Displays the status of the server. The number of zones includes the internal /CH zone, and the default . /IN hint zone if no root zone has been explicitly configured.

Options

-c config-file

Uses config-file as the configuration file instead of the default, TCPIP$ETC:RNDC.CONF.

-k keyfile

Use the specified keyfile instead of the default (TCPIP$ETC:RNDC.KEY). If the configuration file does not exist, the key from TCPIP$ETC:RNDC.KEY will be used instead.

-s server

Specifies the name or address of the server which matches a server statement in the configuration file for rndc. If no server is supplied on the command line, the host named by the default-server clause in the option statement of the configuration file is used.

-p port

Send commands to the specified TCP port instead of the default control channel port, 953.

"-V"

Enables verbose logging. Use quotation marks to preserve uppercase options.

-y keyid

Use the specified keyid from the configuration file specified with the -c option. If the configuration file was not specified on the command line, the rndc configuration file, RNDC.CONF, is used. The keyid must be known by the BIND server with the same algorithm and secret string in order for control message validation to succeed.

If no keyid is specified, rndc first looks for a key clause in the server statement of the server being used, or if no server statement is present for that host, then the default-key clause of the options statement.

Note that the configuration file contains shared secrets that are used to send authenticated control commands to name servers. Therefore, the file should not have general read or write access.

rndc_confgen

rndc_confgen — Generates the configuration files used by the rndc utility.

Syntax

rndc_confgen [-a] [-b keysize] [-c keyfile] [-h] [-k keyname] [-p port] [-r randomfile] [-s address]

Description

The rndc_confgen utility generates configuration files for the rndc utility. It can be used as a convenient alternative to writing the RNDC.CONF file and the corresponding controls and key statements in TCPIP$BIND.CONF by hand. The utility can be run with the -a option to set up an RNDC.KEY file, thereby avoiding the need for an RNDC.CONF file and a controls statement.

Options

-a

Configures rndc automatically. This option creates the file RNDC.KEY in TCPIP$ETC that is read by both rndc and the BIND server on startup. The RNDC.KEY file defines a default command channel and authentication key, allowing rndc to communicate with the BIND server on the local host with no further configuration.

Using the -a option allows BIND Version 9 and rndc to be used as drop-in replacements for BIND Version 8 and ndc, with no changes to the existing TCPIP$BIND.CONF file.

If a more elaborate configuration than that generated by rndc_confgen -a is required (for example, if rndc is to be used remotely), you should run rndc_confgen without the -a option and set up a TCPIP$RNDC.CONF file and a TCPIP$BIND.CONF file as directed.

Note

For the BIND server to recognize a newly generated RNDC.KEY file, you must stop and restart the BIND server.

-b keysize

Specifies the size of the authentication key in bits. Must be between 1 and 512 bits; the default is 128.

-c keyfile

Used with the -a option to specify an alternate location for RNDC.KEY.

-h

Prints a short summary of the options and arguments to rndc_confgen.

-k keyname

Specifies the key name of the rndc authentication key. This must be a valid domain name. The default is rndc-key.

-p port

Specifies the command channel port where the BIND server listens for connections from rndc. The default is 953.

-r randomfile

Specifies a source of random data for generating the authorization. The default source of randomness is keyboard input. randomfile specifies the name of a file containing random data to be used instead of the default. The special value keyboard indicates that keyboard input should be used.

-s address

Specifies the IP address where the BIND server listens for command channel connections from rndc. The default is the loopback address 127.0.0.1.

nsupdate

nsupdate — Updates Domain Name System (DNS) servers interactively.

Syntax

nsupdate [-d] [-y keyname:secret | [-k keyfile] [-r udpretries] [-t timeout] [-u udptimeout] [-v] [ filename]

Description

The nsupdate utility creates dynamic updates, which are sent to a DNS server to update the zone database. nsupdate uses the DNS resolver library to send dynamic updates to a DNS server requesting the addition or deletion of resource records. The zone must be configured to accept dynamic updates for the nsupdate utility to work.

The nsupdate command can accept either a command or the name of a command file.

Zones that are under dynamic control (with nsupdate or a DHCP server) should not be edited by hand. Manual updates could conflict with dynamic updates, causing data to be lost.

If you use a file to supply the updates, the data in the file must be in the following format:
category section name ttl type rdata
In this format:
  • category is any one of the following keywords:
    • update

    • zone

    • prereq

  • section is any one of the following keywords:
    • add

    • delete

    • nxdomain

    • yxdomain

    • nxrrset

    • yxrrset

  • name is the name of the entry being added.

  • ttl is the time to live (in seconds) for this entry. After this time period, the name server no longer serves the entry.

  • type specifies the RR type (for example, A, CNAME, NS, MX, TXT).

  • rdata specifies the data appropriate for the RR type being updated.

Lines beginning with a semicolon are comments and are ignored.

Options

-d

Specifies debug mode.

-y keyname:secret

Generates a signature, where keyname specifies the name of the key and secret is a base-64 encoded secret. This option is not recommended because it displays the shared secret in plain text. Instead, use the -k option.

-k keyfile
Specifies a file that contains the shared secret. The file name has the following format:
Kname.157-random_PRIVATE

For historical reasons, the file Kname.157-random_KEY must also be present.

-r udpretries

Sets the number of UDP retries. The default is 3. If zero, only one update request will be made.

-t timeout

Sets the maximum time an update request can take before it is aborted. The default is 300 seconds. Zero can be used to disable the timeout.

-u udpretries

Sets the UDP retry interval. The default is 3 seconds. If zero, the interval will be computed from the timeout interval and number of UDP retries.

-v

Specifies that nsupdate use the TCP protocol instead of the UDP protocol. By default, nsupdate sends update requests using UDP.

filename

Specifies a file that contains nsupdate commands.

If you do not specify the name of a command file, the NSUPDATE command prompts for a command line. Enter one or more of the following commands.

Commands

server servername [port]

Sends all dynamic update requests to the specified name server. When no name server is specified, the nsupdate utility sends updates to the master server of the correct zone. The MNAME field of that zone's SOA record identifies the master server for that zone. port is the port number to which the dynamic update requests are sent on the specified name server. If no port number is specified, the default DNS port number of 53 is used.

local address [port]

Sends all dynamic update requests using the local address. When no local address is provided, the nsupdate utility sends updates using an address and port chosen by the system. Specify port to make requests come from a specific port. If no port number is specified, the system assigns one.

zone zonename

Specifies that all updates are to be made to the specified zone. If no zone command is provided, the nsupdate utility attempts to determine the correct zone to update based on the rest of the input.

class classname

Specifies the default class. If no class is specified, the default class is IN.

key keyname secret

Specifies that all updates are to be TSIG signed, using the specified keyname and key secret pair.

The key command overrides any key specified on the command line using the -y or -k options.

prereq nxdomain domain-name

Requires that no resource record of any type exist with the specified domain name.

prereq yxrset domain-name type [data]

Makes the presence of an RR set of the specified type owned by domain-name a prerequisite to performing the update. This requires that a resource record of the specified type, class, and domain name must exist. If class is omitted, IN (Internet) is assumed.

prereq nxrrset domain-name [class] {type}

Makes the nonexistence of an RRset of type owned by domain-name a prerequisite to performing the update specified in successive update commands. This requires that no resource record exist of the specified type, class, and domain name. If class is omitted, IN (Internet) is assumed.

The data from each set of prerequisites of this form sharing a common type, class, and domain name are combined to form a set of resource records. This set of resource records must exactly match the set of resource records on the zone at the given type, class, and domain name. The data is written in the standard text representation of the resource record's RDATA.

prereq yxdomain domain-name

Makes the existence of the specified domain-name a prerequisite to performing the update. This requires that the domain name has at least one resource record of any type.

update delete domain-name ttl[class] [type] [rdata]

Deletes any resource records with the specified domain name. If type and data are provided, only matching resource records are removed. If class is omitted, IN (Internet) is assumed. The ttl value is ignored and is included only for compatibility.

update add domain-name ttl[class] type data

Adds a new resource record with the specified ttl, class, and data to the zone. The ttl value, the type, and the data must be included. The class is optional and defaults to IN.

show

Displays the current message, containing all of the prerequisites and updates specified since the last send command.

send

Sends the current message. This is equivalent to entering a blank line.

answer

Displays the answer.

Examples

  1. $ TYPE NSUPD.TXT
    update delete www.nads.zn.
    update add www.nads.zn. 60 CNAME ivy18.nads.zn
    
    $ NSUPDATE NSUPD.TXT

    This example shows how to supply a file (NSUPD.TXT) to the nsupdate utility.

  2. $ NSUPDATE
    > update delete oldhost.example.com A
    > update add newhost.example.com 86400 A 172.16.1.1
    >

    This example shows how the nsupdate utility is used interactively to insert and delete resource records from the example.com zone. Notice that the input contains an extra blank line so that a group of commands are sent as one dynamic update request to the master name server for example.com.

    Any A records for oldhost.example.com are deleted, and an A record for newhost.example.com with IP address 172.16.1.1 is added. The newly added record has a TTL value of 86400 seconds (one day).

  3. $ NSUPDATE
    > prereq nxdomain nickname.example.com
    > update add nickname.example.com 86400 CNAME somehost.example.com
    >

    This example tells the BIND server to verify the prerequisite condition that no resource records of any type exist for nickname.example.com. If any records exist, the update request fails. If no records with that name exist, a CNAME is added for it.

    This prerequisite condition is an RFC restriction that has been relaxed to allow for RRSIG, DNSKEY, and NSEC records to exist.

    After entering data in interactive mode, press Return (or Enter) on a line with no data to complete the input. Alternatively, you can issue the SEND command. The nsupdate utility then processes all update entries in one operation.

6.10. BIND Version 9 Restrictions

BIND Version 9 has the following restrictions:
  • Certain DNS server implementations do not support AAAA (IPv6 address) records. When queried for an AAAA (IPv6) record type by the BIND resolver, these name servers will return an NXDOMAIN status, even if an A (IPv4) record exists for the same domain name. These name servers should be returning NOERROR as the status for such a query. This problem can result in delays during host name resolution.

    BIND Version 9.3.1, which is supported with this release of TCP/IP Services, and prior versions of BIND do not exhibit this problem.

  • Serving secure zones

    When acting as an authoritative name server, BIND Version 9 includes KEY, SIG, and NXT records in responses as specified in RFC 2535 when the request has the DO flag set in the query.

    Response generation for wildcard records in secure zones is not fully supported. Responses indicating the nonexistence of a name include an NXT record proving the nonexistence of the name itself, but do not include any NXT records to prove the nonexistence of a matching wildcard record. Positive responses resulting from wildcard expansion do not include the NXT records to prove the nonexistence of a non-wildcard match or a more specific wildcard match.

  • Secure resolution

    Basic support for validation of DNSSEC signatures in responses has been implemented but should be considered experimental.

    When acting as a caching name server, BIND Version 9 is capable of performing basic DNSSEC validation of positive as well as nonexistence responses. You can enable this functionality by including a trusted-keys clause containing the top-level zone key of the DNSSEC tree in the configuration file.

    Validation of wildcard responses is not currently supported. In particular, a "name does not exist" response will validate successfully even if the server does not contain the NXT records to prove the nonexistence of a matching wildcard.

    Proof of insecure status for insecure zones delegated from secure zones works when the zones are completely insecure. Privately secured zones delegated from secure zones will not work in all cases, such as when the privately secured zone is served by the same server as an ancestor (but not parent) zone.

    Handling of the CD bit in queries is now fully implemented. Validation is not attempted for recursive queries if CD is set.

  • Secure dynamic update

    Dynamic updating of secure zones has been partially implemented. Affected NXT and SIG records are updated by the server when an update occurs. Use the update-policy statement in the zone definition for advanced access control.

  • Secure zone transfers

    BIND Version 9 does not implement the zone transfer security mechanisms of RFC 2535 because they are considered inferior to the use of TSIG or SIG(0) to ensure the integrity of zone transfers.

6.11. Solving Bind Server Problems

6.11.1. BIND Server Diagnostic Tools

The TCP/IP Services product provides the following utilities for diagnosing problems with the BIND server:
  • The dig utility

  • The host utility

  • The nslookup utility

The following sections describe these utilities.

Note

The nslookup utility is no longer recommended. Use the dig utility instead.

dig

dig — Gathers information from the Domain Name System servers.

Syntax

dig [@ server] [- option] [ name] [ type] [ class] [ queryopt...]

Description

dig is a flexible tool for interrogating DNS name servers. It performs DNS lookups and displays the answers that are returned from the name servers that were queried. Most DNS administrators use dig to troubleshoot DNS problems because of its flexibility, ease of use and clarity of output. Other lookup tools tend to have less functionality than dig.

Although dig normally is used with command-line arguments, it also has a batch mode of operation for reading lookup requests from a file. A brief summary of its command-line arguments and options is printed when the -h option is given. Unlike earlier versions of BIND, the BIND Version 9 implementation of dig allows multiple lookups to be issued from the command line.

Unless it is told to query a specific name server, dig tries each of the servers listed in your resolver configuration. When no command line arguments or options are given, dig performs an NS query for "." (the root).

dig has two modes: simple interactive mode, for a single query, and batch mode, which executes a query for each in a list of several query lines. All query options are accessible from the command line.

To get online help for the dig utility, enter the -h option on the command line. For example: $ dig -h

Parameters

@ server

Specifies the name or IP address of the name server to query. This can be either an IPv4 address in dotted-decimal notation or an IPv6 address in colon-delimited notation. When the supplied server argument is a host name, dig resolves that name before querying that name server. If no server argument is provided, dig consults your resolver configuration and queries the name servers listed there. The reply from the name server that responds is displayed.

name

Specifies the name of the resource record to look up.

type

Indicates the type of query required (ANY, A, MX, SIG, and so forth). If the type parameter is not supplied, dig performs a lookup for an A record.

class

Specifies the DNS query class. The default is class IN (Internet).

Options

-b address

Sets the source IP address of the query to address. This must be a valid address on one of the host's network interfaces or 0.0.0.0 or ::. You can specify an optional port by appending #port.

-c class

Specifies the query class. class is any valid class, such as HS for hesiod records or CH for CHAOSnet records. The default query class is IN (Internet).

-f filename

Makes dig operate in batch mode by reading a list of lookup requests to process from the specified file. The file contains a number of queries, one per line. Each entry in the file should be organized in the same way that dig queries are presented using the command-line interface.

-k filename

Allows you to sign the DNS queries sent by dig and their responses using transaction signatures (TSIG). Specify a TSIG key file for filename.

-p port

Allows you to specify a nonstandard port number. port is the port number that dig uses to send its queries instead of the standard DNS port number 53. You can use this option to test a name server that has been configured to listen for queries on a nonstandard port number.

-t type

Sets the query type to type, which can be any valid query type supported in BIND Version 9. The default query type is A, unless the -x option is supplied to indicate a reverse lookup. A zone transfer can be requested by specifying a type of AXFR. When an incremental zone transfer (IXFR) is required, type is set to ixfr=N. The incremental zone transfer contains the changes made to the zone since the serial number in the zone's SOA record was N.

-x addr

Specifies reverse lookups (mapping addresses to names). addr is either an IPv4 address in dotted-decimal notation or a colon-delimited IPv6 address. This option eliminates the need to provide the name, class, and type arguments. dig automatically performs a lookup for a name like 11.12.13.10.in-addr.arpa and sets the query type and class to PTR and IN, respectively. By default, IPv6 addresses are looked up using the IP6.ARPA domain and the nibble format. To use the older RFC 1886 method using the IP6.INT domain, specify the -i option. Bit string labels (RFC 2874) are now experimental and are not attempted.

-y name:key

Allows you to specify the TSIG key itself on the command line. name is the name of the TSIG key and key is the actual key. The key is a base-64 encoded string, typically generated by dnssec_keygen. When using TSIG authentication with dig, the name server that is queried needs to know the key and algorithm that is being used. In BIND, this is done by providing appropriate key and server statements in TCPIP$BIND.CONF.

-4

Forces dig to only use IPv4 query transport.

-6

Forces dig to only use IPv6 query transport.

Query Options

Each query option is identified by a keyword preceded by a plus sign (+). Some keywords set or reset an option. These can be preceded by the string no to negate the meaning of that keyword. Other keywords (like that which sets the timeout interval) assign values to options. These types of keywords have the form +keyword=value.

The query options are:

+[no]tcp

Specifies whether to use TCP when querying name servers. The default behavior is to use UDP unless an AXFR or IXFR query is requested, in which case a TCP connection is used.

+[no]vc

Specifies whether to use TCP when querying name servers. This alternate syntax to [no]tcp is provided for backward compatibility. (vc stands for virtual circuit.)

+[no]ignore

Ignores truncation in UDP responses instead of retrying with TCP. By default, TCP retries are performed.

+domain= name

Sets the search list to contain the single domain name, as if specified in a domain directive in your resolver configuration. Enables search list processing as if the search option were specified.

+[no]search

Specifies whether to use the search list defined by the path directive in your resolver configuration. By default, the search list is not used.

+[no]defname

This deprecated option is treated as a synonym for [no]search.

+[no]aaonly

Sets the aa flag in the query.

+[no]aaflag

Same as +[no]aaonly.

+[no]cl

Display or no not display the class when printing the record.

+[no]adflag

Specifies whether to set the AD (authentic data) bit in the query. The AD bit currently has a standard meaning only in responses, not in queries, but the ability to set the bit in the query is provided for completeness.

+[no]cdflag

Specifies whether to set the CD (checking disabled) bit in the query. This requests the server to not perform DNSSEC validation of responses.

+[no]recurse

Toggles the setting of the RD (recursion desired) bit in the query. This bit is set by default, which means dig normally sends recursive queries. Recursion is automatically disabled when the nssearch or trace query options are used.

+[no]nssearch

Attempts to find the authoritative name servers for the zone containing the name being looked up. Displays the SOA record that each name server has for the zone.

+[no]trace

Toggles tracing of the delegation path from the root name servers for the name being looked up. Tracing is disabled by default. When tracing is enabled, dig makes iterative queries to resolve the name being looked up, following referrals from the root servers and showing the answer from each server that was used to resolve the lookup.

+[no]cmd

Toggles the printing of the initial comment in the output identifying the version of dig and the query options that have been applied. This comment is printed by default.

+[no]short

Provides a terse answer. The default is to print the answer in verbose form.

+[no]identify

Specifies whether to show the IP address and port number that supplied the answer when the +short option is enabled. If terse answers are requested, the default is not to show the source address and port number of the server that provided the answer.

+[no]comments

Toggles the display of comment lines in the output. The default is to print comments.

+[no]stats

Toggles the printing of statistics, such as when the query was made, the size of the reply, and so on. The default behavior is to print the query statistics.

+[no]qr

Specifies whether to print the query as it is sent. By default, the query is not printed.

+[no]question

Specifies whether to print the question section of a query when an answer is returned. The default is to print the question section as a comment.

+[no]answer

Specifies whether to display the answer section of a reply. The default is to display the answer section.

+[no]authority

Specifies whether to display the authority section of a reply. The default is to display the authority section.

+[no]additional

Specifies whether to display the additional section of a reply. The default is to display the additional section.

+[no]all

Specifies whether to set or clear all display flags.

+time= T

Sets the timeout for a query to T seconds. The default timeout is 5 seconds. An attempt to set T to less than 1 results in a query timeout of 1 second.

+retry=A

Sets the number of times to try UDP queries to the server to A instead of to the default of 2. Unlike +tries, this does not include the initial query.

+tries= A

Sets the number of times to try UDP queries to the server to A instead of the default of 2. Unlike +tries, this does not include the initial query.

+ndots= D

Set the number of dots that have to appear in name to D for it to be considered absolute. The default value is 1.

Names with fewer dots are interpreted as relative names and are searched for in the domains listed in the search or domain directive in your resolver configuration.

+bufsize= B

Set the UDP message buffer size advertised using EDNS0 to B bytes. The maximum and minimum sizes of this buffer are 65535 and 0, respectively. Values outside this range are rounded up or down appropriately.

+[no]multiline

Prints records like the SOA records in a verbose multiline format with human-readable comments. The default is to print each record on a single line, to facilitate machine parsing of the output.

+[no]fail

Do not try the next server if you receive a SERVFAIL. The default is to not try the next server which is the reverse of normal stub resolver behaviour.

+[no]besteffort

Attempts to display the contents of messages which are malformed. The default is to not display malformed answers.

+[no]dnssec

Requests DNSSEC records be sent by setting the DNSSEC OK bit (DO) in the the OPT record in the additional section of the query.

+[no]sigchase

Chase DNSSEC signature chains.

+trust-key= nnnn

Specify a trusted key to be used with +sigchase.

+[no]topdown

When chasing DNNSEC signature chains, perform a top-down validation.

Multiple Queries

The BIND Version 9 implementation of dig supports the specification of multiple queries on the command line (in addition to supporting the -f batch file option). Each of those queries can be supplied with its own set of flags, options, and query options.

Each query argument represent an individual query in the command-line syntax. Each individual query consists of any of the standard options and flags, the name to be looked up, an optional query type and class, and any query options that are needed.

A global set of query options, which should be applied to all queries, can also be supplied. These global query options must precede the first tuple of name, class, type, options, flags, and query options supplied on the command line. Any global query options (except for the +[no]cmd option) can be overridden by a query-specific set of query options.

Examples

The following example shows how to use dig from the command line to make three lookups:

  1. An ANY query for www.isc.org

  2. A reverse lookup of 127.0.0.1

  3. A query for the NS records of isc.org.

dig +qr www.isc.org any -x 127.0.0.1 isc.org ns +noqr

; 
<
<>> DiG 9.2.0 
<
<>> +qr www.isc.org any -x 127.0.0.1 isc.org ns +noqr
;; global options:  printcmd
;; Got answer:
;; ->>HEADER
<
<- opcode: QUERY, status: NOERROR, id: 38437
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 5, ADDITIONAL: 5

;; QUESTION SECTION:
;www.isc.org.                   IN      ANY

;; ANSWER SECTION:
www.isc.org.            3421    IN      CNAME   isc.org.

;; AUTHORITY SECTION:
isc.org.                3421    IN      NS      gns1.nominum.com.
isc.org.                3421    IN      NS      gns2.nominum.com.
isc.org.                3421    IN      NS      ns-ext.vix.com.
isc.org.                3421    IN      NS      ns-int.vix.com.
isc.org.                3421    IN      NS      ns1.gnac.com.

;; ADDITIONAL SECTION:
ns1.gnac.com.           17389   IN      A       209.182.195.77
gns1.nominum.com.       92      IN      A       198.133.199.1
gns2.nominum.com.       68661   IN      A       198.133.199.2
ns-ext.vix.com.         2601    IN      A       204.152.184.64
ns-int.vix.com.         828     IN      A       204.152.184.65

;; Query time: 134 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Tue Nov  6 13:09:16 2001
;; MSG SIZE  rcvd: 241

;; Got answer:
;; ->>HEADER
<
<- opcode: QUERY, status: NOERROR, id: 16441
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 1, ADDITIONAL: 1

;; QUESTION SECTION:
;1.0.0.127.in-addr.arpa.                IN      PTR

;; ANSWER SECTION:
1.0.0.127.in-addr.arpa. 86400   IN      PTR     localhost.

;; AUTHORITY SECTION:
0.0.127.in-addr.arpa.   86400   IN      NS      localhost.

;; ADDITIONAL SECTION:
localhost.              86400   IN      A       127.0.0.1

;; Query time: 224 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Tue Nov  6 13:09:16 2001
;; MSG SIZE  rcvd: 93

;; Got answer:
;; ->>HEADER
<
<- opcode: QUERY, status: NOERROR, id: 9922
;; flags: qr rd ra; QUERY: 1, ANSWER: 5, AUTHORITY: 0, ADDITIONAL: 5

;; QUESTION SECTION:
;isc.org.                       IN      NS

;; ANSWER SECTION:
isc.org.                3421    IN      NS      ns-ext.vix.com.
isc.org.                3421    IN      NS      ns-int.vix.com.
isc.org.                3421    IN      NS      ns1.gnac.com.
isc.org.                3421    IN      NS      gns1.nominum.com.
isc.org.                3421    IN      NS      gns2.nominum.com.

;; ADDITIONAL SECTION:
ns1.gnac.com.           17389   IN      A       209.182.195.77
gns1.nominum.com.       92      IN      A       198.133.199.1
gns2.nominum.com.       68661   IN      A       198.133.199.2
ns-ext.vix.com.         2601    IN      A       204.152.184.64
ns-int.vix.com.         828     IN      A       204.152.184.65

;; Query time: 198 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Tue Nov  6 13:09:17 2001
;; MSG SIZE  rcvd: 223



A global query option of +qr is applied so that dig shows the initial query it made for each lookup. The final query has a local query option of +noqr, which means that dig will not print the initial query when it looks up the NS records for isc.org.

The final portion of the output displays the following information:
  • Amount of time the query took

  • Server and port to which the query was sent, in the form server# port

  • Date and time of the query

  • Message size

host

host — The host utility allows you to look up Internet host names. By default, the host utility converts between host names and Internet addresses, but its functionality can be extended with the use of options.

Syntax

host [-a"C"dlr"T"vw] [-c class] [-i] ["-N" ndots] ["-R" number] [-t type] ["-W" wait] [-4] [-6] name [ server]

Note

Use quotation marks to preserve the casing of uppercase options.

Description

The host utility is used to convert names to IP addresses and vice versa. When no arguments or options are given, the host utility prints a short summary of its command line arguments and options.

Parameters

name

Specifies the domain name that is to be looked up. It can also be a dotted-decimal IPv4 address or a colon-delimited IPv6 address, in which cases the host performs a reverse lookup for that address by default.

[server]

Specifies the name or IP address of the name server that the host utility should query instead of the server or servers listed in your resolver configuration.

Options

-a

Equivalent to setting the -v option and asking the host utility to make a query of type ANY.

"-C"
Displays the SOA records for zone name from all the listed authoritative name servers for that zone. The list of name servers is defined by the NS records that are found for the zone. The -C option must be enclosed in quotation marks. For example:
$ host "-C" name
-c class

Makes a DNS query of class class. This can be used to look up hesiod or CHAOSnet class resource records. The default class is IN (Internet).

-d

Specifies verbose output.

-l

Selects list mode. This makes the host utility perform a zone transfer for zone name. Transfer the zone, printing out the NS, PTR, and address records (A/AAAA). If combined with the -a option, all records will be printed.

-i

Specifies that reverse lookups of IPv6 addresses should use the IP6.INT domain as defined in RFC 1886. The default is to use IP6.ARPA.

"-N" number

Sets the number of dots that have to be in the zone name for it to be considered absolute. The default value is 1. Names with fewer dots are interpreted as relative names and are searched for in the domains listed in the search path defined in the resolver configuration.

"-R" number

Changes the number of UDP retries for a lookup. The value for number indicates how many times the host utility repeats a query that does not get answered. The default number of retries is 1. If number is negative or zero, the number of retries defaults to 1.

-r

Makes nonrecursive queries. Setting this option clears the RD (recursion desired) bit in the query that the host utility makes. This should mean that the name server receiving the query does not attempt to resolve name. The -r option enables host to mimic the behavior of a name server by making nonrecursive queries and expecting to receive answers to those queries that are usually referrals to other name servers.

"-T"

Uses a TCP connection when querying the name server. By default, the host utility uses UDP when making queries.

TCP is automatically selected for queries that require it, such as zone transfer (AXFR) requests.

-t type

Selects the query type. type can be any recognized query type, such as CNAME, NS, SOA, SIG, KEY, or AXFR. When no query type is specified, the host utility automatically selects an appropriate query type. By default, the host utility looks for A records, but if the -C option is specified, queries are made for SOA records. If name is a dotted-decimal IPv4 address or a colon-delimited IPv6 address, the host utility queries for PTR records. If a query type of IXFR is chosen the starting serial number can be specified by appending an equal sign followed by the starting serial number (e.g., -t IXFR=12345678).

-v

Generates verbose output.

"-W" wait

Makes the host utility wait for the number of seconds specified by wait before making the query. If wait is less than 1, the wait interval is set to 1 second.

-w

Waits forever for a reply. The time to wait for a response is set to the number of seconds given by the hardware's maximum value for an integer quantity.

-4

Forces the host utility to only use IPv4 query transport.

-6

Forces the host utility to only use IPv6 query transport.

6.12. Using NSLOOKUP to Query a Name Server

The nslookup utility is a debugging tool provided with BIND that allows anyone to directly query a name server and retrieve information. Use NSLOOKUP to determine whether your local name server is running correctly or to retrieve information from remote servers.

nslookup makes direct queries to name servers around the world to obtain DNS information, which includes the following:
  • Host names and addresses on the local domain

  • Host names and addresses on remote domains

  • Host names that serve as Mail Exchange (MX) records

  • Name servers for a specific zone


Note

The nslookup utility is not recommended. Use the dig utility instead.

For online information about using the nslookup utility, enter the following command:
$ HELP TCPIP_SERVICES NSLOOKUP

6.13. Solving Specific Name Server Problems

The following sections describe some problems commonly encountered with BIND and how to solve them.

6.13.1. Server Not Responding

A missing client name in the BIND server's database files results in lack of service to that client. If records that point to the name servers (NS records) in a domain are missing from your server's database files, you might see the following messages:
%TCPIP-W-BIND_NOSERVNAM, Server with address 199.85.8.8 is not responding
%TCPIP-E-BIND_NOSERVERS, Default servers are not available
%TCPIP-W-NORECORD, Information not found
-TCPIP-E-BIND_NOSERVERS, Default servers are not available

When the CONVERT/ULTRIX BIND /DOMAIN command creates the .DB files from the hosts database, it cannot detect the existence or the names of name servers in a domain. Therefore, it does not add NS records for the name servers to the .DB files.

To solve the problem, follow these steps:
  1. Stop the BIND server.

  2. Manually add NS records for the missing names.

  3. Update the start-of-authority (SOA) records by incrementing the serial number.

  4. Restart the BIND server.

Chapter 7. Using DNS to Balance Work Load

This chapter describes how to use DNS to balance the network traffic on a multihomed host or on network servers when you have multiple systems providing the same network service.

TCP/IP Services provides two methods for balancing work load using DNS:
  • Load sharing using the default DNS method of round-robin scheduling.

  • Load balancing using the TCP/IP Services load broker. Load broker is a configurable, calculated, load-balancing mechanism for distributing the work load among DNS cluster members.

This chapter discusses how to use DNS to balance server work load and includes the following topics:

7.1. DNS Clusters

TCP/IP Services defines the term DNS cluster to refer to several A resource records for a single host name. This could be the A resource records for a multihomed host or the A resource records for one or more servers which are to share a work load.

7.2. Round-Robin Scheduling

Round-robin (or cyclic) scheduling is the default load-sharing method used by a DNS server. If multiple resource records satisfy a query, the BIND server returns them each time in a round-robin order. The round-robin scheme is a simple rotation where client requests are passed from one cluster member to the next. The round-robin scheme is also useful for MX records to share mail loads among multiple equivalent gateways of the same MX preference.

Unlike the traditional load-balancing method, round-robin does not take into account the current work load on the DNS cluster members and does not know whether these hosts are up or down.

The following example demonstrates how round-robin load sharing works.

In the example, the DNS cluster alias is defined as robin. When the DNS server receives queries for robin, it shuffles the A resource records in a round-robin manner.
; 
; TCP/IP DNS cluster load sharing - round robin method
;    DNS cluster alias:   "robin" 
robin                           IN      A       9.20.208.47
                                IN      A       9.20.208.30
                                IN      A       9.20.208.72
;
birdy                           IN      A       9.20.208.47
seagull                         IN      A       9.20.208.30
owl                             IN      A       9.20.208.72
;
A user enters the TELNET command, specifying the DNS cluster alias ROBIN. The first query to the DNS name server results in the following TELNET session:
$ TELNET ROBIN
%TELNET-I-TRYING, Trying ... 9.20.208.47
%TELNET-I-SESSION, Session 01, host birdy, port 23
-TELNET-I-ESCAPE, Escape character is ^]

The TELNET client connects to host birdy at IP address 9.20.208.47, the first resource record in the list.

The second query to the name server results in the following TELNET session:
$ TELNET ROBIN
%TELNET-I-TRYING, Trying ... 9.20.208.30
%TELNET-I-SESSION, Session 01, host seagull, port 23
-TELNET-I-ESCAPE, Escape character is ^]

The TELNET client connects to host seagull at IP address 9.20.208.30, the next resource record in the list.

The third query to the name server results in the following TELNET session:
$ TELNET ROBIN
%TELNET-I-TRYING, Trying ... 9.20.208.72
%TELNET-I-SESSION, Session 01, host owl, port 23
-TELNET-I-ESCAPE, Escape character is ^]

TELNET connects to host owl at IP address 9.20.208.72, the next resource record in the list.

The fourth query to the name server results in the following TELNET session:
$ TELNET ROBIN
%TELNET-I-TRYING, Trying ... 9.20.208.47
%TELNET-I-SESSION, Session 01, host birdy, port 23
-TELNET-I-ESCAPE, Escape character is ^]

TELNET again connects to host birdy at IP address 9.20.208.47. This is the start of the cycle repeating. The cycle repeats for the subsequent queries.

The SHOW HOST display for this DNS name server shows the shuffling effect in greater detail. Notice that the output displays the cluster alias name for each host involved in round-robin scheduling.
TCPIP> SHOW HOST ROBIN 
     BIND database

Server:   9.20.208.72 owl.ucx.ern.sea.com

Host address    Host name

9.20.208.47 robin.ucx.ern.sea.com 
9.20.208.30 robin.ucx.ern.sea.com 
9.20.208.72 robin.ucx.ern.sea.com 

TCPIP> SHOW HOST ROBIN 
     BIND database

Server:   9.20.208.72 owl.ucx.ern.sea.com

Host address    Host name

9.20.208.30 robin.ucx.ern.sea.com 
9.20.208.72 robin.ucx.ern.sea.com 
9.20.208.47 robin.ucx.ern.sea.com 

TCPIP>  SHOW HOST ROBIN 
     BIND database

Server:   9.20.208.72 owl.ucx.ern.sea.com

Host address    Host name

9.20.208.72 robin.ucx.ern.sea.com 
9.20.208.47 robin.ucx.ern.sea.com 
9.20.208.30 robin.ucx.ern.sea.com 

TCPIP> SHOW HOST ROBIN 
     BIND database

Server:   9.20.208.72 owl.ucx.ern.sea.com

Host address    Host name

9.20.208.47 robin.ucx.ern.sea.com 
9.20.208.30 robin.ucx.ern.sea.com 
9.20.208.72 robin.ucx.ern.sea.com

BIND Version 9 uses random cyclic scheduling, in which the server randomly chooses a starting point in the RRset and returns the records in order starting at that point, wrapping around the end of the RRset if necessary.

7.2.1. Disabling Round-Robin Scheduling

BIND Version 9 does not allow you to disable round-robin scheduling.

7.3. Load Broker Concepts

TCP/IP Services provides a configurable, calculated, load-balancing mechanism called the load broker for distributing the load across systems in a DNS cluster.

Unlike round-robin scheduling (the default method used by most DNS name servers), the load broker takes into account the load on all DNS cluster participants. The load broker polls DNS cluster members and updates the DNS namespace accordingly.

7.3.1. How the Load Broker Works

When the load broker starts, it reads its configuration file and starts polling DNS cluster members. The load broker exchanges messages with DNS cluster members that run the metric server. The metric server (Section 7.3.3) calculates the current rating and reports it when polled by the load broker. Periodically, the load broker sorts the list of addresses based on metric rating reports, drops the systems that are not responding after being polled three times, and takes a subset of the list and compares it to the name server information. To do the comparison, the load broker sends a host lookup request to the specified name server. If the lists are the same, the load broker does not make any change. If the lists are different, the load broker updates the name server data by sending a dynamic update request to the specified name server.

The name server uses round-robin scheduling to further balance the load across the members of a DNS cluster. So every consecutive request for translating the DNS cluster name results in a list being returned, rotated by one.

The dns-ttl value stored in the load broker configuration file governs how long the record is to be cached by other name servers. If some intermediate name server caches the "A" resource records for a given DNS cluster name, it caches it for the period of time defined by the dns-ttl value. The default dns-ttl value is 45 seconds. If less time is required, you can set dns-ttl to a smaller value. To suppress any caching, you can set the dns-ttl to 0.

The dns-refresh time specifies how often the DNS information for a given DNS cluster is refreshed. The default is 30 seconds. The minimum is 10 seconds. If you want to quickly pick up changes in the system load (reported by metric servers), set dns-refresh to a smaller number.

If the load broker has not received a response from a metric server after being polled three times (one polling interval and two 5-second retry intervals), the load broker marks the address for removal from the DNS alias. This removal will occur at the next dns-refresh interval.

For earliest possible detection of this failure, the polling-interval should be set to a value that is less than one-third of the value specified as the dns-refresh period.
       polling-interval  < (dns-refresh) / 3

The masters list specifies the authoritative name servers to which queries will be sent. Only one name server at a time is sent a query. A query is sent to the first name server specified. If that name server does not respond to the query, then the query is sent to the next name server specified. This process continues until either a name server responds or the list is exhausted. Note that the name servers specified in the masters statement are not necessarily the servers that will be sent dynamic updates.

Queries are sent for the following reasons:
  • A query for A resource records is sent to the name server to obtain the list of addresses associated with the load broker cluster name that is to be updated. The load broker can then perform its comparison to determine whether any updates need to be made.

  • A query for the SOA resource record is sent to the name server so that the load broker can determine the primary master name server for the zone. The primary master name server is then sorted to the top of the name server list that will be sent dynamic update requests.

  • A query for NS resource records is sent to the name server to retrieve the list of name servers that will receive dynamic updates. Dynamic updates are sent to only one server at a time. A dynamic update is sent to the first server on the list. If that name server does not respond, or rejects the dynamic update, then the dynamic update is sent to the next server on the list. This process continues until either the dynamic update is accepted by the name server or the name server list is exhausted.

The name server must be set up to allow dynamic updates from the system that runs the load broker. For information about configuring dynamic updates, see Section 6.4.7.

TCP/IP Services supports dynamic updating of only one master server in a DNS cluster environment.

7.3.2. Managing the Load Broker in an OpenVMS Cluster

By default, you can run the load broker on multiple systems in an OpenVMS Cluster. This is accomplished through a locking mechanism. The first load broker process to start in the cluster obtains the lock. Any load broker processes started afterward go into a standby state and wait for the lock to be released. If the system running the first load broker process goes down, the load broker process releases the lock, allowing the next available standby load broker process to obtain the lock. This system then runs the active load broker process; additional servers remain on standby.

To disable the clusterwide load broker locking mechanism, enter the following command:
$ DEFINE /SYSTEM TCPIP$LBROKER_ALLOW_CONCURRENT_SERVERS 1

7.3.3. How the Metric Server Calculates Load

The metric server calculates the current load on a DNS cluster host by using the following equation:
         rating = availability + workload - penalty
In the equation, the variables are calculated by:
  • Availability

    Availability is calculated using the IJOBLIM system parameters and the SDA global reference variable IJOBCNT in the following equation:
        availability = (20*(IJOBLIM-IJOBCNT))/IJOBLIM
  • Workload

    One consideration in the work load calculation is the system manager's estimate of the host's relative CPU power specified by the system logical TCPIP$METRIC_CPU_RATING.

    To set a CPU power value, use the DCL command DEFINE to define the system logical name TCPIP$METRIC_CPU_RATING with a value. The CPU rating value can range from 1 (the lowest CPU power) to 100 (the highest CPU power). If a value is specified, the value is used instead of the term (min(235,IJOBLIM) in the following equation.
        workload = (min(235,IJOBLIM)*100)/(100+load_average)

    When you set the logical value to 0, or if you do not define TCPIP$METRIC_CPU_RATING, the metric server uses the value of the system parameter IJOBLIM to calculate work load.

    load_average is an average of the current CPU load taken every second. It is calculated by using 97.9% of the previous CPU load and 2.1% of the current CPU load value.

  • Penalty

    The metric server uses the FREEGOAL system parameter and the SDA global reference variable FREECNT to calculate an available memory penalty.
        penalty = 40*((FREEGOAL+2048-FREECNT)/(FREEGOAL+2048))

    The value of penalty is subtracted from the rating only if the value is positive. If the value of FREECNT is high enough, the value of penalty is not applied.

7.4. Load Broker Startup and Shutdown

The load broker can be shut down and started independently. This is useful when you change parameters or logical names that require the service to be restarted.

The following files are provided:
  • SYS$STARTUP:TCPIP$LBROKER_STARTUP.COM allows you to start up the load broker service.

  • SYS$STARTUP:TCPIP$LBROKER_SHUTDOWN.COM allows you to shut down the load broker service.

To preserve site-specific parameter settings and commands, create the following files. These files are not overwritten when you reinstall TCP/IP Services:
  • SYS$STARTUP:TCPIP$LBROKER_SYSTARTUP.COM can be used as a repository for site-specific definitions and parameters to be invoked when the load broker is started.

  • SYS$STARTUP:TCPIP$LBROKER_SYSHUTDOWN.COM can be used as a repository for site-specific definitions and parameters to be invoked when the load broker is shut down.

7.5. Configuring the Load Broker

To configure the load broker, edit the file TCPIP$LBROKER_CONF.TEMPLATE located in SYS$SYSDEVICE:[TCPIP$LD_BKR], then rename the file to TCPIP$LBROKER.CONF.

After making changes to TCPIP$LBROKER.CONF, restart the load broker by running TCPIP$CONFIG, or by using the shutdown and startup procedures.

The load broker configuration file can contain one or more DNS cluster statements in the following format:
cluster "clustername.domain.com" 
{

 [dns-ttl nn;]
 [dns-refresh nn;]
 masters {ip_address};
 [polling-interval nn;]
 [max-members nn;]
 members {ip_address};
 failover {ip_address};
 [ keys { string; [ string; [...]] }; ]

};
Table 7.1 describes the valid cluster statements.
Table 7.1. Valid Cluster Statements

Statement

Description

members

Specifies the IP address for each DNS cluster member.

failover

Specifies the address of the host to use if all other members are down.

masters

Specifies the IP addresses of authoritative name servers.

dns-ttl

Specifies the time to live for a given record. The value you provide governs how long the record is to be cached by other name servers. If some intermediate name servers cache A resource records for a given DNS cluster name, they cache it for the period specified by dns-ttl for the resource record. The default value is 45 seconds.

dns-refresh

Specifies how often the DNS information for a given DNS cluster name is refreshed. The default is 30 seconds. The minimum is 10 seconds. The value of this field should be set relative to the value of polling-interval. The dns-refresh value should be smaller than the polling-interval value. It is unproductive to refresh more often then you poll.

polling-interval

Specifies the length of time between polls to cluster members. The default is 30 seconds. The minimum is 5 seconds.

keys

Specifies a key_id defined by the key ("key" in different font) statement, to be used for transaction security (TSIG) when talking to a remote DNS server. The key statement must come before the cluster statement that references it. When a request is sent to the remote server, a request signature is generated using the key specified here and appended to the message.

max-members

Specifies the maximum number of IP addresses to be returned to the name server in each dynamic update. For effective load balancing, this number should be between one-third and one-half the number of participating DNS cluster members.

The following sample is a configuration of the load broker that load balances the DNS cluster named WWW.TCPIP.ERN.SEA.COM.
cluster "www.tcpip.ern.sea.com"
{
        dns-ttl                 45;
        dns-refresh             30;
        masters {
                 9.20.208.53;
        };
        polling-interval         9;
        max-members              3;
        members {
                9.20.208.100;  
                9.20.208.53;
                9.20.208.54;
                9.20.208.80;
                9.20.208.129;
                9.20.208.130;
        };
        failover 9.20.208.200;
};
To retain your UCX Version 4. x DNS cluster load-balancing configuration:
  1. Enter the CONVERT/CONFIGURATION BIND/CLUSTER command, as shown in the following example:
    TCPIP> CONVERT/CONFIGURATION BIND -
    _TCPIP> /CLUSTER=SYS$SYSDEVICE:[TCPIP$LD_BKR]TCPIP$LBROKER.CONF

    The output from this command is a TCPIP$LBROKER.CONF file containing your basic configuration.

  2. Edit the TCPIP$LBROKER.CONF file to produce a complete configuration file.

7.5.1. Configuring the Load Broker with TSIG

This section describes how to set up Transaction Signatures (TSIG) security in the Load Broker. TSIG provides authentication and data integrity between the Load Broker and the DNS server. To use TSIG, configuration must occur on the Load Broker and on the DNS server. For more information on configuring the BIND/DNS server, see Section 6.2.3.

TSIG requires the definition of a key in the Load Broker configuration file TCPIP$LBROKER.CONF. The following example shows the format of the key statement:
key key_id {
    algorithm algorithm-id;
    secret secret-string;
};
Table 6.3 describes the elements of the key statement.
Table 7.2. Key Statement Elements

Element

Description

key_id

Specifies a domain name that uniquely identifies the key (also known as the key name). It can be used in a cluster statement to cause requests sent to the DNS server to be signed with this key.

algorithm-id

Specifies an authentication algorithm. The only algorithm currently supported with TSIG authentication is HMAC-MD5.

secret-string

Specifies the secret to be used by the algorithm; treated as a Base-64 encoded string.

7.5.1.1. Configuring the Load Broker to Use TSIG

To configure the Load Broker to use TSIG, perform the following steps:
  1. Generate the secret-string that will be used in the key statement on the Load Broker and the DNS server. The key name must be the same on both.

    Longer keys are better, but shorter keys are easier to read. The maximum key length is 512 bits. Use the dnssec-keygen utility to generate keys automatically.

    The following command generates a 128-bit (16-byte) HMAC-MD5 key:

    $ dnssec_keygen -a hmac-md5 -b 128 -n HOST host1-host2

    In this example, the key is in the files KHOST1-HOST2.157-00000_PRIVATE and KHOST1-HOST2.157-00000_KEY. Nothing uses these files directly, but the base-64 encoded string following Key: (in different font) can be extracted from either file and can be used as a shared secret. For example:

    Key: La/E5CjG9O+osljq0a2jdA==

    The string La/E5CjG9O+osljq0a2jdA== can be used as the shared secret.

    Keys can also be specified manually. The shared secret is a random sequence of bits, encoded in base-64. Most ASCII strings are valid base-64 strings (assuming the length is a multiple of 4 and that only valid characters are used).

  2. Inform the Load Broker of the key's existence. Add the following to TCPIP$LBROKER.CONF:

    key host1-host2 {
        algorithm hmac-md5;
        secret "La/E5CjG9O+osljq0a2jdA==";
    };
  3. Instruct the Load Broker to use the key. Add a keys statement to the cluster (in different font) statement in TCPIP$LBROKER.CONF:

    cluster "cluster1.sample.hp.com." {
            masters {
                    1.2.3.4;
            };
            dns-refresh        60;
            polling-interval   30;
            max-members     2;
            keys { host1-host2; };
            members {
                    1.2.3.5;
                    1.2.3.6;
                    1.2.3.7;
            };
    };
    
    

    Multiple keys may be specified and used.

  4. On the DNS server that is authoritative for the zone, add a matching key statement to the configuration file. For TCP/IP Services BIND, the key will be added to TCPIP$BIND.CONF.

    Add an allow-update sub-statement to the zone statement in the BIND configuration file for the zone that the Load Broker will be updating, specifying the key name. The zone should be a "master" zone.

    See Chapter 6 for more information.

  5. Restart the Load Broker.

    The DNS server will now authenticate Dynamic Update requests from the Load Broker based on the shared key.


Note

You must enter the Key's description before the cluster statement, as shown in the following example:
# DESCRIPTION:
#
#   This file contains configuration information for the LBROKER  server.
#   Before starting the LBROKER server, you must edit this file and  copy
#   it to SYS$SYSDEVICE:[TCPIP$LD_BKR]TCPIP$LBROKER.CONF.
#
#   Refer  to  the  HP TCP/IP Services for OpenVMS Management  guide  for
#   instructions on editing and using this file.

key oak {
        algorithm "hmac-md5";
        secret "Bj1xjGUTkzclXQ6aT/UGoA==";
};

cluster "timber.sqa.tcpip.zko.hp.com."
{
  masters {
        16.116.93.66;
  };
  dns-ttl               43200;
  dns-refresh           30;
  polling-interval       5;
  max-members  4;
  keys { oak; };
  members {
        16.116.93.67;
        16.116.93.68;
        16.116.93.69;
        16.116.93.70;
  };
  failover 16.116.93.68;
};

7.5.2. Enabling the Load Broker

To enable DNS cluster load balancing, complete the following tasks:
  1. Ensure that all hosts in the DNS cluster are running TCP/IP Services.

  2. Configure the load broker (see Section 7.5).

  3. Configure the primary master name server that is authoritative for the zone containing the DNS cluster resource record to allow dynamic updates from the host on which the load broker is running. For information about configuring dynamic updates, see Section 6.4.7.

    You can also configure the master name server with the allow-update-forwarding option, so that slave servers that are sent dynamic updates will forward them to the master name server. For more information, see Table 6.21.

  4. Ensure TCP/IP connectivity between the DNS cluster members and the load broker.

  5. Enable the metric server on each member of the DNS cluster:
    1. Run the following command procedure:
      $ @SYS$MANAGER:TCPIP$CONFIG
    2. On the TCPIP$CONFIG Server Components Configuration menu, select option 8:
      8 – METRIC.
    3. On the Metric configuration display, select option 2:
      2 – Start service on this node.
Review the following guidelines:
  • DNS cluster hosts and clients are not required to be on the same bridged LAN.

  • The number of DNS cluster member hosts is limited to 32.

  • A BIND name server can also be a DNS cluster member host.

  • The authoritative name server can run any BIND name server that supports BIND 8.1.1 or later or that supports dynamic updates.

7.5.3. Load Broker Logical Names

Table 7.3 describes the load broker's logical names. Define these logical names with the /SYSTEM qualifier, and restart the load broker server to make the changes take effect.
Table 7.3. Load Broker Logical Names

Logical Name

Description

TCPIP$LBROKER_LOG_LEVEL value

Turns on diagnostics and writes them to the TCPIP$LBROKER_RUN.LOG located in SYS$SYSDEVICE:[TCPIP$LD_BKR]. Valid values are 1 and 2 (2 provides more detailed diagnostics).

TCPIP$LBROKER_ALLOW_CONCURRENT_SERVERS

Turns off the clusterwide load-broker locking mechanism, allowing separate load broker processes to run on each node in the OpenVMS Cluster.

To disable the clusterwide load-broker locking mechanism, enter the following command:

$ DEFINE /SYSTEM TCPIP$LBROKER_ALLOW_CONCURRENT_SERVERS 1

When you define this logical and then start the load broker, multiple load brokers in an OpenVMS Cluster will be active. For more information, refer to Section 7.3.2.

7.5.4. Metric Server Logical Names

Table 7.4 describes the metric server's logical names. Define these logical names with the /SYSTEM qualifier. The metric server detects the change and dynamically updates the current environment.
Table 7.4. Metric Server Logical Names

Logical Name

Description

TCPIP$METRIC_CPU_RATING value

Sets a bias value that represents your estimate of the relative CPU power. Valid values range from 1 (lowest CPU power) to 100 (highest CPU power). Use a value of 0 (zero) to specify the default (The value of the system parameter IJOBLIM is used).

TCPIP$METRIC_COMPUTE_INTERVAL value

Specifies how often the metric server computes the rating. Valid value (in seconds) is a number from 1 to 300. The default is 10 seconds.

TCPIP$METRIC_LOG_LEVEL value

Turns on diagnostics logged to the file TCPIP$METRIC_RUN.LOG located in SYS$SPECIFIC:[TCPIP$METRIC]. Valid values are 1 or 2 (2 provides more detailed diagnostics).

7.6. Metric Server Startup and Shutdown

The metric server starts up automatically at system startup time if the service was previously enabled and can be shut down and started independently.

The following files are provided:
  • SYS$STARTUP:TCPIP$METRIC_STARTUP.COM allows you to start up the metric service.

  • SYS$STARTUP:TCPIP$METRIC_SHUTDOWN.COM allows you to shut down the metric service.

To preserve site-specific parameter settings and commands, create the following files. These files are not overwritten when you reinstall TCP/IP Services:
  • SYS$STARTUP:TCPIP$METRIC_SYSTARTUP.COM can be used as a repository for site-specific definitions and parameters to be invoked when the metric service is started.

  • SYS$STARTUP:TCPIP$METRIC_SYSHUTDOWN.COM can be used as a repository for site-specific definitions and parameters to be invoked when the metric service is shut down.

7.7. Solving Load Broker Problems

TCP/IP Services provides the following tools to assist in solving load broker problems:
  • The metricview utility, to display metric information regarding DNS cluster members.

  • Diagnostic log files.

7.7.1. Metricview Utility

The metricview utility is used to read the metric ratings. It displays the metric rating of the member hosts in the TCP/IP DNS cluster.

To run the metricview utility, enter the following commands
$ @SYS$STARTUP:TCPIP$DEFINE_COMMANDS.COM
$ metricview 
Host                                                    Rating
----                                                    ------
10.10.2.11      rufus.lkg.dec.com                         47
10.10.2.255     peach.lkg.dec.com                         51
Optionally, you can direct the metricview query to a specific host by including the /HOST qualifier on the command. For example:
/HOST=hostname

Only the specified host will be queried. If the host is multihomed, it will send replies out over each interface, resulting in a separate metricview display line for each interface. Note that the metric rating is calculated on a per-host basis, so the ratings will be the same for each interface of a multihomed host.

7.7.2. Viewing Diagnostic Messages

If you define the logical name TCPIP$METRIC_LOG_LEVEL, the metric server writes diagnostic messages to the TCPIP$METRIC_RUN.LOG file. If you experience problems with the metric server, define TCPIP$METRIC_LOG_LEVEL and, after a period of operation, review the messages in the TCPIP$METRIC_RUN.LOG file for an indication of what the problem could be. See Section 7.5.4 for a description of the logical name.

Chapter 8. Configuring and Managing BOOTP

The Bootstrap Protocol (BOOTP) server answers network bootstrap requests from diskless workstations and other network devices such as routers, terminal servers, and network switching equipment. When it receives such a request, the BOOTP server looks up the client's address in the BOOTP database file.

The Trivial File Transfer Protocol (TFTP) handles the file transfer from a TFTP server to a diskless client or other remote system. The client initiates the file transfer. TFTP is described in Chapter 9.

Because BOOTP is a subset of DHCP, you cannot enable both BOOTP and DHCP on the same host.

This chapter reviews key concepts and describes:

8.1. Key Concepts

The BOOTP server answers client requests for diskless client configuration by sending address and file name information to the client. When the client receives this information from the BOOTP server, it initiates a file transfer using the TFTP protocol.

The BOOTP server performs the following steps to accomplish a bootstrap:
  1. The BOOTP server receives a configuration request from a client. A broadcast request goes out to all potential servers on the subnetwork or is directed to a predetermined known server address.

  2. The BOOTP server reads information in the BOOTP database to get information about the client. The identity of the client is based on the network hardware address contained in the request.

  3. BOOTP identifies the network client.

  4. BOOTP constructs a response that contains all of the information in the BOOTP database for that client. The client information in the database includes:
    • Client's IP address

    • Client's host name (usually)

    • Name and size of the client's system load file

    • IP address of the TFTP server storing this file

    • IP addresses of the hosts offering common network services, such as a log server or a print (LPD) server

  5. When the client receives the configuration information in the BOOTP response, it sends a request to the TFTP server host named in the response. This request is necessary only if the client must retrieve the load file.

  6. If the client sends a read request (RRQ) to the TFTP server, the TFTP server attempts to locate this file. If it finds the file, the server transfers it to the client.

8.2. BOOTP Planning and Preconfiguration Tasks

When planning BOOTP, you need to make decisions about the network configuration and the local BOOTP service.

8.2.1. Network Configuration Decisions

Before you start to set up BOOTP, answer the following questions:
  • What clients will access the BOOTP server? For each client, obtain the following information:
    • System image and location from where it can be copied

    • Additional information requested

    • Hardware address

    • IP address

  • What hosts in your network will run the BOOTP server?

  • Will gateways be used for downloading? Gateways let you specify a specific path for the data transfer.

  • Do you want to limit client access to specific server directories?

8.2.2. BOOTP Service Decisions

Before you start to configure BOOTP, consider the following:
  • Default priority for the TCPIP$BOOTP server account in the user authorization file (UAF)

    For optimal performance, use the default priority level for the TCPIP$BOOTP user account.

    In a large or active subnetwork, clients might generate several broadcast requests per minute. The server continues to process all incoming requests, even those for which it lacks information in its database.

    In most cases, all this processing does not create system performance problems. However, it does use, perhaps unnecessarily, system resources. A different network configuration might avoid wasted system overhead.

  • Segmented subnetworks

    To reduce large volumes of BOOTP request traffic to a specific server, segment very large subnetworks with filtering bridges.

    If you configure multiple servers, each server competes to provide the requested configuration information. For efficient use of each server, partition the database with a subset of the overall client population designated to each server.

  • Separate directory for each client

    To avoid writing over the same file name with configuration information from multiple clients, create a separate subdirectory for each client in the TCPIP$TFTP_ROOT directory tree.

    Some BOOTP clients, such as routers and terminal servers, can store configuration options on the BOOTP server host. In a network with two or more of these clients, the clients can use the same file name to store the configuration information with TFTP.

  • Security needs

    Identify your system's security needs (see Section 8.2.3).

8.2.3. BOOTP Security</