APC Command Line Interface User Manual

4.6 (7)
Users Guide
Command Line Interface
for Switched Rack PDUs
Contents
Command Line Interface (CLI) User’s Guide i
Product Capabilities..........................1
Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . 1
PDU features not supported by the CLI . . .1
Integration with APC Rack KVM products . .1
System Requirements. . . . . . . . . . . . . . . . . . 2
Firmware version required . . . . . . . . . . . . .2
Rack PDUs required . . . . . . . . . . . . . . . . . .2
Exporting an .ini File . . . . . . . . . . . . . . . . . . 2
Using the Commands .......................3
How to Enter CLI Commands . . . . . . . . . . . . 3
Capitalization in commands and arguments 3
Editing in the CLI . . . . . . . . . . . . . . . . . . . . 3
The Space character as command delimiter 3
Quotation marks and the reverse slant . . .3
Command Error Codes. . . . . . . . . . . . . . . . .4
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
CLI Online Help . . . . . . . . . . . . . . . . . . . . . .4
Logging On and Off.........................5
Logging On . . . . . . . . . . . . . . . . . . . . . . . . .5
User Name and Password . . . . . . . . . . . . . 5
Log-on procedure . . . . . . . . . . . . . . . . . . . 5
Responses to successful and failed log-on .5
Logging Off. . . . . . . . . . . . . . . . . . . . . . . . . 6
Log-off procedure . . . . . . . . . . . . . . . . . . .6
Automatic log-off . . . . . . . . . . . . . . . . . . . . 6
Command Syntax .............................7
Characters and Fonts . . . . . . . . . . . . . . . . . .7
Syntax Examples . . . . . . . . . . . . . . . . . . . . . 8
Italic text with no brackets or braces. . . . . .8
Braces and vertical line . . . . . . . . . . . . . . .8
Brackets and ellipses . . . . . . . . . . . . . . . . . 8
Large braces . . . . . . . . . . . . . . . . . . . . . . .8
ii Command Line Interface (CLI) User’s Guide
Command Reference ........................9
User Management Overview . . . . . . . . . . . . 9
Types of users who can access the CLI . . . 9
Authentication of users . . . . . . . . . . . . . . 9
User Management Commands . . . . . . . . . . 10
adduser . . . . . . . . . . . . . . . . . . . . . . . . . 10
assign . . . . . . . . . . . . . . . . . . . . . . . . . . 11
deluser . . . . . . . . . . . . . . . . . . . . . . . . . . 11
passwd . . . . . . . . . . . . . . . . . . . . . . . . . 12
unassign . . . . . . . . . . . . . . . . . . . . . . . . 13
whoami . . . . . . . . . . . . . . . . . . . . . . . . . 13
Outlet Overview . . . . . . . . . . . . . . . . . . . . 14
Access to outlets . . . . . . . . . . . . . . . . . . 14
Synchronized outlet groups . . . . . . . . . . 14
Outlet Commands . . . . . . . . . . . . . . . . . . . 15
off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
outletgroups . . . . . . . . . . . . . . . . . . . . . 17
poweroffdelay . . . . . . . . . . . . . . . . . . . . 18
powerondelay . . . . . . . . . . . . . . . . . . . . 19
reboot . . . . . . . . . . . . . . . . . . . . . . . . . . 20
rebootduration . . . . . . . . . . . . . . . . . . . . 21
status . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Switched Rack PDU Commands . . . . . . . . . 23
current . . . . . . . . . . . . . . . . . . . . . . . . . . 23
list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
lowloadwarning . . . . . . . . . . . . . . . . . . . 25
name . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
nearoverloadwarning . . . . . . . . . . . . . . . 26
overloadalarm . . . . . . . . . . . . . . . . . . . . 27
overloadrestriction . . . . . . . . . . . . . . . . . 28
pducoldstartdelay . . . . . . . . . . . . . . . . . 29
power . . . . . . . . . . . . . . . . . . . . . . . . . . 29
General Management Commands . . . . . . . 30
exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
help . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
reset_defaults_pdu . . . . . . . . . . . . . . . . . 30
uploadini . . . . . . . . . . . . . . . . . . . . . . . . 31
ver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Index .............................................33
Command Line Interface (CLI) User’s Guide 1

Product Capabilities

Features

Scripting

The Command Line Interface (CLI) for American
Power Conversion (APC
®
) Switched Rack PDUs
enables you to create scripts for automated
operation. The existing text-based control console
interface to Switched Rack PDUs is difficult to use
for scripting because it is menu-driven. APC will
support both interfaces.

PDU features not supported by the CLI

The Web, control console, and SNMP interfaces
for Switched Rack PDUs support the following
features that do not have corresponding CLI
commands:
Configuration for scheduling
Configuration of synchronized outlet groups
Advanced outlet control commands, such as
sequenced on
Event logging, event actions, and other
features that are provided through the APC
AOS firmware module and that you use for
monitoring through the Web interface and
control console.

Integration with APC Rack KVM products

You can use the CLI to create scripts to automate
the management of your Switched Rack PDUs
through the following APC Rack Keyboard, Video,
Mouse (KVM) products.
AP5401
AP5405
AP5456
The CLI is not supported by APC
Metered Rack PDUs
To configure features for which
there are not corresponding CLI
commands, see “System
Requirements” on page 2 and
“uploadini” on page 31.
2 Command Line Interface (CLI) User’s Guide

System Requirements

Firmware version required

To use the Command Line Interface, your
Switched Rack PDU must be running firmware
version 2.7.0 for the AOS firmware module and
2.7.3 for the application firmware module.

Rack PDUs required

You can use the command line interface only with
APC Switched Rack PDUs.

Exporting an .ini File

You can configure all parameters of a Switched
Rack PDU (including those for which there are not
specific CLI commands) by using the CLI to
transfer an .ini file to that PDU. The CLI uses
XMODEM to perform the transfer. However, you
cannot read the current .ini file through
XMODEM.
See “uploadini” on page 31.
Command Line Interface (CLI) User’s Guide 3

Using the Commands

How to Enter CLI Commands

Capitalization in commands and arguments

Commands are valid in lowercase, uppercase, or
mixed case, but arguments are case-sensitive
unless specified otherwise.

Editing in the CLI

The
BACK SPACE key deletes the most recently
entered character of the current command string.
No other editing function is available during
command entry.
The CLI does not retain a command history. You
cannot retrieve previously entered commands.

The Space character as command delimiter

The CLI uses one Space character (ASCII 0x20) as
the delimiter between commands and arguments;
extra Space characters are ignored.

Quotation marks and the reverse slant

Use quotation marks (ASCII 0x22) and the reverse
slant (\: decimal code 92) as follows:
For both input and output, enclose in quotation
marks any string value that begins or ends with
spaces or contain commas or semicolons.
Do not use traditional escape sequences (the
reverse slant followed by a lowercase
alphabetic character or by one or more
numeric characters) preceding special
characters within strings. The CLI does not
recognize such escape sequences, and the
resulting error causes the entire keyword and
value pair to be ignored.
If an argument value contains a quotation mark
or reverse slant, it must be preceded by a
reverse slant only as its escape character. For
example, this command adds the user "John
Doe" to the local database:
adduser \"John Doe"
If an input string contains a quotation mark or
reverse slant, enclose the string in quotation
marks. For example, this command adds the
user pdu\\device to the local database:
adduser "pdu\\device user"
Optionally, you can use quotation marks to
enclose any argument value.
4 Command Line Interface (CLI) User’s Guide

Command Error Codes

Format

The CLI reports all errors in the following format:
E[0-9][0-9][0-9]: Error message
The CLI reports all successful command
operations with the message OK, followed by the
output of the command.
The CLI command error codes enable scripted
operations to detect error conditions reliably
without having to match error message text.

Codes

CLI Online Help

Use the help command to do the following:
Obtain information about the purpose and
syntax of a specified command.
Check whether a command exists. If the
command you specify is not a valid CLI
command, the message Command does
not exist is displayed.
List the commands that are available to you,
based on your account type.
Code Message Text Notes
E100 Command does not
exist.
E101 Invalid command
arguments.
The arguments supplied
are too few, too many, the
wrong type, etc.
E102 User already exists.
E103 User does not exist.
E104 User does not have
access to this
command.
E200 Input error. A command that prompts
for required user input,
such as a password, did
not receive that input
within three minutes.
Command Line Interface (CLI) User’s Guide 5

Logging On and Off

Logging On

User Name and Password

If you are not using a KVM, configure the
administrator user name and password through the
Web or control console interface of the PDU.
If you are using a KVM, configure the
administrator user name and password in the KVM
configuration file /etc/pm.APCPDU. The default
for both is apc. The pm.APCPDU file is saved to
non-volatile memory when you save your
configuration. The -c option is then appended to
the configured password automatically to log you
on to the CLI when you log on to the PDU.

Log-on procedure

To log on to the CLI:
1. Connect to the Switched Rack PDU through
Telnet, through SSH version 1 or 2, or serially.
2. At the User Name prompt, enter your user
name.
3. At the Password prompt, enter your password
(followed by a space and -c if you are not
using a KVM), and press
ENTER.

Responses to successful and failed log-on

When you attempt to log on to the CLI:
If the user name and password you entered are
valid and the CLI is available, you are logged
on to the CLI. The prompt APC> is displayed.
After three consecutive unsuccessful log-on
attempts, the Switched Rack PDU prevents
further attempts for two minutes.
If the CLI is unavailable, the Switched Rack
PDU application layer does not start, i.e., the
-c option does not work.
If you log onto the CLI, and the application
firmware of the Switched Rack PDU has not
finished initializing, the CLI displays the
following message and logs you off.
The Switched Rack PDU is still
initializing. Please try again later.
If the administrator password is configured
incorrectly (does not meet the PDU criteria for
a valid password) in the KVM pm.APCPDU
configuration file, the Switched Rack PDU
prevents further log-on attempts for 150
seconds. Correct the password configuration
before trying to log on again.
6 Command Line Interface (CLI) User’s Guide

Logging Off

Log-off procedure

To log off from the CLI, use one of the following
commands: exit, logout, logoff, quit, or
bye.

Automatic log-off

You will be logged off automatically in the
following circumstances:
•If the inactivity logout time of the Switched
Rack PDU (3 minutes by default, or a
configured time of 1 to 10 minutes) expires
without keyboard input or input through the
mouse within the CLI interface. Movement of
the mouse pointer or clicking the mouse
without actual input does not restart the timer
for inactivity logout.
If the value yes is configured for the option
logoutAfterCommandComplete in the KVM
pm.APCPDU configuration file, and the CLI
completes executing the command that you
entered. The default for this option is no. A
value of yes provides maximum availability of
the text-based interface to other users.
If your connection to the Switched Rack PDU
is through Telnet or SSH version 1 or 2, and
there is a log-on serially to the Switched Rack
PDU CLI to execute a command. Serial access
to the CLI always has priority over remote
access.
Command Line Interface (CLI) User’s Guide 7

Command Syntax

Characters and Fonts

Item Explanation
Italic Variables, such as outlet_number, are italicized.
| A vertical line between items enclosed in
brackets [ ] or braces {}indicates that the items
are mutually exclusive; you cannot use more
than one of the items.
[ ] Brackets enclosing an item or series of items
indicates that the item or series is optional. Any
item not enclosed in brackets or braces is
required.
{} Braces enclosing two or more items, separated
by the vertical line character, indicate that the
items are mutually exclusive but that you must
use one of the items. Any item not enclosed in
braces or brackets is required.
Large braces have the same meaning as braces
{}, but items are “stacked” on separate lines
within the large braces to simplify complex
syntax.
... Ellipses following a variable item indicate that
additional items of the same type can follow.
All other
characters
All unitalicized text and all punctuation marks
are to be entered literally.
8 Command Line Interface (CLI) User’s Guide

Syntax Examples

Italic text with no brackets or braces.

adduser user_name
For the adduser command, you must specify the
name of the user to add (indicated in the syntax by
the variable user_name.

Braces and vertical line

pducoldstartdelay {time|never}
For the pducoldstartdelay command, you must
enter either a time in seconds (time) that the PDU
waits to apply power to its outlets or enter never
to specify that the outlets will never turn on
automatically when power is applied to the PDU.

Brackets and ellipses

assign outlet|range[,outlet|range...] user_name
For the assign command, you must specify at least
one outlet or range of outlets and the user name of
the outlet user to which the outlets are being
assigned. Brackets indicate that you can optionally
specify another outlet or range to assign to that
user, and the ellipses indicates that, optionally, you
can specify additional outlets or ranges in the same
format.

Large braces

all
on outlet|range[,outlet|range...]
For the on command, you must enter one of the
following:
The literal value all (to turn on all outlets)
A comma-delimited list that can include
outlets specified by name or number, or ranges
of outlet numbers.
Loading...
+ 27 hidden pages