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 . . . . . . . . . . . . . . . . . .
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 . . . . . . .
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.
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.
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.
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 E100 E101 E102 E103 E104 E200 Notes Command does not exist. Invalid command The arguments supplied arguments.
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.
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.
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.
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.
Command Reference User Management Overview Types of users who can access the CLI The CLI is accessible to three of the four user types supported by the Switched Rack PDU: • The administrator has unrestricted access. • The device manager (device-only user) can view status and configure most settings, including all settings of all outlets. • An outlet user can control and configure only those outlets assigned to that user The read-only user has no access to the CLI.
User Management Commands adduser Syntax: adduser user_name Description: Add an outlet user to the local database. Until an outlet user is explicitly assigned access to specific outlets, that user, by default, has no outlet access. Access: Administrator only. Parameter: user_name One to ten printable ASCII characters. Output Format: OK Password: password Re-enter password: password User name and password set for user user_name.
Command Reference: User Management assign Syntax: assign outlet|range[,outlet|range...] user_name Description: Grant access to specified outlets to a user configured in the local database. (Outlet permissions for RADIUS-defined users can be configured only at the RADIUS server.) Access: Administrator only Parameters: outlet range user_name An outlet number. A range of outlet numbers, with a hyphen separating the starting number from the ending number. A user configured in the local database.
Command Reference: User Management Commands passwd Syntax: passwd|password [user_name] Description: To be prompted to change your password, omit user_name. As an administrator, specify a user name to be prompted to change that user’s password. A password must be one to ten printable ASCII characters. You must change RADIUS-authenticated passwords at the RADIUS server. Access: All three account types, to change the logged-on user’s password. Administrator only, to change another user’s password.
Command Reference: User Management unassign Syntax: unassign outlet|range[,outlet|range...] user_name Description: Remove access to specified outlets from a user configured in the local database. (Outlet permissions for RADIUS-defined users can be removed only at the RADIUS server.) Access: Administrator only Parameters: outlet range user_name An outlet number. A range of outlet numbers, with a hyphen separating the starting number from the ending number. A user configured in the local database.
Outlet Overview Access to outlets An administrator or an outlet user can use all the CLI outlet commands to manage outlets, but an outlet user can use these commands to manage only the outlets to which he or she has been granted access. (An administrator grants access through the CLI assign command or through the Web or control console interfaces of the Switched Rack PDU.
Outlet Commands off Syntax: off all outlet|range[,outlet|range...] Description: Turn off one or more outlets. If you specify more than one outlet, the outlets will turn off approximately at the same time. However, for close synchronization, outlets must be configured as part of a synchronized outlet group. Parameters: all The value all turns off all outlets of the Switched Rack PDU. This value is not casesensitive. outlet An outlet name or number.
Command Reference: Outlet Commands on Syntax: on all outlet|range[,outlet|range...] Description: Turn on one or more outlets. If you specify more than one outlet, the outlets will turn on approximately at the same time. However, for close synchronization, outlets must be configured as part of a synchronized outlet group. Parameters: all The value all turns on all outlets of the Switched Rack PDU. This value is not casesensitive. outlet An outlet name or number.
Command Reference: Outlet Commands outletgroups Syntax: outletgroups Description: List the outlet synchronization groups defined on the Switched Rack PDU. If synchronization of outlets among PDUs is enabled, command output also includes information on those devices. Parameters: None. Output format: group_name: IP_address_of_local_PDU Outlets: number, number... IP_address_of_remote_PDU Outlets: number, number... group_name: IP_address_of_local_PDU Outlets: number, number...
Command Reference: Outlet Commands poweroffdelay Syntax (to read the power-off delay): poweroffdelay [outlet|range][,outlet|range...] Syntax (to set the power-off delay): poweroffdelay outlet|range[,outlet|range...] time|never Description: Set or read the power-off delay (the time in seconds that the PDU waits after a command is issued before it restores power to an outlet). If you do not specify any outlets, the power-off delay settings of all outlets to which you have access are read.
Command Reference: Outlet Commands powerondelay Syntax (to display the power-on delay): powerondelay [outlet|range][,outlet|range...] Syntax (to set the power-on delay): powerondelay outlet|range[,outlet|range...] time|never Description: Set or read the power-on delay (the time in seconds that the PDU waits after a command is issued before it restores power to an outlet). If you do not specify any outlets, the power-on delay settings of all outlets to which you have access are read.
Command Reference: Outlet Commands reboot Syntax: all outlet|range[,outlet|range...] reboot Description: Remove and then restore power to one or more outlets. The CLI does not wait for the reboot command to complete before providing output and re-displaying the CLI prompt (APC> ). If you specify more than one outlet, the outlets will turn off and on approximately at the same time. However, for close synchronization, outlets must be configured as part of a synchronized outlet group.
Command Reference: Outlet Commands rebootduration Syntax (to read the reboot duration): rebootduration [outlet|range][,outlet|range...] Syntax (to set the reboot duration): rebootduration outlet|range[,outlet|range...]:time Description: Set or read the reboot duration (the time in seconds that an outlet will remain off before restarting). If you do not specify any outlets, the reboot duration settings of all outlets to which you have access are read.
Command Reference: Outlet Commands status status outlet|range[,outlet|range...] Description: Reads the status (ON or OFF) of outlets that you specify from among the outlets assigned to you. A trailing asterisk (*) after the status in the output indicates that a control action is pending. Parameters: outlet An outlet name or number. If you specify a name that contains a space character, you must enclose the name in quotation marks.
Switched Rack PDU Commands current Syntax: current Description: Displays the total current draw in amps. The Switched Rack PDU does not track its total current draw. Parameters: None. Access: All three account types with access to the CLI.
Command Reference: Switched Rack PDU Commands list Syntax: list Description: When the administrator or device manager (device-only user) uses the command: • If the current user was authenticated by RADIUS, the output lists all RADIUS-defined users, all users in the local database, and the outlets assigned to each through RADIUS.
Command Reference: Switched Rack PDU lowloadwarning Syntax (to read the low-load warning threshold): lowloadwarning [phase_number] Syntax (to set the low-load warning threshold): lowloadwarning phase_number current Description: Set or read the low-load warning threshold. Parameters: phase_number The number (1, 2, or 3) of the phase whose low-load warning threshold will be read or set. The default is 1. current The threshold, in amps, to set for the phase specified as phase_number.
Command Reference: Switched Rack PDU Commands nearoverloadwarning Syntax (to read the nearoverload alarm threshold): nearoverloadwarning [phase_number] Syntax (to set the nearoverload warning threshold): nearoverloadwarning phase_number current Description: Set or read the near-overload warning threshold. Parameters: phase_number The number (1, 2, or 3) of the phase whose near-overload warning threshold you want to read or set. The default is phase 1.
Command Reference: Switched Rack PDU overloadalarm Syntax (to read the overload alarm threshold): overloadalarm [phase_number] Syntax (to set the overload alarm threshold): overloadalarm phase_number current Description: Set or read the overload alarm threshold. Parameters: phase_number The number (1, 2, or 3) of the phase whose overload alarm threshold you want to read or set. The default is phase 1. current The threshold, in amps, to set for the phase specified as phase_number.
Command Reference: Switched Rack PDU Commands overloadrestriction Syntax to read the overload restriction: overloadrestriction [phase_number] Syntax to set the overload restriction: overloadrestriction phase_number setting Description: When the overload restriction is set to on, the command prevents outlets from turning on while the overload alarm threshold is violated. • To read the current setting, omit setting in the command line.
Command Reference: Switched Rack PDU pducoldstartdelay Syntax (to read the cold-start delay): pducoldstartdelay Syntax (to set the cold-start delay): pducoldstartdelay {time|never} Description: Set or read the PDU cold-start delay (the time that the Switched Rack PDU delays applying power to the outlets after AC power has been applied to the Switched Rack PDU).
General Management Commands exit Syntax: {exit|logout|logoff|quit|bye} Description: Exit from the CLI interface. Parameters: None. Output Format: OK Bye. Error Message: E101 help Syntax: help|? [command] Description: Obtain help on CLI commands Parameter: command The name of the command for which help will be provided. If you omit command, the output consists of a list of all the CLI commands available and applicable to your account type.
Command Reference: General Management uploadini Syntax: uploadini Description: Upload an INI file, using XMODEM, when you are accessing the CLI through a serial connection. After the upload completes: • If there are any system or network changes, the user interface of the Switched Rack PDU restarts, and you must log into the CLI again.
Command Reference: General Management Commands ver Syntax: ver Description: Displays information about the Switched Rack PDU and its configuration. Access: All three user types with access to the CLI. Parameters: None.
Index A D adduser, 10 assign, 11 Automatic log-off, 6 deluser, 11 B Editing command lines, 3 Error codes, 4 escape character, reverse slant, 3 exit, 30 bye, 30 C Commands adduser, 10 assign, 11 bye, 30 current, 23 deluser, 11 editing the command line, 3 exit, 30 help, 30 how to enter commands, 3 list, 24 logoff, 30 logout, 30 lowloadwarning, 25 name, 25 nearoverloadalarm, 26 off, 15 on, 16 outletgroups, 17 overloadalarm, 27 overloadrestriction, 28 passwd, 12 pducoldstartdelay, 29 power, 29 poweroffde
Index on, 16 outletgroups, 17 Outlets commands, 15 overview, 14 overloadalarm, 27 overloadrestriction, 28 P passwd, 12 pducoldstartdelay, 29 power, 29 poweroffdelay, 18 powerondelay, 19 Q quit, 30 Quotation marks, 3 U unassign, 13 uploadini, 31 User management commands, 10 overview, 9 V ver, 32 R reboot, 20 reset_defaults_pdu, 30 Reverse slant, as escape character, 3 S Space character as delimiter, 3 status, 22 Switched Rack PDU commands, 23 Synchronized outlet groups, 14 Syntax characters and fonts,
APC Worldwide Customer Support Customer support for this or any other APC product is available at no charge in any of the following ways: • Visit the APC Web site to access documents in the APC Knowledge Base and to submit customer support requests. – www.apc.com (Corporate Headquarters) Connect to localized APC Web sites for specific countries, each of which provides customer support information. – www.apc.com/support/ Global support searching APC Knowledge Base and using e-support.
