Schneider Electric AP9640, AP9641, AP9643 Command Line Interface Guide

Command Line Interface Guide

UPS Network Management Card 3

AP9640, AP9641, AP9643

990-91149C-001 02/ 2021

Schneider Electric Legal Disclaimer

The information presented in this manual is not warranted by Schneider Electric to be authoritative, error free, or complete. This publication is not meant to be a substitute for a detailed operational and site specific development plan. Therefore, Schneider Electric assumes no liability for damages, violations of codes, improper installation, system failures, or any other problems that could arise based on the use of this Publication.

The information contained in this Publication is provided as is and has been prepared solely for the purpose of evaluating data center design and construction. This Publication has been compiled in good faith by Schneider Electric. However, no representation is made or warranty given, either express or implied, as to the completeness or accuracy of the information this Publication contains.

IN NO EVENT SHALL SCHNEIDER ELECTRIC, OR ANY PARENT, AFFILIATE OR SUBSIDIARY COMPANY OF SCHNEIDER ELECTRIC OR THEIR RESPECTIVE OFFICERS, DIRECTORS, OR EMPLOYEES BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL, OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS, CONTRACT, REVENUE, DATA, INFORMATION, OR BUSINESS INTERRUPTION) RESULTING FROM, ARISING OUT, OR IN CONNECTION WITH THE USE OF, OR INABILITY TO USE THIS PUBLICATION OR THE CONTENT, EVEN IF SCHNEIDER ELECTRIC HAS BEEN EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SCHNEIDER ELECTRIC RESERVES THE RIGHT TO MAKE CHANGES OR UPDATES WITH RESPECT TO OR IN THE CONTENT OF THE PUBLICATION OR THE FORMAT THEREOF AT ANY TIME WITHOUT NOTICE.

Copyright, intellectual, and all other proprietary rights in the content (including but not limited to software, audio, video, text, and photographs) rests with Schneider Electric or its licensors. All rights in the content not expressly granted herein are reserved. No rights of any kind are licensed or assigned or shall otherwise pass to persons accessing this information.

This Publication shall not be for resale in whole or in part.

Command Line Interface (CLI)

How To Log On

Overview

To access the command line interface, you can use either a local, serial connection, or a remote connection (Telnet or SSH) with a computer on the same network as the Network Management Card (NMC).

To access the Command Line Interface detailed in this CLI Guide, the NMC must have the SmartUPS or Single Phase Symmetra firmware installed, and the NMC must be installed in a Smart-UPS or Single Phase Symmetra model UPS. For more information on UPS models compatible with your NMC, see Knowledge Base article FA237786 on the APC support website, www.apc.com/support

Use case-sensitive user name and password entries to log on (by default, apc and apc for a Super User). The default user name for a Device User is device. A Read-Only User cannot access the command line interface.

NOTE: You will be prompted to enter a new password the first time you connect to the NMC with the Super User account.

Security Lockout. If a valid user name is used with an invalid password consecutively for the number of times specified in the NMC web interface under Configuration > Security > Local Users > Default Settings, the Device User account will be locked until a Super User or Administrator re-enables the account.

See the UPS Network Management Card 3 User Guide (for AP9640, AP9641, AP9643) for more information on these options.

If you cannot remember your user name or password, see “How to Recover from a Lost Password” in the User Guide.

Remote access to the command line interface

You can access the command line interface through Telnet or SSH. Only SSH is enabled by default.

To enable or disable these access methods, use the Web interface. On the Configuration menu, select

Network > Console > Access.

You can also enable or disable Telnet or SSH access through the command line interface. See “console” on page 13.

SSH for high-security access. If you use the high security of SSL/TLS for the Web interface, use SSH for access to the command line interface. SSH encrypts user names, passwords, and transmitted data. The interface, user accounts, and user access rights are the same whether you access the command line interface through SSH or Telnet, but to use SSH, you must first configure SSH and have an SSH client program installed on your computer. Enabling SSH also enables SCP (Secure Copy), for secure file transfer.

1	UPS Network Management Card 3 CLI User Guide

1. Use the following example command to use SSH to access the NMC: ssh -c aes256-ctr apc@156.205.14.141

NOTE: This SSH command is for OpenSSH. The command may differ depending on the SSH tool used.

2.Enter the user name and password.

NOTE: You will be prompted to enter a new password the first time you connect to the NMC with the Super User account.

Telnet for basic access. Telnet provides the basic security of authentication by user name and password, but not the high-security benefits of encryption.

To use Telnet to access the command line interface:

1.From a computer that has access to the network on which the NMC is installed, at a command prompt, type telnet and the IP address for the NMC (for example, telnet 139.225.6.133, when the NMC uses the default Telnet port of 23), and press ENTER.

NOTE: This example works for command prompt based Telnet clients. The commands may differ for different Telnet clients.

If the NMC uses a non-default port number (from 5000 to 32768), you must include a colon or a space, depending on your Telnet client, between the IP address (or DNS name) and the port number. (These are commands for general usage: some clients don’t allow you to specify the port as an argument and some types of Linux might want extra commands).

2.Enter the user name and password.

NOTE: You will be prompted to enter a new password the first time you connect to the NMC with the Super User account.

Local access to the command line interface

For local access, use a computer that connects to the Network Management Card through the USB virtual serial port to access the command line interface:

1.Connect the provided micro-USB cable (part number 960-0603) from a USB port on the computer to the console port at the NMC.

2.In Windows Search, type “Device Manager”, or open it from the Control Panel. Select “Ports” and note the COM port number the NMC was assigned.

3.Run a terminal program (e.g. 3rd party terminal emulator programs like HyperTerminal, PuTTy, or Tera Term) and configure the COM port (noted in step 2) for 9600 bps, 8 data bits, no parity, 1 stop bit, and no flow control. Save the changes.

4.Press ENTER, repeatedly if required, to display the User Name prompt.

5.Enter the user name and password.

NOTE: The user name will be “apc” at first log for the Super User account. You will be prompted to enter a new password after you log in.

UPS Network Management Card 3 CLI User Guide

2

Main Screen

Sample main screen

Following is an example of the screen displayed when you log on to the command line interface at the Network Management Card (NMC).

Information and status fields

Main screen information fields.

•Two fields identify the American Power Conversion operating system (AOS) and application (APP) firmware versions. The application firmware name identifies the device that connects to the network through this NMC. In the example above, the NMC uses the application firmware for a Smart-UPS UPS.

Network Management Card AOS	vx.x.x
Smart-UPS APP	vx.x.x

•Three fields identify the system name, contact person, and location of the NMC.

Name : Test Lab

Contact: Don Adams

Location: Building 3

•The Up Time field reports how long the NMC management interface has been running since it was last turned on or reset.

Up Time: 0 Days 21 Hours 21 Minutes

•Two fields report when you logged in, by date and time.

3	UPS Network Management Card 3 CLI User Guide

Date : 06/30/2020

Time : 5:58:30

•The User field reports whether you logged in through the Super User, Administrator, Device Manager, Network-Only or Read-Only account.

When you log on as Device Manager (equivalent to Device User in the user interface), you can access the event log, configure some UPS settings, and view the number of active alarms.

User : Super User

Main screen status fields.

•The Stat field reports the NMC status. The middle status varies according to whether you are running IPv4, IPv6, or both, as indicated in the second table below.

Stat : P+ N+ A+

P+	The operating system (AOS) is functioning properly.

IPv4	IPv6	IPv4 and
only	only	IPv6*
N+	N6+	N4+	N6+
N?	N6?	N4? N6?
N–	N6–	N4N6-
N!	N6!	N4! N6!

Description

The network is functioning properly.

A DHCP or BOOTP request cycle is in progress.

The NMC did not connect to the network.

Another device is using the IP address of the NMC.

*The N4 and N6 values can be different from one another: you could, for example, have N4– N6+.

A+	The application is functioning properly.
A–	The application has a bad checksum.
A?	The application is initializing.
A!	The application is not compatible with the AOS.

If P+ is not displayed, see customer support at http://www.apc.com/site/support/.

UPS Network Management Card 3 CLI User Guide

4

How to Use the Command Line Interface

Overview

The command line interface provides options to configure the network settings and manage the UPS and its Network Management Card (NMC).

How to enter commands

At the command line interface, use commands to configure the NMC. To use a command, type the command and press ENTER. Commands and arguments are valid in lowercase, uppercase, or mixed case. Options are case-sensitive.

While using the command line interface, you can also do the following:

•Type ? and press ENTER to view a list of available commands, based on your account type.

To obtain information about the purpose and syntax of a specified command, type the command, a space, and ? or the word help. For example, to view RADIUS configuration options, type: radius ?

or

radius help

•Press the UP arrow key to view the command that was entered most recently in the session. Use the UP and DOWN arrow keys to scroll through a list of up to ten previous commands.

•Type at least one letter of a command and press the TAB key to scroll through a list of valid commands that match the text you typed in the command line.

•Type ups -st to view the status of the UPS.

•Type exit or quit to close the connection to the command line interface.

Command syntax

Item

-

< >

[ ]

|

Description

Options are preceded by a hyphen.

The definitions of options are enclosed in angle brackets. For example:

-pw <user password>

If a command accepts multiple options or an option accepts mutually exclusive arguments, the values may be enclosed in brackets.

A vertical line between items enclosed in brackets or angle brackets indicates that the items are mutually exclusive. You must use one of the items.

5	UPS Network Management Card 3 CLI User Guide

Syntax examples

A command that supports multiple options: user -n <user name> -pw <user password>

Here, the user command accepts both the option -n, which specifies the user name, and the option -pw, which changes the password.

For example, to change a password to XYZ: user -n apc -pw XYZ

NOTE: Super User also requires the current password when changing the password remotely. See the “user” section.

A command that accepts mutually exclusive arguments for an option: alarmcount -p [all | warning | critical]

In this example, the option -p accepts only three arguments: all, warning, or critical. For example, to view the number of active critical alarms, type:

alarmcount -p critical

The command will not work if you type an argument that is not specified.

Command Response Codes

The command response codes enable scripted operations to detect error conditions reliably without having to match error message text.

The CLI reports all command operations with the following format:

E [0–9][0–9][0–9]: Error message

Code	Error message
E000	Success
E001	Successfully Issued
E002	Reboot required for change
	to take effect
E100	Command failed
E101	Command not found
E102	Parameter Error
E103	Command Line Error
E107	Serial communication with
	the UPS has been lost
E108	EAPoL disabled due to
	invalid/encrypted certificate

UPS Network Management Card 3 CLI User Guide

6

Command Descriptions

The availability of the commands and options below can vary between UPS devices.

?

Access: Super User, Administrator, Device User

Description: View a list of all the CLI commands available to your account type. To view help text for a specific command, type the command followed by a question mark.

Example: To view a list of options that are accepted by the alarmcount command, type: alarmcount ?

about

Access: Super User, Administrator, Device User, Read-Only User, Network-Only User

Description: View hardware and firmware information. This information is useful in troubleshooting and enables you to determine if updated firmware is available at the website.

alarmcount

Access: Super User, Administrator, Device User, Read Only

Description:

Option Arguments

all

-p warning critical informational

Description

View the number of active alarms reported by the NMC. Information about the alarms is provided in the event log.

View the number of active warning alarms. View the number of active critical alarms. View the number of active informational alarms.

Example: To view all active warning alarms, type: alarmcount -p warning

7	UPS Network Management Card 3 CLI User Guide

bacnet

Access: Super User, Administrator, Device User Description: View and define the BACnet settings.

For more information on the UPS data points made available via BACnet, see the BACnet Application Maps available on the APC website, www.apc.com.

	Option	Arguments
	-S	enable |
		disable
	-d	0-4194303
	-n	<device
		name>
	-t	1000 - 30000
	-r	0 - 10

-pw <password>

BACnet IP options:

-o 47808, 5000-65535

Description

Select the option to enable or disable BACnet. If BACnet is disabled, the NMC cannot be accessed via BACnet. BACnet is disabled by default.

NOTE: BACnet cannot be enabled until the Device Communication Control Password (-pw) is set.

A unique identifier for this BACnet device, used for addressing the device.

A name for this BACnet device, which must be unique on the BACnet network. The default device name is “BACn”+ the last eight digits of the NMC MAC address. The minimum length is 1, the maximum length is 150 characters, and special characters are permitted.

Specify the APDU timeout; the number of milliseconds the NMC will wait for a response to a BACnet request. The default value is 6000.

Specify the APDU retries; the number of BACnet requests attempts that the NMC will make before aborting the request. The default value is 3.

The Device Communication Control service is used by a BACnet client to instruct a remote device (e.g. a BACnet-enabled NMC) to stop initiating, or stop responding to all APDUs (except the Device Communication Control service) for a specified duration of time. This service can be used for diagnostic purposes.

Specify the Device Communication Control password to ensure that a BACnet client cannot control the BACnet communication of an NMC without first providing the password set here. The password is required to be between 8 and 20 characters, and must contain:

•A number.

•An uppercase character.

•A lowercase character.

•A special character.

It is recommended to update the password when you first enable BACnet. You do not need to know the current password to update the password.

Specify the UDP/IP port the NMC uses to send and receive BACnet/IP messages.

NOTE: The address of a BACnet/IP-enabled NMC is defined as the IP address of the NMC and the local port.

UPS Network Management Card 3 CLI User Guide

8

Option Arguments

-fdre enable | disable

-rip	IP address
-rpo	5000 - 65535
-fttl	1-65535

-fsl

Example:

Description

Specify enable to register the NMC with a BACnet broadcast management device (BBMD).

NOTE: You need to register your NMC as a foreign device with a BBMD if there is no BBMD currently on the subnet of the NMC, or if the NMC uses a different local port to the BBMD. See the NMC User Guide for more information on Foreign Device Registration.

The IP address or fully qualified domain name (FQDN) of the BACnet broadcast management device with which this NMC card will be registered.

The port of the BBMD with which this NMC card will be registered.

The number of seconds (Time To Live) that the BBMD will maintain the NMC as a registered device. If the NMC does not re-register before this time expires, the BBMD will delete it from its foreign-device table, and the NMC will no longer be able to send and receive broadcast messages via the BBMD.

The foreign device registration status.

bacnet

E000: Success Enabled: yes Device ID: 1013

Device name: BACnB7D7E5F2 Network Protocol: BACnet/IP APDU timeout (ms): 6000 APDU retries: 3

IP Port: 47808 (0xBAC0) Registration Enabled: no

Registration Status: Foreign device registration inactive Registration BBMD: 0.0.0.0

Registration BBMD port: 47808 (0xBAC0) Registration TTL: 7200

9	UPS Network Management Card 3 CLI User Guide

boot

Access: Super User, Administrator, Network-Only User

Description: Define how the NMC will obtain its network settings, including the IP address, subnet mask, and default gateway. Then configure the BOOTP or DHCP server settings.

	Option Argument
	-b	dhcp | bootp |
	<boot
		manual
	mode>
	-c	enable |
		disable

Description

Define how the TCP/IP settings will be configured when the NMC turns on, resets, or restarts.

dhcp boot modes only. Enable or disable the requirement that the DHCP server provide the APC cookie.

The default values for these three settings generally do not need to be changed:

-v <vendor class>

-i <client id>

-u <user class>

APC.

The MAC address of the NMC, which uniquely identifies it on the network.

The name of the application firmware module.

Example: To use a DHCP server to obtain network settings:

1.Type boot -b dhcp

2.Enable the requirement that the DHCP server provide the APC cookie: boot -c enable

bye

Access: Super User, Administrator, Device User, Read-Only User, Network-Only User

Description: Exit from the command line interface session.This works the same as the exit or quit commands.

Example: bye

Connection Closed - Bye

cd

Access: Super User, Administrator, Device User, Read-Only User, Network-Only User Description: Navigate to a folder in the directory structure of the NMC.

Example 1: To change to the ssh folder and confirm that an SSH security certificate was uploaded to the NMC:

1.Type cd ssh and press ENTER.

2.Type dir and press ENTER to list the files stored in the SSH folder.

Example 2: To return to the previous directory folder, type: cd ..

UPS Network Management Card 3 CLI User Guide

10

cfgshutdn

Access: Super User, Administrator, Device User

Description: Configure the shutdown parameters: this enables you to show and configure UPS Shutdown Delay, UPS Return Delay, UPS Low Battery Duration, UPS Sleep Time, UPS Minimum Battery Charge, and UPS Min Return Runtime.

These options are not available with all UPS devices.

Option	Argument
-all
	000	| 090	|
-sd	180	| 270	|
	360	| 450	|
	540	| 630
-lo	02 | 05 |		08
	| 11 | 14		|
	17 | 20 |		23
	000	| 060	|
-rd	120	| 180	|
	240	| 300	|
	360	| 420
-rrt	0–3600
-sl	0.0–359.9
-rsc	00 | 15 |		30
	| 45 | 60		|
	75 | 90

Example: cfgshutdn -all

E000: Success

Description

Show all applicable shutdown parameters for this UPS.

Set the shutdown delay in seconds.

Set the low battery duration in minutes.

Set the UPS return delay in seconds, that is, the delay time before the UPS turns on again.

Set the minimum return runtime in seconds, that is, the battery runtime to support the load must reach this value before the UPS turns on again.

Set the sleep time, in hours. The argument can have any number between 0.0 and 359.9.

Set the minimum battery charge, as a percentage of the total capacity.

Low Battery Duration: 4 min Sleep Time: 0.0 hr0

11	UPS Network Management Card 3 CLI User Guide

cfgpower

Access: Super User, Administrator, Device User

Description: Configure the power parameters: this enables you to show and configure transfer points, sensitivity and output voltage.

These options are not available with all UPS devices.

Option

-all -l -h

-ov

-s

-bu

-bl

-rda

-lda

-rta

Argument

These values can vary with different devices.

97–106
127–136
100	|	120	|
110	|
Normal |			Low
Reduced |
127	|	130	|
133	|	136	|
139	|	142	|
145	|	148
086	|	088	|
090	|	092	|
094	|	096	|
098	|	100
Never | n+1 |
n+2
Never		| 01.0

| 02.0 | 03.0 | 04.0 | 05.0

| 06.0 | 07.0 | 08.0 | 09.0 | 10.0 | 12.0 | 14.0 | 16.0

Never | 005 | 010 | 015 | 030 | 045 | 060 | 120 | 180 | 240 | 300 | 360 |

420 | 480

Description

Show all applicable power parameters for this UPS.

Set the low transfer point, in VAC.

Set the high transfer point, in VAC.

Set the outlet voltage, in VAC.

Set the sensitivity, using one of the three arguments.

Set the bypass upper voltage in VAC; when the voltage rises above this value, the device goes into bypass.

Set the bypass lower voltage in VAC; when the voltage drops below this value, the device goes into bypass.

Set an alarm to occur if available redundant power drops below n+1 or n+2. Enter Never to prevent an alarm in response to any loss of redundancy. This option is available for Symmetra model UPS only.

Set an alarm to occur if the load exceeds the specified kVA load level. Enter Never to prevent an alarm in response to changes to the load level. This option is available for Symmetra model UPS only.

Set an alarm to occur if the Available Battery Runtime drops below the specified number of minutes. Available Battery Runtime is the number of minutes the UPS can support the current load while operating on battery power. Enter Never to prevent an alarm in response to a drop in available battery runtime. This option is available for Symmetra model UPS only.

UPS Network Management Card 3 CLI User Guide

12

Example: cfgpower -all E000: Success

Low Transfer Voltage: 106 VAC High Transfer Voltage: 127 VAC Sensitivity: Normal

clrrst

Access:

Super User, Administrator

Definition: Clear the network interface reset reason. See “lastrst” on page 22.

console

Access: Super User, Administrator, Network Only

Description: Define whether users can access the command line interface using Telnet, which is disabled by default, or Secure Shell (SSH), which is enabled by default, which provides protection by transmitting user names, passwords, and data in encrypted form. You can change the Telnet or SSH port setting for additional security. Alternately, disable network access to the command line interface.

	Option	Argument
	-s	enable | disable
	-t	enable | disable
	-pt	<telnet port
		number>
	-ps	<SSH port number>
	-b	2400 | 9600 |
		19200 | 38400

Description

Enable or disable SSH. Enabling SSH enables SCP. Enable or disable Telnet.

Specify the Telnet port number used to communicate with the NMC (23 by default). The other range is 5000–32768.

Specify the SSH port number used to communicate with the NMC (22 by default). The other range is 5000–32768

Configure the serial baud rate (9600 by default).

Example 1: To enable SSH access to the command line interface, type: console -s

Example 2: To change the Telnet port to 5000, type: console -pt 5000

date

Access: Super User, Administrator

Definition: Configure the date used by the NMC.

To configure an NTP server to define the date and time for the NMC, see the User Guide.

13	UPS Network Management Card 3 CLI User Guide