APC Command Line Interface User Manual
User’s Guide
Command Line Interface
for Switched Rack PDUs
Contents
Product Capabilities..........................1
Features . . . . . . . . . . . . . . . . . . . . . . . . . . . 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
Command Line Interface (CLI) User’s Guide i
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
ii Command Line Interface (CLI) User’s Guide
Product Capabilities
Features
Scripting
The Command Line Interface (CLI) for American
Power Conversion (APC
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.
The CLI is not supported by APC
Metered Rack PDUs
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.
®
) Switched Rack PDUs
To configure features for which
there are not corresponding CLI
commands, see “System
Requirements” on page 2 and
“uploadini” on page 31.
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
Command Line Interface (CLI) User’s Guide 1
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.
2 Command Line Interface (CLI) User’s Guide
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.
Command Line Interface (CLI) User’s Guide 3
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
Code Message Text Notes
E100 Command does not
exist.
E101 Invalid command
arguments.
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
The arguments supplied
are too few, too many, the
wrong type, etc.
for required user input,
such as a password, did
not receive that input
within three minutes.
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.
4 Command Line Interface (CLI) User’s Guide
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.
Command Line Interface (CLI) User’s Guide 5
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.
6 Command Line Interface (CLI) User’s Guide
Command Syntax
Characters and Fonts
Item Explanation
Italic Variables, such as outlet_number, are italicized.
| A vertical line between items enclosed in
[ ] Brackets enclosing an item or series of items
{} Braces enclosing two or more items, separated
... Ellipses following a variable item indicate that
All other
characters
brackets [ ] or braces {}indicates that the items
are mutually exclusive; you cannot use more
than one of the items.
indicates that the item or series is optional. Any
item not enclosed in brackets or braces is
required.
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.
additional items of the same type can follow.
All unitalicized text and all punctuation marks
are to be entered literally.
Command Line Interface (CLI) User’s Guide 7
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.
8 Command Line Interface (CLI) User’s Guide
Loading...