Updated: 24 May 2001

DECnet-Plus

Order Number: AA-Q190F-TE

This manual describes the syntax and features of the Network Control Language (NCL) and the NCL commands used for network management modules.

Revision/Update Information: This manual supersedes the DECnet-Plus Network Control Language Reference Guide.

Operating Systems: OpenVMS VAX Version 7.1
OpenVMS Alpha Version 7.1
DIGITAL UNIX Version 4.0

Software Versions: DECnet-Plus for OpenVMS Version 7.1
DECnet/OSI for DIGITAL UNIX Version 4.0

Digital Equipment Corporation Maynard, Massachusetts

Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from DIGITAL or an authorized sublicensor.

DIGITAL conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

© Digital Equipment Corporation 1996. All rights reserved.

The following are trademarks of Digital Equipment Corporation: Bookreader, DDCMP, DEC, DECdirect, DECnet, DECNIS, DECserver, DECsystem, DECwindows, DIGITAL, DNA, InfoServer, OpenVMS, PATHWORKS, ULTRIX, VAX, VAX DOCUMENT, VAXcluster, VAXstation, VMS, VMScluster, and the DIGITAL logo.

The following are third-party trademarks:

Macintosh is a registered trademark of Apple Computer, Inc.
Microsoft, MS, and MS--DOS are registered trademarks of Microsoft Corporation.
MS-DOS is a registered trademark of Microsoft Corporation.
Motif, OSF, OSF/1, OSF/Motif, and Open Software Foundation are registered trademarks of the Open Software Foundation, Inc.
OS/2 is a registered trademark of International Business Machines Corporation.
OSF/1 is a registered trademark of Open Software Foundation, Inc.
OSI is a registered trademark of CA Management, Inc.
PATHways is a registered trademark of The Wollongong Group.
SCO is a trademark of Santa Cruz Operations, Inc.
TCPware is a registered trademark of Process Software Corporation.
UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Ltd.

All other trademarks and registered trademarks are the property of their respective holders.

This document was prepared using VAX DOCUMENT, Version V3.2m.

Contents

Index

This book describes the syntax and features of the Network Control Language (NCL), and the NCL commands that you use for network management modules. DECnet-Plus networking software works with systems running DIGITAL UNIX and OpenVMS software and conforms to the DIGITAL Network Architecture (DNA). DNA, the model for all DECnet implementations, allows all DIGITAL operating systems to participate in the same network.

Intended Audience

This multiplatform book is written for network managers responsible for managing DECnet-Plus for OpenVMS and DECnet-Plus for DIGITAL UNIX networks.

Document Structure

This book has two parts:

Part I	Provides an overview of the functions provided by NCL.
Part II	Describes the NCL commands and related information. There is a separate chapter for every NCL module and each chapter contains a comprehensive description of each entity belonging to that module.

Common data types, common exceptions, and NCL error messages are described in the appendixes.

Related Documents

For a list of additional documents that are available in support of this version of the operating system, refer to the DECnet-Plus for OpenVMS Introduction and User's Guide or the DECnet-PLUS for DIGITAL UNIX Introduction and User's Guide.

For additional information the DECnet-Plus products and services, access the DIGITAL OpenVMS World Wide Web site. Use the following URL:

http://www.openvms.digital.com

Reader's Comments

DIGITAL welcomes your comments on this manual or any of the DECnet-Plus documents. Send us your comments through any of the following channels:

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

Terminology

An adjacent node is a node connected to the local node by a single physical line.

These terms are used interchangeably:

• Transition and migration
• Phase IV and DECnet Phase IV
• Phase V and DECnet Phase V
• End system and end node
• Intermediate system and router
• Running database and operational database
• Sink node and logging node

How To Order Additional Documentation

Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

The following conventions apply to this book.

Acronyms

The following acronyms are used throughout this book:

ACSE	Association Control Service Element
ASE	application service element
ASN.1	Abstract Syntax Notation One
BER	basic encoding rules
CMIP	Common Management Information Protocol
CML	CMIP Management Listener
DAP	Data Access Protocol
DCS	defined context set
DDCMP	DIGITAL Data Communications Message Protocol
DECdns	DIGITAL Distributed Name Service
DNA	DIGITAL Network Architecture
DTR	DECnet Test Receiver
DTS	DECnet Test Sender
ES--IS	end system to intermediate system protocol
EVL	Event Dispatcher
EVL	event logger
FAL	file access listener
FTAM	File Transfer, Access, and Management
HDLC	High-Level Data Link Control
MIR	loopback mirror
MOP	Maintenance Operations Protocol
NSAP	network service access point
NCL	Network Control Language
NSP	Network Services Protocol
OSI	Open Systems Interconnection
OSUL	Open Systems Upper Layer
PCI	protocol control information
PDU	protocol data unit
PPCI	presentation protocol control information
PSDN	packet switching data network
SPCI	Session Protocol Control Information
SPDU	session protocol data unit
SSDU	session service data unit
TCP/IP	Transmission Control Protocol/Internet Protocol
TPDU	transport protocol data unit
TSDU	transport service data unit

This reference guide describes how to use the Network Control Language (NCL) command line interface on DECnet-Plus for DIGITAL UNIX and DECnet-Plus for OpenVMS nodes. You should be familiar with the concepts and terminology of the entity model of network management, as described in the network management guide for your operating system.

This chapter tells you how to use NCL in the following ways:

• Invoke, use, and exit the Network Control Language
• Issue NCL commands from your terminal
• Define common data types for NCL
• Interpret NCL error messages

DECnet-Plus for OpenVMS uses OpenVMS rights identifiers to check access on all manageable entities. This differs from the Phase IV software, which used OpenVMS privileges for access to the permanent database and for write access. Read access to the volatile database in Phase IV was unprotected.

1.1.1 Access to Local Network Data

In DECnet-Plus for OpenVMS, the rights identifier NET$EXAMINE grants a user read access to the network configuration data. The NET$MANAGE rights identifier grants read and write access to the network configuration data, and NET$SECURITY grants ability to set default accounts. These new rights allow the network manager to restrict access to network parameters. Access is granted to an individual user by means of the Authorize utility on OpenVMS. The following command examples grant access:

UAF> grant/id net$examine Joe ! Grant user Joe read access to local network data

UAF> grant/id net$manage Joe ! Grant user Joe read/write access to local network data

UAF> grant/id net$security Joe ! Grant user Joe ability to set default accounts

In lieu of NET$MANAGE rights, the BYPASS privilege grants read and write access.

When issuing NCL commands to the local node (for example, NCL SHOW ALL or NCL SHOW NODE 0 ALL), the rights of the executing process determine whether access is granted.<>

In DIGITAL UNIX, access control policy is as follows:

• Any user is allowed to use the show command.
• To execute any command that modifies network data, the user must have superuser privileges.
• When commands default to the local node (either by not specifying a node, or using Node 0), NCL communicates with the CMIP Management Listener (CML) application by way of pipes, and the privileges are determined by the unique identification (UID) that NCL is running under.
• When commands are issued to a remote node or to the local node by explicitly including the node name (for example, using node alpha on the system named alpha), then the access granted depends on the access control provided; the Session Control attributes defined for CML on the target node; and the proxy accounts set up on the target node.
• The access control used with a command is determined as follows:
  • If any explicit access control is included on the command line, that is what is used. You can provide the information either after the node name (for example, node alpha/smith/abc) or with a by clause (for example, by user = smith, password = abc).
  • If no explicit access control is provided, then NCL checks if any default access has been set previously, and if so, uses that. Default access is set using the set ncl default access by user = USER, password = PASSWORD command. You can check the current state of NCL's default access with the show ncl default access command.
  • If neither of the these cases applies, no access information is used.
• When an NCL command arrives at a target node, the access control accompanying the command, along with the Session Control proxy entries and Session Control application cml characteristics determine what will be allowed. By default (as DECnet is initially installed), all show commands are allowed, and commands that alter network data are allowed only if the root account and password are provided explicitly. To modify this behavior, refer to the appropriate manual entries on session control.<>

When issuing NCL commands to the remote node (for example, NCL SHOW NODE remote-node-name ALL or NCL SET NCL DEFAULT ENTITY NODE remote-node-name), a connection is established to the CML application on the remote node. Access checks performed on the remote node are dependent on the account the remote CML application is running in (on an OpenVMS node). When the connection comes into an OpenVMS machine, a process is created to run the CML application. The account used is determined in the following order:

1. If explicit access control is specified, the specified account is used.
2. If there is a default account for the application receiving the request, it is used.
3. If a proxy account is specified, or there is a default proxy account for the remote user, it is used.
4. If none of the above are specified, the session entity is checked for a default nonprivileged account to use.

If the account that runs the CML application does not have the NET$EXAMINE for read access, or NET$MANAGE identifier for read and write access, then the access is denied by the management agent.

The manager of the remote node must take explicit action to allow an individual user access to the network configuration information. For example:

• Run the Authorize utility and grant an account the proper rights
• Run Authorize and create a proxy account and grant the proxy account the proper rights
• Determine the user name associated with the SESSION CONTROL APPLICATION CML. Run the Authorize utility to ensure that that account has NET$EXAMINE for read-only access.

The last option is one of the selections offered by NET$CONFIGURE when configuring the application database. If you select a default account for the CML application, NET$CONFIGURE grants NET$EXAMINE right to that account by default.

1.2 Network Management Graphical User Interface

You can access NCL through either a command line interface or graphical user interface (GUI). The GUI allows network managers to view the status of network components and control those components from a Motif-based window interface located at:

• sys$system:net$mgmt.exe (NET$MGMT) --- for OpenVMS
• dna_mgmt --- for DIGITAL UNIX

This utility provides a hierarchical graphical approach to the management of DECnet-Plus. The manageable components of DECnet-Plus (modules, entities, and subentities) are represented in a tree-like structure below the icon that represents the node you are managing. This provides an easy way to familiarize yourself with the organization of these manageable entities. If you choose to enable the displaying of NCL commands from the Default Actions pull-down menu, this utility can also help familiarize you with NCL syntax.

In addition to issuing NCL commands on your behalf, NCL GUI can also perform task-oriented functions that involve many NCL commands or are complex in some way. The currently supported NCL GUI tasks are:

• show known links
• show known node counters
• check transports

The same rights required to run NCL are also required to run this utility.

For further information, refer to the network management guide for your operating system.

1.3 Getting Started with NCL

You can issue NCL commands from a terminal or from a command file. You can use NCL to manage network entities on local and remote nodes. If you are familiar with Phase IV network management and the Network Control Program (NCP), you can use the decnet_migrate utility as an option to map NCP commands to their NCL equivalents. See the network management guide your operating system for further details.

1.3.1 Invoking NCL (DIGITAL UNIX)

There are several ways to invoke the interactive NCL utility:

1. Enter ncl at the shell prompt. The NCL prompt appears:

   % ncl Return ncl>

2. Enter an NCL command line.

   % ncl any ncl command Return

   
   After the command executes, you return to the shell.

3. Redirect a command script into NCL.

   % ncl <scripta

   
   where scripta is the name of a script that contains a sequence of NCL commands.

4. Execute a shell script containing NCL commands. Your shell script can use the exit status returned by NCL commands.

   % ncl_filename

   
   The following C shell script demonstrates this:

   #!/bin/csh ncl show routing circuit circuit-1 all attributes if ( $status != 0 ) then echo "" echo "This ncl command failed." echo "" endif

   
   This sample script uses the exit status from an NCL command to determine whether or not to echo a message. If the command fails, the shell script echoes the message.

Other NCL operations include:

• To abort an NCL operation, press Ctrl/C.
• To continue a long command to the next line, use a hyphen as the last character in the line. The _ncl> prompt is displayed on continuation lines:

  ncl> set node moosie routing manual network entity titles - _ncl> { 49::00-0c:08-00-2b-12-34-56:00, - _ncl> 49::00-0c:08-00-2b-12-34-57:00 }

• To include comments in NCL shell scripts or as part of a command line in the interactive utility, use the exclamation point (!) or pound sign (#) character. NCL ignores hyphens within and at the end of a comment line.
• To exit from NCL, type exit, quit, or press Ctrl/D at the ncl> prompt.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6500PRO.HTML