Keepalive Time = 60 Retransmit Threshold = 5 Congestion Avoidance = False A command that executes appropriately and completes its assigned task produces a Success Response. Success Responses are not documented in the command description sections of this manual unless the Success Response contains arguments or the response indicates that something other than the expected action has occurred. If a command does not complete successfully, you can get one or more exception or error messages. There are three categories of error returns for NCL commands: o OpenVMS NCL error messages; that is, errors that occur at the level where OpenVMS is processing NCL commands. o Common NCL exception messages; that is, errors that occur within NCL and which apply to more than one command. o Command-specific exception messages, which are described with the commands that can produce them. Each command description in this manual includes at least one example that shows a typical successful command with possible resulting output. 3 Displaying_UIDs Any entity that has counters or generates events is assigned a unique identification (UID) value. A UID is a 16-byte entity attribute that is unique throughout the network and for all time; that is, because the creation time of the entity is included as a portion of the UID, no two identical UIDs will ever be created. A UID identifies a unique instance of an entity. For network management, UIDs provide a guaranteed way to track the characteristics and status of that precise entity instance. Each entity having counter attributes also has a creation timestamp identifying, simply, when the entity was created. The UID is included in any response or event from an entity that has a UID. Any entity that generates events or has counters must have a UID, which is also visible as a status attribute. Both the UID and the creation timestamp are included in any event logging report that returns one or more counters in its argument list. By default on Tru64 UNIX, UID values are not displayed. The UID value for an entity is not always needed and can clutter a show display or an event-logging report. Use the enable ncl uid display command if you wish to see this attribute. To turn UID displays back off, type disable ncl uid display. 2 Specifying_Access_Control To set default access control information for a series of NCL commands within a single NCL session (usually to be performed on a remote system), use the SET NCL DEFAULT ACCESS command. Refer to HELP NCL DEFAULT_CONTEXT for more information on the use of that command. To provide access control information to be used for the execution of a single NCL command, you may use one of the following methods: o Use the by prepositional phrase The by prepositional phrase authenticates that an account or proxy account for a particular user has been set up with the proper access control information. Use of the by preposition is portable to other DECnet-Plus systems. Use the following format to append access control information using the by preposition. by user=username, password=password, account=account, - proxy={TRUE/FALSE} For Tru64 UNIX, NCL ignores any use of the by proxy clause so that the modifier "by proxy=true" (i.e., proxy access allowed) is always in effect. If user j_smith has privileges to access the session control application graphics_exchange on the remote node, he can use the by preposition as follows: ncl> ! On node .admin.finance ncl> show node .admin.artists session control application - _ncl> graphics_exchange all counters, by user=j_smith, - _ncl> password=DoNotUse o Specify an access control string The access control string (ACS) consists of a user name and password, for an account on the remote system. For Tru64 UNIX, enter the ACS as part of the node-name specification nodename/usr/password as follows: ncl> show node .admin.artists/j_smith/DoNotUse session control - _ncl> application graphics_exchange all counters You do not need privileges to do a show operation. However, to do a set operation, you need to have superuser access to the system. For OpenVMS: NCL> show node .admin.artists"j_smith DoNotUse" session - _NCL> control application graphics_exchange all counters To do a show operation, you need NET$EXAMINE right on the remote OpenVMS system. For read and write access (for example, set, disable, enable etc.), you need NET$MANAGE right or BYPASS priviledge on the remote system. The use of proxy accounts is a more manageable method of establishing access control schemes between two systems. See the DECnet-Plus Network Management manual for more information about controlling remote network access through the use of proxy accounts, or refer to HELP NETWORK_MANAGEMENT ACCESS_CONTROL PROXIES. For Tru64 UNIX, access control does not have any effect when the NCL command is directed to the local node. This happens because NCL uses interprocess communication instead of DECnet-Plus to communicate with node 0, the local node, and therefore the user's privileges are determined by the user id that NCL is running under. 2 Default_Context When you wish to perform a series of commands on a particular entity (either on your local node or a remote Phase V node), you may choose to set your default NCL context. The SET NCL DEFAULT ENTITY command allows you to specify an entity to be used for further NCL commands. Similarly, the SET NCL DEFAULT ACCESS command allows you to specify access control information. 3 OpenVMS The NET$EXAMINE right is required to issue SET NCL DEFAULT ENTITY and SET NCL DEFAULT ACCESS commands. Refer to HELP NETWORK_MANAGEMENT ACCESS_CONTROL RIGHTS_IDENTIFIERS for information on rights identifiers. Once established, default entity and access control information will remain in effect for the duration of an NCL session until it is modified by subsequent SET NCL DEFAULT commands. When supplying access information, both the username and password should be provided in a single command. Here are a few acceptable forms of the SET NCL DEFAULT command: NCL>SET NCL DEFAULT ENTITY - _NCL>NODE nodename"username password" [subentity|subentities] NCL>SET NCL DEFAULT ENTITY NODE nodename [subentity|subentities],- _NCL>ACCESS BY USER=username, PASSWORD=password NCL>SET NCL DEFAULT ACCESS BY USER=username, PASSWORD=password,- _NCL>ENTITY NODE nodename [subentity|subentities] When a SET NCL DEFAULT command contains new access information but lacks a default node entity, as in: NCL>SET NCL DEFAULT ACCESS BY USER=username, PASSWORD=password NCL>SET NCL DEFAULT ENTITY [subentity|subentities],- _NCL>ACCESS BY USER=username, PASSWORD=password NCL>SET NCL DEFAULT ACCESS BY USER=username, PASSWORD=password,- _NCL>ENTITY [subentity|subentities] then the new access information is stored, but it will not be used until some subsequent SET NCL DEFAULT ENTITY NODE command is issued. In the following example, new access control information is stored: NCL>SHOW NCL DEFAULT No NCL Default Access has been set NCL Default Entity () NCL>SET NCL DEFAULT ACCESS BY USER=user1, PASSWORD=goodpassword NCL>SHOW NCL DEFAULT NCL Default Access by User user1, Password xxx NCL Default Entity () but that access control information remains unused until the default node entity is modified. The following SET command would then result in the establishment of a connection to node remnod using the user1 account: NCL>SET NCL DEFAULT ENTITY NODE remnod NCL>SHOW NCL DEFAULT NCL Default Access by User user1, Password xxx NCL Default Entity Node remnod Once you have set a default node entity, all subsequent SET NCL DEFAULT ENTITY [subentity | subentities] commands apply to that node until the user attempts to modify the default node entity. For example, now that the default node entity is remod, in order to set the default entity to Session Control on node remnod, you can do so without re-specifying the node entity, as in: NCL>SET NCL DEFAULT ENTITY Session Control NCL>SHOW NCL DEFAULT NCL Default Access by User user1, Password xxx NCL Default Entity Node remnod Session Control To change to another subentity on the remote node, you must include (or re-specify) any subentities beneath the node entity. Even though the current default entity in this example is Node remnod Session Control, you must re-specify the Session Control subentity if you want to set default to a lower subentity on that node. In other words, NCL would not parse the following command because the Session Control entity needs to be re-specified. Since the command could not be parsed, the NCL defaults remained unchanged: NCL>SET NCL DEFAULT ENTITY Application fal %NCL-E-INVALIDCOMMAND, unrecognized command SET NCL DEFAULT ENTITY \Application\ fal NCL>SHOW NCL DEFAULT NCL Default Access by User user1, Password xxx NCL Default Entity Node remnod Session Control Instead, this command would be necessary to change the default to a lower subentity on node remnod: NCL>SET NCL DEFAULT ENTITY Session Control Application fal NCL>SHOW NCL DEFAULT NCL Default Access by User user1, Password xxx NCL Default Entity Node remnod Session Control Application fal Note that in the example above the "fal" instance identifier specified a particular instance of a Session Control Application. But it is also acceptable to use wildcards to specify the default entity. In the example below, the wildcard "*" is used as an instance identifier to refer to all session control applications on the default node. NCL>SET NCL DEFAULT ENTITY Session Control Application * NCL>SHOW NCL DEFAULT NCL Default Access by User user1, Password xxx NCL Default Entity Node remnod Session Control Application * If default access control information and the default entity were then modified, but no node entity was specified, as in: NCL>SET NCL DEFAULT ACCESS BY USER=user2, PASSWORD=badpassword, _NCL>ENTITY Session Control NCL>SHOW NCL DEFAULT NCL Default Access by User user2, Password xxx NCL Default Entity Node remnod Session Control Application * The new default access information would be stored, but contrary to the default access information displayed by SHOW NCL DEFAULT, the connection to node remnod through the user1 account will remain in use until the default node entity is changed. This next command would request a new connection to node remnod using the latest default access information (through the user2 account), but the connection would fail because the password information provided earlier for the user2 account was incorrect: NCL>SET NCL DEFAULT ENTITY NODE remnod %NCL-E-REQUESTFAILED, command failed due to: -CML-E-SESSPROB, error returned from session control -IPC-E-BADUSER, access control rejection -NET-F-REMOTEDISCONN, connection disconnected by remote user %NCL-E-NOCONNECTION, cannot establish CMIP connection to remote node set ncl default entity node remnod Whenever a connection to a default entity node fails, the default entity will be reset to the local node entity. Default subentity information is cleared as well because subentities are node- specific. The default access information will be left as is, but it will remain unused until the default node entity is reset. For example, after the above failure to modify the default node entity, the NCL defaults would look like this: NCL>SHOW NCL DEFAULT NCL Default Access by User user2, Password xxx NCL Default Entity () 3 Tru64_UNIX When you are using NCL commands to manage one particular entity, either set up a default for the entity, access control information for the entity, or both. For example: ncl> set ncl default entity node .mfg.cadcam session control ncl> show ncl default entity ncl default entity = node .mfg.cadcam session control The set ncl default access command sets up default access control independently of the default entity. Once established, the default access control is applied to any command where an explicit by prepositional phrase is omitted and no user information is given with the node name. ncl> ! on node .admin.finance ncl> set ncl default access by user=j_smith, password=DoNotUse ncl> show ncl default access ncl Default access = user name=j_smith account= proxy=false ncl> show node .admin.artists session control application - _ncl> graphics_exchange all counters The set ncl default access overrides an embedded access control value in the entity. 2 Using_Snapshot The following sections describe how to use snapshot on both Tru64 UNIX and OpenVMS. 3 Tru64_UNIX Snapshot saves all of the counter attributes available from the specified entity at that time. You can snapshot only counters, and the results are displayed using a subsequent show command. For example, do either of the following: ncl> snapshot node 0 all counters or ncl> snapshot node 0 all counters, to file_name If you omit the attribute list entirely from the snapshot command, NCL defaults to all counters. If you do not choose a file name, NCL retains the binary data in memory. If you enter the show command for which the remote entity returns any counters, NCL tries to find snapshot data in the snapshot file you specified (or within its memory, if you did not specify a file name). If your show command does not contain the from preposition, NCL tries to find a corresponding snapshot in memory. If you have not performed a snapshot command in this NCL session, NCL displays just the raw counters. If the show command does contain the from preposition, NCL tries to read the specified file. If NCL cannot open the file, it returns the appropriate error message and displays the data returned from the entity. If a snapshot file exists, but does not contain data from the current entity, NCL displays just the raw counters. If NCL succeeds in finding a saved snapshot of the entity's counters, then it displays the counters returned by the agent. The following example shows a typical snapshot file, in this instance called x.tmp: ncl> snapshot 12.80 csm sta * oct se, oct r, to x.tmp To recall the snapshot file x.tmp, you would use the following command: show n 12.80 csm sta *, from x.tmp Node 12.80 CSMA-CD Station csmacd-1 AT 1994-09-08-11:12:01.497-04:00I0.165 Snapshot Elapsed Time = +0-02:01:47.536I0.428 Current Snapshot Difference ------- -------- ----------- Counters Octets Sent 64354851 45070297 19284554 Octets Received 34030180 27575906 6454274 To list all the snapshots that NCL is holding "in memory," use the command: ncl> show ncl snapshots To eliminate the snapshot corresponding to a value, thus allowing counters to be displayed in the normal name=value format, use the command: ncl> clear ncl snapshot 50 without this, the only way to get back to a normal display is to exit NCL and reinvoke it. To periodically poll the value of a counter and display it (using the snapshot format) until ^C'ed, use the command: ncl> cmonitor entity counter this is similar to netstat and iostat which allow you to monitor a value by specifying an interval. To control what the interval between polls should be, use the commands: ncl> set ncl cmonitor time = 5 ncl> show ncl cmonitor time 3 OpenVMS The snapshot function saves the counters' values and displays those values. After the snapshot command is issued, the show command can be used to display a comparison of the current values and the registered values at later times. The following command activates snapshot for the entity and produces the snapshot output: NCL> snap nsp port nsp$port_0000200f all counters Snapshot node 0 NSP Port NSP$PORT_0000200F at 1994-09-18-19:49:11.76078 - 04:00 I 52.08425 Counters Creation Time = 1991-09-18-18:55:25.59899 - 04:00 I 52.08425 User Octets Received = 932 User Octets Sent = 246 User PDUs Received = 22 User PDUs Sent = 10 . . . The following show command displays the snapshot for the entity for which snapshot was activated: NCL> show nsp port nsp$port_0000200f all counters Show node 0 NSP Port NSP$PORT_0000200F at 1994-09-18-19:49:11.76078 - 04:00 I 52.08425 Counters Creation Time = 1994-09-18-18:55:25.59899 - 04:00 I 52.08425 Snapshot created at 1994-09-18-19:49:11.76078 - 04:00 I 52.08425 Actual Value Snapshot Value Difference ------------- --------------- --------- User Octets Received 2414 932 1482 User Octets Sent 262 246 16 User PDUs Received 25 22 3 User PDUs Sent 11 10 1 . . . . . . . . . . . . Snapshot information is only retained for the duration of an NCL session. Therefore, the snapshot command and subsequent show commands must be issued at the NCL> prompt rather than at the DCL prompt. To gather snapshot information from a remote node, you can either set the ncl default to the remote node entity or include the nodename in each ncl command, as long as the commands are issued within the same NCL session. 2 Customizing_NCL You can customize your NCL environment using optional initialization files. In addition, on OpenVMS you have the option of using a keypad definition file. Tru64 UNIX allows you to define symbols for use with NCL. Setting a default NCL context is another way of customizing your NCL environment. This allows you to specify a particular entity or default access control information to be used for the remainder of an NCL session. For information on setting a default NCL context, refer to HELP NCL DEFAULT_CONTEXT. 3 Initialization_File The initialization file contains NCL commands that are executed when you start NCL; that is, before you receive the NCL prompt. Alternatively, the initialization file is executed prior to executing an NCL script file that is specified as part of a DCL command line. In the following example, the initialization file will be executed before the ROUTING.NCL script: $ ncl @routing.ncl 4 OpenVMS NCL uses the default file name SYS$LOGIN:NCL$INIT.COM unless you have defined an alternative file use the NCL$INIT logical. To use NCL$NODEA_INIT.COM as an initialization file, use the following DCL define command: $ define ncl$init ncl$nodea_init.com When NCL starts up, it will check for the file NCL$NODEA_INIT.COM, and if it exists, will execute the ncl commands within it. 4 Tru64_UNIX For Tru64 UNIX, if the file .nclrc exists in the user's top level directory, the command within it will be executed automatically when NCL is started. 3 Key_Definition_File_(OpenVMS) The key definition file associates commonly used NCL commands with keys on the keypad. Use the define/key command to create the definition. NCL uses the default file name SYS$LOGIN:NCL$KEYDEF.INIT unless you have defined an alternative file use the NCL$KEYDEF logical. The SYS$EXAMPLES:SETUP_NCL_KEYPAD.COM command file creates files that allow you to execute commonly used NCL commands using one or two keystrokes on the keypad. This command file should be executed from the system account. It works in a cluster environment, but only for those roots on a single system disk and only for those nodes booted into the cluster at the time you execute the command file. $ @sys$examples:setup_ncl_keypad This command file creates Keypad definitions files for NCL to be used with the HP DECnet-Plus for OpenVMS products. It creates files in SYS$MANAGER: and SYS$HELP:. All files begin with NCL$KEYDEF. A copy of this file will be made in SYS$UPDATE: In a cluster environment, NCL scripts are created in SYS$SPECIFIC: directories for each node on this system disk. This file may be copied to any system running HP DECnet-Plus for OpenVMS. Note: Please add "$ DEFINE/SYSTEM NCL$KEYDEF SYS$MANAGER:NCL$KEYDEF.INIT" to your OpenVMS startup procedure. Continue? [Y/N Def: Y]: Creating NCL Key Definition Init File... Creating NCL Key Definition Help Text Files... Installing in a cluster environment. Scripts created for each member... %SYSMAN-I-ENV, current command environment: Clusterwide on local cluster Username SYSTEM will be used on nonlocal nodes %SYSMAN-I-OUTPUT, command execution on node NODEA NSP Show Nodes Complete... OSI Show Nodes Complete... Show Routing Adjacencies Complete... %SYSMAN-I-OUTPUT, command execution on node NODEB NSP Show Nodes Complete... OSI Show Nodes Complete... Show Routing Adjacencies Complete... %SYSMAN-I-OUTPUT, command execution on node NODEA %SYSMAN-I-OUTPUT, command execution on node NODEB $ Once in NCL, keypad (PF4) displays an introduction and keypad PF2 provides help on the keypad layout. 3 Defining_Symbols_(Tru64_UNIX) You can define symbols to represent commonly used class/instance pairs of NCL commands. Symbol definitions are provided to cut down on the amount of repetitive typing you must perform. Use the define and read control verbs to create and verify symbol definitions. For example: define ncl symbol NAME = "VALUE" undefine ncl symbol [ NAME | * ] show ncl symbol [ NAME | * ] list ncl symbol [ NAME | * ] ncl> define ncl sym rc1 = "routing circuit circuit-1" ncl> show rc1 Node 0 Routing Circuit circuit-1 AT 1994-07-14-15:10:10.976-04:00I0.226 Identifiers Name = circuit-1 The first parameter to the define command is the symbol and all remaining text is the equivalence string (the translation of the symbol). The symbol can be from 1 to 500 characters in length and contain any ISO latin-1 characters (?). At definition time, the equivalence string is not parsed. NCL will parse the full NCL command and any symbols that form part of the command. To delete symbols, use the undefine verb. For example: ncl> undefine Ether,Remote_Node ! To delete specific symbols . . . ncl> undefine * ! To delete all remaining symbols . . . You can use "." to mean "the entity used in the last command."