Vertiv Avocent ACS800 User manual

Avocent® ACS800/8000
Advanced Console System
Application Programming Interface (API)
User Guide

Technical Support Site
If you encounter any installation or operational issues with your product, check the pertinent section of
this manual to see if the issue can be resolved by following outlined procedures. Visit
https://www.VertivCo.com/en-us/support/ for additional assistance.

TABLE OF CONTENTS
1 Overview 1
1.1 Base URL 1
1.2 Methods 1
1.3 Body 1
1.4 Query Parameters 1
1.5 Response Codes 2
1.5.1 Error information 2
1.5.2 Ignored keys 2
1.6 Authentication 3
1.6.1 JSON Web Token (JWT) 3
1.6.2 Basic authentication 3
1.7 Document Conventions 3
1.7.1 Abbreviated URLs 3
1.7.2 Examples 3
2 API Resources and Methods 5
2.1 Sessions 6
2.1.1 /sessions/login 6
2.1.2 /sessions/logout 7
2.2 System 8
2.2.1 /system/info 8
2.2.2 /system/reboot 9
2.2.3 /system/shutdown 9
2.2.4 /system/factoryDefault 10
2.2.5 /system/firmware/version 11
2.2.6 /system/firmware/download 11
2.2.7 /system/firmware/install 13
2.2.8 /system/firmware/downloaded 13
2.2.9 /system/config/save 14
2.2.10 /system/config/restore 15
2.2.11 /system/dateAndTime 17
2.2.12 /system/dateAndTime/timezones 18
2.2.13 /system/general 19
2.3 Security Profile 20
2.3.1 /security 20
2.4 Network 24
2.4.1 /network/settings 24
2.4.2 /network/devices[/<INT>] 25
2.5 Serial Ports 27
2.5.1 /serialPorts[/<PORT#>] 27
2.6 Pluggable Devices 30
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | iii

2.6.1 /pluggableDevices[/<NAME>] 30
2.6.2 /pluggableDevices/<NAME>/setConsole 32
2.6.3 /pluggableDevices/<NAME>/eject 33
2.6.4 /pluggableDevices/<NAME>/delete 34
2.7 Authentication 34
2.7.1 /authentication 34
2.7.2 /authentication/ldap 35
2.7.3 /authentication/radius 36
2.7.4 /authentication/tacacs 37
2.8 Users 38
2.8.1 /users[/<NAME>] 38
2.9 Resources 40
2.9.1 /resources 40
Appendices 45
Appendix A: cURL 45
Appendix B: Python 46
Appendix C: Helper Script 47
Appendix D: Certificate Verification 48
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | iv

1 OVERVIEW
This document explains the external (remote web) Application Programming Interface (API) services and
schema for the Avocent® ACS800/8000 Advanced Console System.
Remote web API services allow any third-party software system to integrate with the console system
software. This integration enables your applications, tools and systems to manage information in the
console system software and provides support for accessing information, performing unit control and
adding events to the event log.
1.1 Base URL
The base URL format is: https://<IP_ADDRESS>:<PORT_NUMBER>/api/v1/
NOTE: The version number is mandatory to allow for future enhancements and expansion.
The HTTPS port number is 48048 by default. HTTP may also be used with a default port number of 8080
but this is completely insecure. By default, HTTP access is disabled and only HTTPS access is enabled. An
admin can enable or disable HTTP and HTTPS access as well as change their respective port numbers.
NOTE: Changes to these settings will restart the RESTful API server and disconnect any existing
RESTful sessions.
1.2 Methods
The following basic HTTP methods are supported.
METHOD DESCRIPTION
POST
Used to create a new resource (specified in the JSON body) underneath the resource specified by the URL. The resource created is
returned in the body or enough information is returned to find the new resource (an ID or URL).
Also used to initiate actions.
GET Requests a representation of the specified resource. This has no other effects other than reading and returning the data.
PUT
This method is used to modify an existing resource (specified by the URL) with the data present in the JSON body. Only the items
present in the body are modified and the rest are left unchanged. The response code is typically 204 (Status No Content) with no
content in the body unless otherwise requested by a specific parameter.
PATCH This method is similar to the PUT method, but is typically intended only for modifying a portion of the specified resource. PUT in this API
is also allowed to only modify a portion of a resource, so PATCH is included just for those applications that already use it.
DELETE This method deletes the resource specified by the URL.
Table 1.1 Supported HTTP Methods
1.3 Body
The body for GET/POST/PUT/PATCH requests uses JSON syntax. This means that the "Content-Type"
and "Accept" headers should be set to application/json. All parameters and values are case sensitive.
Parameters that are string types must have their value enclosed in quotes even if the content is
numerical, as is the case with some of the parameters that have a dropdown menu in the WebUI. All
parameters are string type unless otherwise specified to be integer, array or something else.
1.4 Query Parameters
The fields query parameter is supported for many resources to enable the user to limit the fields that are
returned. For example:GET /serialPorts?fields=pinout,speed.
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 1

This example above would return an array of all the serial ports with only the speed and pinout fields of
each.
Sub-fields such as speed which is under the "physical" portion of a serialPort are unique and may be
specified without any reference to the parent (physical in this example).
1.5 Response Codes
The API utilizes standard HTTP response codes where appropriate. The following table lists the response
codes supported and typical usage.
RESPONSE
CODE MEANING DESCRIPTION
200 OK Success Returned for successful request. Response may include a JSON body with results.
201 Created Created Returned for successful request that has resulted in the creation of a new resource.
204 No
Content Success Returned for successful request. Response does NOT include a JSON body with results.
400 Bad
Request Failure Returned on failed request. Response includes a JSON encoded list of errors for one or more of the problematic parameters. May also indicate other system errors.
401
Unauthorized
Authorization
Failure Returned for request without the proper authentication.
404 Not
Found APInot active Returned for request where the resource is not found. Response typically includes a JSON encoded error structure with more error detail.
Table 1.2 Response Code Descriptions
1.5.1 Error information
In addition to returning a failing response code, error information is returned in the response body
providing more detail to the user. This response is in JSON format as follows:
{
"error": {
"code": "AE003",
"message": "invalid parameter",
"detail": "bob"
}
}
NOTE: Not all error information responses will include the detail field.
1.5.2 Ignored keys
If unknown keys are sent as part of the JSON body of a PUT or PATCH request, then they will be ignored
by the API. This is part of the RESTful way of supporting different devices and different versions of API
implementation. If a device doesn't understand or support something, it is permitted to ignore it.
Rather than ignoring mis-spellings and leaving the caller to wonder why a parameter didn't get set, the
API will return a response body along with the 200 response code that contains a successful response
message along with a list of keys that were ignored. This permits the caller to look for this information if so
desired.
{
"status": "success", "ignoredKeys": [
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 2

"datea", "timee"
]
}
If a parent key is ignored, then all children below it are ignored but are not processed and listed as ignored
keys.
Even if all keys are ignored, success will still be returned because the command didn't fail to write
anything that it attempted.
1.6 Authentication
The ACS RESTful API supports two different methods of authentication: JSON Web Token (JWT) and
basic authentication.
1.6.1 JSON Web Token (JWT)
The JWT method allows for the user to login and authenticate using the /sessions/login resource, passing
it a valid appliance username and password in the JSON body of the request. If successful, the appliance
returns a JWT that must be included in the header of all subsequent requests as the "Authorization" key
with a value of "Bearer <JWT>".
This minimizes some of the appliance authentication overhead on each individual RESTful API call. The
JWT remains valid for 60 minutes. A GET on the /sessions/refresh resource can be done before the token
expires to refresh and provide a new token.
NOTE: The username and password are transmitted unencrypted as plain text in the original
/sessions/login request body, so it is recommended to use HTTPS for RESTful communications.
1.6.2 Basic authentication
Basic authentication takes a username/password pair and encodes it using base64. This resulting base64
value must then be included in every request header as the "Authorization" key with a value of "Basic
<BASE64_VALUE>". Each such request is then authenticated by the appliance, the request is executed,
and the session terminated.
NOTE: The username/password pair are transmitted unencrypted (base64 is NOT secure encryption)
in every request, so it is recommended to use HTTPS for RESTful communications.
1.7 Document Conventions
1.7.1 Abbreviated URLs
Throughout this document, the URLs in the examples will generally be abbreviated to just show the
portion of the URL after the /v1. This is only to make the document more readable. The full URL is
necessary when using the API. For example:
/system/info is shown instead of https://10.20.30.40:48048/api/v1/system/info
1.7.2 Examples
In the RESTful examples throughout the document, what is sent in the request is shown in bold type
including both URL components and message body. The response body is shown in normal type. For
example:
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 3

POST /sessions/login {"username": "admin", "password": "avocent"}
{
"token":"eyJhbGciOiJIUzI1NiIsInR…fVzCM"
}
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 4

2 API RESOURCES AND METHODS
The following table is an outline of the URLs that the API provides in this release.
URL METHOD DESCRIPTION
Sessions
/sessions/login POST Login with username and password, creating an API session, and returning a
token in JSON body.
/sessions/logout POST Exit and cleanup the current session.
/sessions/refresh GET Using the token provided, obtain a new refreshed token which is returned in the
JSON body response.
System
/system/info GET Read basic system info such as serial number and type.
/system/reboot POST Reboots the appliance. Returns immediately.
/system/shutdown POST Shutdown the appliance. Returns immediately.
/system/factoryDefault POST Reset the appliance to the factory defaults and reboot.
/system/firmware/version GET Returns version information of firmware, bootcode, and date of build.
/system/firmware/download POST Download a firmware image file to the appliance using ftp, sftp or scp.
/system/firmware/install POST Installs a previously downloaded firmware image file.
/system/firmware/downloaded GET Returns the version information of a previously downloaded firmware file.
/system/config/save POST Save the appliance configuration to a file.
/system/config/restore POST Restore the appliance configuration from a saved file.
/system/dateAndTime
GET
PUT
PATCH
Read and configure system time parameters.
/system/dateAndTime/timezones GET Return a list of all recognized timezones.
/system/general
GET
PUT
PATCH
Read and configure general system parameters including onlineHelp, language,
banner, etc.
Security
/security
GET
PUT
PATCH
Read and configure various security profile parameters.
Network
/network/settings
GET
PUT
PATCH
Read and configure various appliance specific network parameters.
/network/devices
/network/devices/<ETH#>
GET
PUT
PATCH
Read and configure network device specific parameters: method (dhcp or static),
IP address, netmask, gateway, etc.
Ports
/serialPorts GET
Read and configure various serial port parameters: status, pinout, parity, profile,
etc.
/serialPorts/<PORT#>
GET
PUT
PATCH
Pluggable
/pluggableDevices
/pluggableDevices/<NAME> GET Return a list of attached pluggable devices and their details or return details on the named pluggable device.
/pluggableDevices/<NAME>/eject POST Eject the specified device so that it is safe to remove.
Table 2.1 URL Descriptions
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 5

URL METHOD DESCRIPTION
/pluggableDevices/<NAME>/delete POST Delete the specified device after having unplugged it.
/pluggableDevices/<NAME>/setConsole POST Setup the specified pluggable device as a console port.
Authentication
/authentication/
GET
PUT
PATCH
Read and configure general appliance authentication parameters.
/authentication/dsview
/authentication/kerberos
/authentication/ldap
/authentication/radius
/authentication/tacacs
GET
PUT
PATCH
Read and configure authentication parameters specific to each type of
authentication server.
Users
/users
/users/<NAME>
GET
PUT
PATCH
POST
DELETE
Read and configure user specific parameters, including listing all users, adding a
user, and editing existing users.
Resources
/resources GET Return a list of available API resources.
2.1 Sessions
2.1.1 /sessions/login
This action establishes a connection given username and password provided in the JSON body using the
configured authentication of the appliance.
A web token is returned that is to be sent in the header of ALL subsequent requests as the
"Authorization" key with a value of "Bearer <TOKEN>".
An alternative to this login session is to send a base64 encoded username/password pair in every API
request using an "Authorization" key with a value of "Basic <BASE64_VALUE>" as detailed in section 1.6.
Methods
POST
Parameters
PARAMETER DESCRIPTION
username Valid username of an account on the appliance. (root, admin, etc.)
password Valid password for the specified username.
Query
None
Response Body
JSON object
Response Codes
200 OK
401 Not Authorized
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 6

40x Failure
Examples
POST /sessions/login {"username": "admin", "password": "avocent"}
{
"token":"eyJhbGciOiJIUzI1NiIsInR…fVzCM"
}
POST /sessions/login {"username": "bad", "password": "bad"}
{
"error": {
"code": "AE017",
"message": "user authentication failed"
}
}
2.1.2 /sessions/logout
This action invalidates the web token accompanied with it in the header and removes the associated API
session from the appliance. Subsequent use of the web token will be unsuccessful.
Methods
POST
Parameters
None
Query
None
Response Body
JSONobject
Response Codes
200 OK
40x Failure
Examples
POST /sessions/logout
{
"logout": "OK",
"username": "root"
}
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 7

2.2 System
2.2.1 /system/info
This resource provides access to read only system information about the appliance’s identity, versions,
power and CPU information.
Methods
GET
Parameters
PARAMETER DESCRIPTION
serialNumber Serial number assigned to the appliance at the factory.
type Description of the type of unit including model number with port count, power supplies, and modem presence.
Example: ACS8048 with single power supply
bootcode Version number of the installed bootcode.
Example: 1.17
firmware Full version number of the installed firmware.
Example: 1.3.75.2779+551+28+11
firmwareDate Date of the installed firmware.
Example: Sep 1 2016 – 04:07:14
bootedFrom Identifies whether the appliance is currently booted from hardware (internal Flash) or network.
powerSupply1 Status of power supply 1: on/off
powerSupply2 Status of power supply 2, if present: on/off
cpu Description of the cpu: ARMv7 Processor rev 0 (v71)
cores Number of cores in the cpu: integer 2
Query
Fields are supported for all parameters
Response Body
JSONobject
Response Codes
200 OK
400 Bad request
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 8

Examples
GET /system/info
{
"serialNumber": "1234567890",
"type": "ACS8048 with single power supply",
"bootcode": "1.17",
"firmware": "1.3.75.2779+551+28+11",
"firmwareDate": "Sep 1 2016 – 04:07:14",
"bootedFrom": "hardware",
"powerSupply1": "on",
"cpu": "ARMv7 Processor rev 0 (v7l)",
"cores": 2
}
2.2.2 /system/reboot
This action causes the appliance to reboot.
Methods
POST
Parameters
None
Query
None
Response Body
JSONobject
Response Codes
200 OK
40x Failure
Examples
POST /system/reboot
{
"status": "initiated reboot"
}
2.2.3 /system/shutdown
This action causes the appliance to shut down.
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 9

Methods
POST
Parameters
None
Query
None
Response Body
JSONobject
Response Codes
200 OK
40x Failure
Examples
POST /system/shutdown
{
"status": "initiated shutdown"
}
2.2.4 /system/factoryDefault
This action restores the appliance to the factory default and reboots the appliance.
Methods
POST
Parameters
None
Query
None
Response Body
JSONobject
Response Codes
200 OK
40x Failure
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 10

Examples
POST /system/factoryDefault
{
"status": "initiated factoryDefault"
}
2.2.5 /system/firmware/version
This resource provides information about the currently installed and running firmware, including build
date and version numbers of various components.
Methods
GET
Parameters
PARAMETER DESCRIPTION
version Full version number of the installed firmware. Example: 1.3.75.2779+551+28+11
bootVersion Version number of the installed bootcode. Example: 1.17
date Date of the firmware build. Example: Aug 12 2017 – 09:12:24
Query
None
Response Body
JSON object
Response Codes
200 OK
400 Bad Request
Examples
GET /system/firmware/version
{
"version": "1.3.75.2779+551+28+11",
"bootVersion": "1.17",
"date": "Aug 12 2017 – 09:12:24"
}
2.2.6 /system/firmware/download
This action causes the appliance to download the firmware file specified in preparation for subsequent
firmware updating. The action does not return until the file download has completed or fails. Depending
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 11

on the network speed, this could take a couple minutes.
Methods
POST
Parameters
PARAMETER DESCRIPTION
protocol Specifies the protocol to use to download file: ftp/scp/sftp.
ipAddress The IP address of the remote server from which to download the file.
username The username to access the remote server.
password The password to access the remote server.
directory The directory path on the remote server, typically relative to the ftp root directory.
filename The filename of the firmware file on the remote server.
Query
None
Response Body
JSONobject
Response Codes
200 OK
400 Bad Request
Examples
POST /system/firmware/download
{
"protocol": "ftp",
"ipAddress": "10.20.30.80",
"username": "anonymous",
"password": "anonymous",
"directory": "pub/firmware/",
"filename": "firmware_acs8_1_2_9.fl"
}
Response is:
{
"status": "download successful",
"firmware": {
"version": "1.2.9.2449+540+23+11",
"date": "03/01/17"
}
}
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 12

2.2.7 /system/firmware/install
This action causes the appliance to install a previously downloaded firmware image into flash memory.
This request does not return until the installation is complete, which may take up to two minutes.
Methods
POST
Parameters
None
Query
None
Response Body
JSONobject
Response Codes
200 OK
400 Bad Request
Examples
POST /system/firmware/install
{
"status": "install successful",
"firmware": {
"version": "1.2.9.2449+540+23+11",
"date": "03/01/17"
}
}
2.2.8 /system/firmware/downloaded
This resource provides information about a firmware image that has previously been downloaded to the
appliance.
Methods
GET
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 13

Parameters
PARAMETER DESCRIPTION
version Full version number of the firmware file.
Example: 1.2.9.2449+540+23+11
date Date of the build of the firmware file.
Example: 03/01/17
Query
None
Response Body
JSONobject
Response Codes
200 OK
400 Bad Request
Examples
GET /system/firmware/downloaded
{
"version": "1.2.9.2449+540+23+11",
"date": "03/01/17"
}
2.2.9 /system/config/save
This action saves the system configuration of the appliance.
This command does not return until the save is complete, which may take several minutes depending
upon the format.
NOTE: XML format is not supported in the API.
Methods
POST
Parameters
PARAMETER DESCRIPTION
format Format to save the configuration in. Default is cli if nothing is specified. Otherwise choose from: cli/compressed
where Where to save the file, either to local appliance file system or a remote server: local/remote.
protocol Protocol used to transfer the file to a remote server: ftp/scp/sftp.
ipAddress IP Address of the remote server.
username Username of the account to use on the remote server.
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 14

PARAMETER DESCRIPTION
password Password for the specified username on the remote server. Defaults to "anonymous" if none is provided.
directory
Directory where the file is to be written. If the directory starts with "/", then it is considered an absolute path. Otherwise the
directory is relative to /mnt/hdUser/backup for local, which is the default location of local configuration files, or relative to the
specified protocol's configured base directory on the remote server.
filename Filename to use for the saved configuration file.
Query
None
Response Body
JSONobject
Response Codes
200 OK
400 Bad Request
Examples
POST /system/config/save
{
"format": "cli",
"where": "remote",
"protocol": "ftp",
"ipAddress": "10.20.30.70",
"username": "anonymous",
"password": "anonymous",
"directory": "pub",
"filename": "myconfig.cli"
}
Response is:
{
"status": "backup configuration saved as cli config filename:
pub/myconfig.cli"
}
2.2.10 /system/config/restore
Restores the appliance configuration from a specified file.
NOTE: XML format is not supported in the API.
Methods
POST
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 15

Parameters
PARAMETER DESCRIPTION
where Where the configuration file is located: local/remote.
protocol Protocol used to retrieve remote file: ftp/scp/sftp.
ipAddress IP Address of the remote server.
username Username of the account to use on the remote server.
password Password for the specified username on the remote server. Defaults to "anonymous" if none is provided.
directory
Directory where the file is located. If the directory starts with "/", then it is considered an absolute path. Otherwise the directory is
relative to /mnt/hdUser/backup for local, which is the default location of local configuration files, or relative to the ftp/scp/sftp
configured base directory on the remote server.
filename Name of the configuration file to restore.
Query
None
Response Body
JSONobject
Response Codes
200 OK
400 Bad Request
Examples
POST /system/config/restore
{
"where": "remote",
"protocol": "ftp",
"ipAddress": "10.20.30.70",
"username": "anonymous",
"password": "anonymous",
"directory": "pub",
"filename": "myconfig.cli"
}
Response is:
{
"status": "backup configuration restored from cli config filename:
pub/myconfig.cli"
}
The following command restores from the local file /mnt/hdUser/backup/myconfig.cli, which is sitting in
the default local directory for backup configuration files. The directory parameter is not actually needed
in this case, as it is assumed to be blank if not provided.
POST /system/config/restore
{
"where": "local",
"directory": "",
"filename": "myconfig.cli"
Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 16