Vertiv Avocent ACS800, Avocent ACS8000 User Manual

Download

Page 1

Avocent® ACS800/8000 Advanced Console System

Application Programming Interface (API)

User Guide

Page 2

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.

Page 3

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

Page 4

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

Page 5

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.

Table 1.1 Supported HTTP Methods

METHOD DESCRIPTION

Used tocreate a new resource (s pecifiedin the JSON body) underneaththe resource specified by the URL. The resource created is

POST

GET Requests a representation of the specified r esource. This has no other effects other than reading and returning the data.

PUT

PATCH

DEL ETE This method deletes the resource specified by the URL.

returned in the body or enough informationis returnedto find the new resource (an ID or URL).

Also used to initiate actions.

This method is used to modify an existing resource (specified by the URL) with the data pres ent in the JSON body. Only the items present in the body ar e modifiedand the rest are left unchanged. The response code is typically 204 (S tatus No Content) withno content in the body unless otherwise requested by a specific parameter.

This method is similar tothe PUT method, but is typically intended only for modifying a portion of the specified r esource. PUT in this A PI is also allowed to only modify a portion of a r esource, so PATCH is included just for those applications that already use it.

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

Page 6

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.

Table 1.2 Response Code Descriptions

RESPONS E CODE

200 OK Success Returnedfor successful request. Response may include a JSON body with res ults.

201 Created Created Returned for successful r equest that has resulted in the cr eationof a new resource.

204 No Content

400 Bad Request

401 Unauthorized

404 Not Found

MEANING DESC RIPTION

Success Returnedfor successful request. Response does NOT include a JSON body with results.

Failure

Authorization Failure

APInotactive

Returnedon failed request. Response includes a JSON encodedlist of err ors for one or more of the problematic parameters. May also indicate other s ystem errors.

Returnedfor request withoutthe proper authentication.

Returnedfor request where the resource is not found. Response typically includes a JSON encoded error structure withmore error detail.

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

Page 7

"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

Page 8

POST /sessions/login {"username": "admin", "password": "avocent"}

{ "token":"eyJhbGciOiJIUzI1NiIsInR…fVzCM" }

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 4

Page 9

2 API RESOURCES AND METHODS

The following table is an outline of the URLs that the API provides in this release.

Table 2.1 URL Descriptions

URL METHOD DESC RIPTION

Sessions

/ses sions/login POST

/ses sions/logout POST Exit and cleanup the curr ent session.

/ses sions/r efres h GET

System

/sys tem/info GET Read basic system info such as serial number andtype.

/sys tem/reboot POST Reboots the appliance. Returns immediately.

/sys tem/shutdown POST Shutdown the appliance. Returns immediately.

/sys tem/factoryDefault POST Reset the appliance to the factory defaults and reboot.

/sys tem/firmware/ver sion GET Returns versioninformation of firmware, bootcode, and date of build.

/sys tem/firmware/download POST Downloada firmware image file to the appliance usingftp, s ftp or scp.

/sys tem/firmware/install POST Installs a previously downloaded firmware image file.

/sys tem/firmware/downloaded GET Returns the version informationof a previously downloaded firmware file.

/sys tem/config/save POST Save the appliance configuration to a file.

/sys tem/config/restore POST Restore the appliance configuration from a saved file.

/sys tem/dateAndTime

/sys tem/dateAndTime/timezones GET Return a list of all recognized timezones.

/sys tem/general

Security

/security

Network

/network/settings

/network/devices /network/devices/<ETH#>

Ports

/ser ialPorts GET

/ser ialPorts/<PORT#>

Pluggable

/pluggableDevices /pluggableDevices/<NA ME>

/pluggableDevices/<NA ME>/eject POST Eject the specified device s o that it is safe to remove.

GET PUT PATCH

GET

Using the token provided, obtaina new refreshed token which is returned in the JSON body r esponse.

Read and configure system time parameters.

Read and configure general system parameters including onlineHelp, language, banner, etc.

Read and configure various security profile parameters .

Read and configure various appliance specific network parameters.

Read and configure network device specific parameters : method (dhcpor static), IP address , netmask, gateway, etc.

Read and configure various serial port parameters : status, pinout, parity, profile, etc.

Return a list of attachedpluggable devices andtheir details or return details on the named pluggable device.

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 5

Page 10

URL METHOD DESC RIPTION

/pluggableDevices/<NA ME>/delete POST Delete the specified device after havingunpluggedit.

/pluggableDevices/<NA ME>/setConsole POST Setup the specified pluggable device as a console port.

Authentication

/authentication/

/authentication/dsview /authentication/kerberos /authentication/ldap /authentication/radius /authentication/tacacs

User s

/users /users/<NAME>

Resources

/res ources GET Return a list of available API resources .

GET PUT PATCH

GET PUT PATCH POST DEL ETE

Read and configure general appliance authentication parameters.

Read and configure authentication parameters specific to eachtype of authenticationserver.

Read and configure user specific parameters, including listingall user s, adding a user, and editing existingusers .

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 pass word 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

Page 11

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

Page 12

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 DESC RIPTION

serialNumber Serial number assignedto the appliance at the factory.

type

bootcode

firmware

firmwareDate

bootedFrom Identifies whether the appliance is currently bootedfrom hardware (internal Flash) or network.

powerSupply1 Status of power supply 1: on/off

powerSupply2 Status of power supply 2, if pres ent: on/off

cpu Description of the cpu: ARMv7 Processor rev 0 (v71)

cores Number ofcores in the cpu: integer 2

Description of the type of unitincluding modelnumber withport count, power supplies, and modem presence. Example: ACS8048 with single power supply

Version number of the installedbootcode. Example: 1.17

Fullver sion number of the installed firmware. Example: 1.3.75.2779+551+28+11

Date of the installed firmwar e. Example: Sep 1 2016 – 04:07:14

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

Page 13

Examples

GET /system/info

{ "serialNumber": "1234567890", "type": "ACS8048 with single power supply", "bootcode": "1.17", "firmwar e": "1.3.75.2779+551+28+11", "firmwar eDate": "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

Page 14

Methods

POST

Parameters

None

Query

None

Response Body

JSONobject

Response Codes

200 OK

40x Failure

Examples

POST /system/shut down

{ "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

Page 15

Examples

POST /system/f actoryDef ault

{ "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 Fullver sion number of the installed firmware. Example: 1 .3.75.2779+551+28+11

bootVersion Version number of the installedbootcode. 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

Page 16

on the network speed, this could take a couple minutes.

Methods

POST

Parameters

PARAMETER DESCRIPTION

protocol Specifies the protocol to use to downloadfile: ftp/scp/sftp.

ipAddress The IP address of the r emote s erver from which to downloadthe file.

username The username toaccess the remote ser ver.

password The pass word to access the remote server.

directory The directory path on the remote s erver , typically relative to the ftp root directory.

filename The filename of the firmwar e file onthe remote server.

Query

None

Response Body

JSONobject

Response Codes

200 OK

400 Bad Request

Examples

POST /system/f irmware/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", "firmwar e": { "version": "1.2.9.2449+540+23+11", "date": "03/01/17" } }

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 12

Page 17

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/f irmware/install

{ "status": "install successful", "firmwar e": { "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

Page 18

Parameters

PARAMETER DESCRIPTION

version

date

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" }

Fullver sion number of the firmware file. Example: 1.2.9.2449+540+23+11

Date of the buildof the firmware file. Example: 03/01/1 7

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 DESC RIPTION

format Format to save the configuration in. Default is cli if nothing is specified. Otherwise choose from: cli/compressed

where Where tosave 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 A ddress of the remote ser ver.

username Username of the accountto use on the r emote s erver .

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 14

Page 19

PARAMETER DESC RIPTION

password Pass word for the specified username on the remote server. Defaults to"anonymous" if none is provided.

directory

filename Name of the configuration file to restore.

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 defaultlocation of local configuration files, or relative to the ftp/scp/sftp configured base directory on the r emote s erver.

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

Page 21

}

Response is: { "status": "backup configuration restored from cli config filename: myconfig.cli" }

2.2.11 /system/dateAndTime

Gets and sets parameters related to the system’s date and time.

NOTE: Setting the time and date is not permitted when NTP is enabled and will result in an error.

Methods

GET, PUT, PATCH

Parameters

PARAMETER DESCRIPTION

time Current time.

date Current date.

ntp Network Time Protocol. enabled/disabled.

ntpSettings (only valid when ntpis enabled)

ntpServer IP address or name.

ntpServer 2 IP address or name.

timezone Name of the timezone. UTCis the default.

Query

Fields are supported for all parameters.

Response Body

JSONobject

Response Codes

200 OK

204 OKNo Content (for a PUTor PATCH)

400 Bad Request

Examples

GET /system/dateAndTime

{ "time": "18:00:50", "date": "07/12/2017", "ntp": "enabled", "ntpSettings": {

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 17

Page 22

"ntpServer": "10.20.30.40", "ntpServer2": "ntp.pool.org" }, "timezone": "UTC" }

PUT /system/dateAndTime { "ntp": "disabled" } PUT /system/dateAndTime { "time": "05:00:00", "date": "08/01/2017" } PUT /system/dateAndTime { "ntp": "enabled", "ntpSettings": { "ntpServer": "ntp.pool.org", "ntpServer2": "" } } PUT /system/dateAndTime {"timezone": "US/Central"}

2.2.12 /system/dateAndTime/timezones

Gets a list of all the recognized timezones. These values can be used when setting the timezone via the /system/dateAndTime resource.

Methods

GET

Parameters

None

Query

None

Response Body

JSONobject

Response Codes

200 OK

400 Bad Request

Examples

GET /system/dateAndTime/timezones

{

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 18

Page 23

"timezones": [ "Africa/Abidjan", "Africa/Accra", …. "Zulu" ] }

2.2.13 /system/general

Gets and sets general appliance level parameters.

Methods

GET, PUT, PATCH

Parameters

PARAMETER DESC RIPTION

language Language used for ssh, telnet and console port sessions tothe appliance. english/chinese/french/german/japanese/spanish.

onlineHelp

banner Controls whether a login banner is displayed. enabled/disabled.

bannerText

viewer The type of viewer to use when opening serial or appliance sessions. html5/jnlp.

URL for the online help productdocumentation. Default: http://global.avocent.com/us/olh/acs8x/en/index.html.

Text of the login banner to display. It may include specialcharacters for formatting including\t for tabs and\n for newlines. Only shown in the full r eturn body when banner is enabled.

Query

Fields are supported for all parameters.

Response Body

JSONobject

Response Codes

200 OK

204 OK No Content (for a PUT or PATCH)

400 Bad Request

Examples

GET /system/general

{ "language": "english", "onlineHelp": "http://global.avocent.com/us/olh/acs8x/en/index.html", "banner": "enabled", "bannerT ext": "=================================================================== =======\n WARNING! The use of this system is restricted to

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 19

Page 24

authorized users. \n \n All information and communications on this system are subject \n to review, monitoring and recording at any time, without notice\n or permission. Users should have no expectation of privacy.\n========================================================== ================\n", "viewer": "html5" }

PUT /system/general {"bannerText":"==========\n Multiple\n Line\n Banner\n==========\n"}

PUT /system/general {"language":"german","banner":"disabled","viewer":"j nlp"}

2.3 Security Profile

2.3.1 /security

Gets and sets parameters in the security profile of the appliance.

Methods

GET, PUT, PATCH

Parameters

PARAMETER DESCRIPTION

idleTimeout

Session idle timeout in seconds: integer. 0 disables the timeout entirely, otherwise 90 seconds is the minimum accepted value.

rpc RPC service: enabled/disabled

pluggableDevices Pluggable device detection: enabled/disabled

pluggableStorage Pluggable storage devices: enabled/disabled

Serial port access can be configured to allow access for all users,

access

or allow the configuration of group and user-specific authorizations to restrict access: all/user_group

allAccessSettings (only valid when access is all)

session

Sessions can be set to allow single or multiple session read/write: single/multiple

killMultiSession Enables a user to kill other sharers of a session: enabled/disabled

sendMessageMultiSession

powerControl

dataBufferManagement

Enables a user to send a message to other users sharing a session: enabled/disabled

Enables a user to control power of a multi session: enabled/disabled

Enables a user for data buffer management of a session: enabled/disabled

restfulClientMenu Enables the restfulClient menu: enabled/disabled

eraseFlash

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 20

Control whether entire flash config is erased on a factory default:

Page 25

PARAMETER DESCRIPTION

enabled/disabled

bootp Controls bootp configuration retrieval: enabled/disabled

bootpSettings (only valid when bootp is enabled)

bootpInterface Specifies network interface used by bootp: eth#

liveConfigurationRetrieval

sshUserPass

profile

Enables live configuration retrieval any time DHCP renews: enabled/disabled

Controls whether SSH allows authentication via username/password: enabled/disabled

Sets the appliance security profile: open/moderate/secure/custom

customProfile (only valid when profile is custom)

telnet Telnet service: enabled/disabled

ftp FTP service: enabled/disabled

snmp SNMP service: enabled/disabled

ipsec IPSec: enabled/disabled

answerlcmp Answer ICMP message: enabled/disabled

sshVersion SSH Version: 1 / 2 / 1|2 / 2|1

sshPort SSH TCP port number (default 22): integer

sshRootAccess SSH allow root access: enabled/disabled

sshCipherLevel SSH minimum cipher and mac suite level: low/high

httpSession HTTP sessions: enabled/disabled

httpSettings (only valid when httpSession is enabled)

httpPort HTTP Port number (default 80): integer

httpsSession HTTPS sessions: enabled/disabled

httpsSettings (only valid when httpsSession is enabled)

httpsTlsVersion

HTTPS TLS version: 1.1 / 1.1|1.2 / 1.2 / 1.1+1.0 / 1.1|1.2+1.0 /

1.2+1.0

httpsCipherLevel HTTPS minimum cipher suite level: low/medium/high

httpsPort HTTPS Port number (default 443): integer

redirectHttp Redirect HTTP/HTTPS: enabled/disabled

consolePort Appliance console port: enabled/disabled

apiHttpAccess Allow RESTful API access via HTTP: enabled/disabled

apiHttpSettings (only valid when apiHttpAccess is enabled)

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 21

Page 26

PARAMETER DESCRIPTION

apiHttpPort HTTP Port number for RESTful API access: integer

apiHttpsAccess Allow RESTful API access via HTTPS: enabled/disabled

apiHttpsSettings (only valid when apiHttpsAccess is enabled)

apiHttpsPort HTTPS Port number for RESTful API access: integer

FIPS 140-2 module: enabled/disabled

fips

NOTE: Changing the fips value will cause the appliance to reboot.

dsview Allow appliance to be managed by DSView: enabled/disabled

Query

Fields are supported for all parameters.

Response Body

JSONobject

Response Codes

200 OK

204 OK No Content (for a PUT or PATCH)

400 Bad Request

NOTE: Pluggable Storage Device changes will be effective after reboot only.

NOTE: Disabling Pluggable Device Detection will be effective after reboot only.

NOTE: Profile changes affecting HTTP and HTTPS will terminate all http sessions.

NOTE: Disabling the Console Port can make the appliance inaccessible and should only be done in the most extreme cases.

NOTE: API changes made while using the API may terminate the API session.

Examples

GET /security

{ "idleTimeout": 63955, "rpc": "disabled", "pluggableDevices": "enabled", "pluggableStorage": "disabled", "access": "all", "allAccessSettings": { "session": "multiple", "killMultiSession": "enabled", "sendMessageMultiSession": "enabled", "powerControl": "enabled", "dataBufferManagement": "enabled", "restfulClientMenu": "enabled"

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 22

Page 27

}, "eraseFlash": "disabled", "bootp": "enabled", "bootpSettings": { "bootpInterface": "eth0", "liveConfigurationRetrieval": "enabled" }, "sshUserPass": "enabled", "profile": "custom", "customProfile": { "telnet": "enabled", "ftp": "disabled", "snmp": "disabled", "ipsec": "disabled", "answerIcmp": "enabled", "sshVersion": "1|2", "sshPort": 22, "sshRootAccess": "enabled", "sshCipherLevel": "low", "httpSession": "enabled", "httpSettings": { "httpPort": 80 }, "httpsSession": "enabled", "httpsSettings": { "httpsTlsVersion": "1.1|1.2+1.0", "httpsCipherLevel": "low", "httpsPort": 443, "redirectHttp": "disabled" } }, "consolePort": "enabled", "apiHttpAccess": "enabled", "apiHttpSettings": { "apiHttpPort": 8080 }, "apiHttpsAccess": "enabled", "apiHttpsSettings": { "apiHttpsPort": 48048 }, "fips": "disabled", "dsview": "enabled" }

GET /security

{ "idleTimeout": 63955, "rpc": "disabled", "pluggableDevices": "disabled", "access": "user_group", "eraseFlash": "disabled", "bootp": "disabled", "sshUserPass": "enabled", "profile": "open", "consolePort": "enabled", "apiHttpAccess": "disabled", "apiHttpsAccess": "disabled", "fips": "disabled", "dsview": "disabled" }

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 23

Page 28

GET /security?fields=idleTimeout

{ "idleTimeout": 300 }

GET /security?fields=rpc,pluggableDevices

{ "rpc": "disabled", "pluggableDevices": "enabled" }

PUT /security {"customProfile": {"httpsSettings": {"httpsPort": 444, "redirectHttp": "disabled"}}}

2.4 Network

2.4.1 /network/settings

Get and set various network parameter settings of the console system.

NOTE: When configuring failoverSettings, the primary and secondary interface cannot be set to the same value, so when swapping them the changes need to be made in one PUT command rather than separately.

Methods

GET, PUT, PATCH

Parameters

PARAMETER DESCRIPTION

hostname User definedname of the appliance on the network. Defaults toformat of "ACS80xx-<serialNumber>"

primaryDns IP address of the primary DNS server.

secondaryDns IP address of the s econdary DNS server .

domain Domain address. Default: corp.avocent.com

search Search address. Default: corp.avocent.com

lldp Link L ayer Discovery Protocol: enabled/disabled

ipv6 IPv6 support: enabled/disabled

ipv6Settings (only valid when ipv6 is enabled)

dhcpv6Dns Get the IPv6 D NS ser ver address from DHCPv6: enabled/disabled

dhcpv6Domain Get the IPv6 D omain name from DHCPv6: enabled/disabled

multipleRouting

failoverSettings ( only valid when multipleRoutingis enable_network_failover)

primaryInterface Primary network interface: eth#

secondaryInterface Secondary network interface: eth#

trigger

unreachableIp IP A ddress to probe when trigger is unreachable_ip_address.

dhcpv6Domain Get the IPv6 D omain name from DHCPv6: enabled/disabled

Enable network failover or IPv4 Multiple Routing Tables: none/enable_network_failover/enable_multiple_ routing

Failover trigger: primary_interface_down/unreachable_primary_default_gateway/ unreachable_ip_ address/unreachable_dsview

Query

Fields are supported for all parameters.

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 24

Page 29

Response Body

JSONobject

Response Codes

200 OK

204 OK No Content (for a PUT or PATCH)

400 Bad Request

Examples

GET /network/settings

{ "hostname": "ACS8048-123456789", "primaryDns": "10.20.30.40", "secondaryDns": "10.20.30.50", "domain": "corp.avocent.com", "search": "corp.avocent.com", "lldp": "disabled", "ipv6": "enabled", "ipv6Settings": { "dhcpv6Dns": "disabled", "dhcpv6Domain": "disabled" }, "multipleRouting": "enable_network_failover", "failoverSettings": { "primaryInterf ace": "eth0", "secondaryInterface": "eth1", "trigger": "unreachable_ip_address", "unreachableIp": "10.20.30.50" } }

PUT /network/settings {"hostname": "myhostname"}

2.4.2 /network/devices[/<INT>]

Get and set various network device parameters for individual network interfaces.

Methods

GET, PUT, PATCH

Parameters

PARAMETER DESCRIPTION

interface Read-only name of the network interface: eth0, eth1, etc.

isPrimar y Read-only. Identifies if this is theprimary interface: enabled/disabled

status Status of the interface: enabled/disabled

ipv4Method Method used toconfigure IPv4: dhcp/static/unconfigured

ipv6Method Method used toconfigure IPv6: s tateless/dhcpv6/static/unconfigured

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 25

Page 30

PARAMETER DESCRIPTION

mac Read only hardware mac address of this interface. Example: 00:e0:86:01:02:03

ipv4Static (only valid when ipv4Method is static)

ipv4Address

ipv4Mask

ipv4Gateway

ipv6Static (only valid when ipv6Method is static)

ipv6Address

ipv6PrefixLength

IPv4 Address for static configuration. Example: 10.20.30.40

Subnetmask for static configuration. Example: 255.255.255.0

Gateway to use for static configuration. Example: 10.20.30.1

IPv6 Address for static configuration. Example: fd00:0024:0000:0000:02e0:86ff:fe10:2c3b

IPv6 Prefix L ength for static configuration. Example: 112

Query

Fields are supported for all parameters.

Response Body

JSONobject

Response Codes

200 OK

204 OK No Content (for a PUT or PATCH)

400 Bad Request

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 26

Page 31

Examples

GET /network/devices

{ "devices": [ { "interface": "eth0", "isPrimary": "enabled", "status": "enabled", "ipv4Method": "dhcp", "ipv6Method": "stateless", "mac": "00:11:22:33:44:55", }, { "interface": "eth1", … } ] }

GET /network/devices/et h1

{ "interface": "eth1", "isPrimary": "disabled", "status": "enabled", "ipv4Method": "static", "ipv6Method": "stateless" "mac": "00:11:22:33:44:56", "ipv4Static": { "ipv4Address": "10.20.30.40", "ipv4Mask": "255.255.255.0", "ipv4Gateway": "" } }

2.5 Serial Ports

2.5.1 /serialPorts[/<PORT#>]

Get parameters for one or all serial ports. Set various serial port parameters for one serial port.

Methods

GET, PUT, PATCH

Parameters

PARAMETER DESCRIPTION

port Read-only port number

profile

deviceName Read-only device name assigned by operatingsystem. E xamples: ttyS1, ttyUSB0, ttyACM0

status Port status: enabled/disabled

physical (only valid when profile is cas, power or s ocket_client

pinout Serial port pinout: auto/cisco/cyclades/rs422/rs485

speed Serial port s peed: integer 1200/2400/4800/9600/19200/38400/57600/115200/230400

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 27

Port profile: cas /power/dial_in/dial_out/socket_client/unconfigured Note: dial_inand dial_out ar e not s upported at this time, and unconfigured is a readonly s tate that cannot be s et.

Page 32

PARAMETER DESCRIPTION

parity Parity: even/odd/none

dataBits Number of data bits: integer 5/6/7/8

stopBits Number of stopbits: integer 1/2

flowControl Flow control mechanism: none / hardware / software / rxon_software / txon_software

cas (only valid when profile is cas)

name

autoDiscovery

speedAutoDetection Enable speed auto detection to try todiscover the s peed of the s erial port: enabled/disabled

protocol

authentication

textHotKey

powerHotKey

restfulHotKey

telnetAliasPort TCP port used to connect directly to a ser ial port using Telnet protocol. Default: 7000+port number

sshAliasPort TCP port used to connect directly to a serial port using SSH protocol. Default: "" ( not configured)

rawModeAliasPort TCP port used to connect directly to a ser ial port using r aw socket for connection. Default: "" (notconfigured)

ipv4AliasAddress IPv4 address used to connect directly to a serial port.

ipv4AliasInterface Interface as sociated with the ipv4AliasAddres s. eth#

ipv6AliasAddress IPv6 address used to connect directly to a ser ial port.

ipv6AliasInterface Interface associatedwith the ipv6AliasAddress. eth#

dcdSensitivity Allow s ess ion only if DCD is on. enabled/disabled

autoAnswer

dtrMode

dtrOffInterval Interval used by DTR Mode off_interval in milliseconds: integer, Default: 100.

linefeedSuppress ion Enables the suppression ofthe linefeedcharacter after the carriage r eturn character. enabled/disabled

nullAfterCrSuppression E nables the suppression of the NU LL character after the carriage return character. enabled/disabled

transmissionInterval The interval the port waits to senddata to a remote client in milliseconds: integer

breakSequence

breakInterval Interval for the break signalin milliseconds: integer, Default: 500

multiSess ionMenu

loginNotification Enables the notificationto multi-sess ion user s when a new user logs inor a user logs out. enabled/disabled

infoNotification Displays an informationmessage when a target s ess ion is opened. enabled/disabled

cas/dataBuffering (only valid when profile is cas)

bufferingStatus Enables or disables data buffering. enabled/disabled

bufferingType

User as signed or default name for port. Defaultis the last half ofthe appliance mac address followedby "- p-" and the port number. Example: 10-2c-3d-p-1

Enable auto discovery. The target name will be discovered and will be associatedwiththis serial port. If it fails, the default port name willbe used. enabled/disabled

Hotkey to suspendthe target session and return to the cliprompt. Notavailable for Raw. Default: "^Z" which is Ctrl-Z

Hotkey to suspendthe target session and display the Power ManagementMenu to control the outlets merged to the target. Not available for Raw. Default: "^P" which is Ctrl-P

Hotkey to suspendthe target session and display the RESTfulClient Menu, which is used to send user-defined RESTful actions to a RES Tful ser ver. Default: "" (notconfigured)

Enables processing of inputdata so that when the inputdata matches one input stringconfigured in Auto Answer , the configured output string willbe transmitted to the serial port. enabled/disabled

DTR Mode canbe set to the following: always_on –DTR status willalways be on. normal –This is the default. The DTR status willdepend on the existence of a CAS ses sion. off_interval - when the a CAS session is closed, the DTR will stay down duringthis interval.

An administrator can configure the control key as the break sequence, entering ^ before the letter. Default: ~break

Enables the multi-sess ion menu whenconnectingto a port thatis already beingaccessed by another user. enabled/disabled

Controls the type of data buffering:

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 28

Page 33

PARAMETER DESCRIPTION

local – stores the data bufferingfile on the appliances local file system nfs –stores the data bufferingfile on anNFS server syslog– sends the data to the s yslog s erver dsview –sends the data to the DSView server .

localDevice

timeStamp When enabled, adds the time stampto the data bufferingline for a local or NFS server. enabled/disabled

loginMessage Includes special notification for logins andlogouts indata buffering. enabled/disabled

sessionLogging Controls when data is stored. enabled/disabled

power (only valid when profile is power)

speedAutoDetect

pollingRate The interval in seconds to update information from the PDU: integer, Default: 20

deviceType The type of power device connectedto the s erial port. pdu/ups

pduType

powerCycleInterval The interval in seconds between Off and Onactions for the power cycle command: integer, Default: 15

syslog Whenenabled, the PDU will sendsyslogmess ages tothe appliance. enabled/disabled

buzzer Enables or disables the PDU's buzzer. enabled/disabled

overcurrentProtection When enabled, the software's overcurrent protection is on. enabled/disabled

upsType D efines the type or vendor of the UPS connected to the serial port. gxt4

socketClient (only valid when profile is socket_client)

remoteServer IPv4 or IPv6 address of the remote ser ver.

remoteTcpPort TCP port to be used to establish a connection with a remote s erver .

establishConnection Configure the event thatwill trigger the establishmentof the connection. dcd/always

Whenthe bufferingType is s et to local, this fieldspecifies where on the local system the data bufferingfiles are stored. Options are the built-in memory (mmcblk0) or a connectedUSB storage or S D card location.

Enable speed auto detect for power device. Tries to discover the speedof the attached power device. enabled/disabled

Defines the type or vendor of the PD U connected to the serial port. auto/cyclades/enp/spc/servertech/raritan/apc/eaton

Query

Fields are supported for all parameters.

Response Body

JSONobject

Response Codes

200 OK

204 OK No Content (for a PUT or PATCH)

400 Bad Request

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 29

Page 34

Examples

GET /serialPorts/1

{ "port": "1", "profile": "cas", "deviceName": "ttyS1", "status": "enabled", "physical": { "pinout": "cisco", "speed": 115200, "parity": "none", "dataBits": 8, "stopBits": 1, "flowControl": "none" }, "cas": { "name": "MyServer", "autoDiscovery": "disabled", … } }

GET /serialPorts

{ "serialPorts": [ { "port": "1", "profile": "cas", "deviceName": "ttyS1", "status": "enabled", … }, … { "port": "48", … } ] }

PUT /serialPorts/1 '{"cas":{"sshAliasPort":"8001"}} }

GET /serialPorts/75

{"error": { "code": "AE002", "message": "resource id not found", "detail": "75 is not a valid port id" } }

2.6 Pluggable Devices

2.6.1 /pluggableDevices[/<NAME>]

Read information about the attached pluggable devices (USB, SD card).

Methods

GET

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 30

Page 35

Parameters

PARAMETER DESCRIPTION

deviceName Linux assigned name of the USB device. (ie ttyACM0, ttyUSB0)

deviceType Device's type: console/ethernet/modem/storage/wireless Modem

card Physical device type: "mmc SD" / "usb usbslot"

devicePath USB device path to uniquely identify where the device is in the usb tree.

deviceInfo Device info available via usb device descriptors.

status Current state of the device: inserted/unmounted/ejected

port Serial port number assigned to this device if itis enabledas a console.

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 | 31

Page 36

Examples

GET /pluggableDevices

{ "pluggableDevices": [ { "deviceName": "ttyACM0", "deviceType": "Console", "card": "usb usbslot", "devicePath": "1-1.3", |"deviceInfo": "…", "status": "ejected", "port": "49" }, … ] }

GET /pluggableDevices/tt yUSB0

{ "deviceName": "ttyUSB0", "deviceType": "console", "card": "usb usbslot", "devicePath": "1-1.4", "deviceInfo": "…", "status": "inserted", "port": "49" }

GET /pluggableDevices/mmcblk1p1

{ "deviceName": "mmcblk1p1", "deviceType": "stroage", "card": "mmc SD", "devicePath": "", "deviceInfo": " ", "status": "inserted" }

2.6.2 /pluggableDevices/<NAME>/setConsole

Setup the specified pluggable device as a console port. This adds the device to the list of serial ports by adding a new serial port number. The serial port must then be configured appropriately. This can only be done for devices which show a deviceType of "console".

Methods

POST

Parameters

None

Query

None

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 32

Page 37

Response Body

JSONobject

Response Codes

200 OK

400 Bad Request

Examples

POST /pluggableDevices/ttyUSB0/setConsole

{ "status": "success. ttyUSB0 set to console, port 49" }

2.6.3 /pluggableDevices/<NAME>/eject

Eject the specified pluggable device so that it can be physically removed without causing loss of data. For a storage device, this makes sure the device is not busy.

Methods

POST

Parameters

None

Query

None

Response Body

JSONobject

Response Codes

200 OK

400 Bad Request

Examples

POST /pluggableDevices/sda1/eject

{ "status": "It is now saf e to physically unplug the sda1 device" }

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 33

Page 38

2.6.4 /pluggableDevices/<NAME>/delete

Delete the specified pluggable device after it has been safely ejected and physically unplugged.

Methods

POST

Parameters

None

Query

None

Response Body

JSONobject

Response Codes

200 OK

400 Bad Request

Examples

POST /pluggableDevices/ttyUSB1/delete

{ "status": "success. ttyUSB1 deleted" }

2.7 Authentication

2.7.1 /authentication

Get and set various appliance authentication parameters.

Methods

GET, PUT, PATCH

Parameters

PARAMETER DESCRIPTION

applianceAuthType

singleSignOn

singleSignOnAuthType

Enabling single s ign-onuses the specified single sign-on authentication and no further authentication is needed when access ing a port: enabled/disabled

Query

Fields are supported for all parameters.

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 34

Page 39

Response Body

JSONobject

Response Codes

200 OK

204 OK No Content (for a PUT or PATCH)

400 Bad Request

Examples

GET /authentication/kerberos

{ "server": "10.20.30.41", "realmDomainName": "avocent.com", "domainName": "avocent.com" }

PUT /authentication/kerberos { "server": "10.20.30.41" }

2.7.2 /authentication/ldap

Get and set LDAP authentication parameters.

Methods

GET, PUT, PATCH

Parameters

PARAMETER DESCRIPTION

server IP Address of the L DAP server.

base Bas e.

secure Secure mode: on/off/start_tls

userName The database username.

password The database password for the username.

attributes Login attributes.

Query

Fields are supported for all parameters.

Response Body

JSONobject

Response Codes

200 OK

204 OK No Content (for a PUT or PATCH)

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 35

Page 40

400 Bad Request

Examples

GET /authentication/ldap

{ "server": "10.20.30.42", "base": "", "secure": "off", "userName": "myuser", "password": "mypassword", "attributes": "" }

PUT /authentication/ldap { "server":"10.20.30.42", "secure": "on" }

2.7.3 /authentication/radius

Get and set RADIUS authentication parameters.

Methods

GET, PUT, PATCH

Parameters

PARAMETER DESCRIPTION

firstAuthenticationServer IP Address of the firs t authentication ser ver.

firstAccountingServer IP Address of the first accountingserver .

secondAuthenticationServer IP Addres s of the secondauthentication s erver.

secondAccountingServer IP A ddress of the secondaccountingserver.

secret Secret word or passphrase, applies toboth s ets of ser vers .

timeout Desired number of seconds for server timeout: integer

retries Desired number ofretries: integer

serviceType Enable Service-Type attribute to specify the authorization group: enabled/disabled.

serviceTypeGroups: (only validif serviceType is enabled)

framed Authorization group name for Framed.

callbackLogin Authorization group name for Callback Login.

callbackFramed Authorization group name for Callback Framed.

outbound Authorization group name for Outbound.

administrative Authorizationgroupname for Administrative.

Query

Fields are supported for all parameters.

Response Body

JSONobject

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 36

Page 41

Response Codes

200 OK

204 OK No Content (for a PUT or PATCH)

400 Bad Request

Examples

GET /authentication/radius

{ "firstAuthenticationServer": "127.0.0.1", "firstAccountingServer": "127.0.0.1", "secondAuthenticationServer": "", "secondAccountingServer": "", "secret": "******", "timeout": 3, "retries": 2, "serviceType": "enabled", "serviceTypeGroups": { "login": "", "framed": "", "callbackLogin": "", "callbackFramed": "", "outbound": "", "administrative": "" } }

PUT /authentication/radius {"firstAuthenticationServer": "10.20.30.45","timeout":120}

2.7.4 /authentication/tacacs

Get and set TACACS+ authentication parameters.

Methods

GET, PUT, PATCH

Parameters

PARAMETER DESCRIPTION

firstAuthenticationServer IP Address of the first authentication server.

firstAccountingServer IP A ddress of the first accountings erver .

secondAuthenticationServer IP Address of the secondauthentication s erver.

secondAccountingServer IP Address of the s econd accounting server.

service Service: ppp/raccess /s hell

secret Secret word or passphrase, applies to boths ets of ser vers.

timeout Desired number of seconds for s erver timeout.

retries Des ired number of retries.

version Version: v0 / v0_v1 / v1 / v1_v0

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 37

Page 42

PARAMETER DESCRIPTION

userL evel Enable User-Level attribute to specify the authorization group: enabled/disabled

userL evelGroups: (only valid if user Level is enabled)

userL evel1 Authorization group name for User- Level 1.

... ...

userL evel15 Authorization group name for User- Level 1 5.

Query

Fields are supported for all parameters.

Response Body

JSONobject

Response Codes

200 OK

204 OK No Content (for a PUT or PATCH)

400 Bad Request

Examples

GET /authentication/tacacs

{ "firstAuthenticationServer": "10.20.30.46", "firstAccountingServer": "10.20.30.47", "secondAuthenticationServer": "", "secondAccountingServer": "", "service": "ppp", "secret": "", "timeout": 10, "retries": 2, "version": "v1", "userLevel": "enabled", "userLevelGroups": { "userLevel1": "", … "userLevel15": "" } }

PUT /authentication/tacacs {"firstAut henticationServer": "10.20.30.46", "firstAccountingServer": "10.20.30.47","version": "v0_v1"}

2.8 Users

2.8.1 /users[/<NAME>]

This resource provides the ability to view and edit user settings as well as add new users and delete existing users.

Methods

GET, PUT, PATCH, POST, DELETE

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 38

Page 43

NOTE: For methods PUT, PATCH, POST, and DELETE, the Name is required and not optional. For example:DELETE /users/testuser

Parameters

PARAMETER DE SCRIPTION

name User name. admin and rootexist by default.

settings

password Password for the user.

changePass wordNextLogin Set to force the user tochange the password the next time they log in. enabled/disabled.

userGroups List of groups to which this user belongs: string arr ay.

passwordExpiration

minimumDays The minimum number of days allowed between pass word changes: integer

maximumDays The maximum number of days a password is valid: integer

inactiveDays The number ofinactive days after which a password is considered expired: integer

warningDays The number of days a warning is issued to the user prior toexpiration: integer

accountExpiration Account expirationdate.

Query

Fields are supported for all parameters.

Response Body

JSONobject

Response Codes

200 OK

201 Created

204 OK No Content (for a PUT or PATCH)

400 Bad Request

Examples

GET /users

{ "users": [ { "name": "admin", "settings": { "password": "", … }, { "name": "root", … } ] }

GET /users/admin

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 39

Page 44

{ "name": "admin", "settings": { "password": "", "changePasswordNextLogin": "disabled", "userGroups": [ "admin" ], "passwordExpiration": { "minimumDays": 0, "maximumDays": 99999, "inactiveDays": "", "warningDays": 7 }, "accountExp": "" } }

POST /users

{ "name": "bob", "settings": { "password": "password1234!", "changePasswordNextLogin": "enabled", … } Response is: { "name": "bob", "settings": { "password": "password1234!", … }

2.9 Resources

2.9.1 /resources

This resource provides a list of the available resources and methods.

Methods

GET

Parameters

None

Query

None

Response Body

JSONobject

Response Codes

200 OK

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 40

Page 45

40x Failure

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 41

Page 46

Examples

{ "resources": [ "GET /authentication", "PATCH /authentication", "PUT /authentication", "GET /authentication/dsview", "PATCH /authentication/dsview", "PUT /authentication/dsview", "GET /authentication/kerberos", "PATCH /authentication/kerberos", "PUT /authentication/kerberos", "GET /authentication/ldap", "PATCH /authentication/ldap", "PUT /authentication/ldap", "GET /authentication/radius", "PATCH /authentication/radius", "PUT /authentication/radius", "GET /authentication/tacacs", "PATCH /authentication/tacacs", "PUT /authentication/tacacs", "GET /network/devices", "GET /network/devices/:INT", "PATCH /network/devices/:INT", "PUT /network/devices/:INT", "GET /network/settings", "PATCH /network/settings", "PUT /network/settings", "GET /pluggableDevices", "GET /pluggableDevices/:NAME", "POST /pluggableDevices/:NAME/delete", "POST /pluggableDevices/:NAME/eject", "POST /pluggableDevices/:NAME/setConsole", "GET /resources", "GET /security", "PATCH /security", "PUT /security", "GET /serialPorts", "GET /serialPorts/:PORT", "PATCH /serialPorts/:PORT", "PUT /serialPorts/:PORT", "POST /sessions/login", "POST /sessions/logout", "GET /sessions/refresh", "POST /system/config/restore", "POST /system/config/save", "GET /system/dateAndTime", "PATCH /system/dateAndTime", "PUT /system/dateAndTime", "GET /system/dateAndTime/timezones", "POST /system/factoryDef ault", "POST /system/firmware/download", "GET /system/firmware/downloaded", "POST /system/firmware/install", "GET /system/firmware/version", "GET /system/general", "PATCH /system/general", "PUT /system/general",

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 42

Page 47

"GET /system/info", "POST /system/reboot", "POST /system/shutdown", "GET /users", "POST /users", "DELETE /users/:NAME", "GET /users/:NAME", "PATCH /users/:NAME", "PUT /users/:NAME" ] }

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 43

Page 48

This page intentionally left blank.

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 44

Page 49

APPENDICES

Appendix A: cURL

The cURL command line utility is one method that can be used to communicate with the RESTful API.

Examples:

$ curl -H "Content -Type: application/json" -H "Accept:application/json" http://10.20.30.40:8080/api/v1/sessions/login -d '{"username":"admin","password":"avocent "}'

{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE 1MDQxMTU2NzUsImlkIjoiYWRt aW4iLCJvcmlnX2lhdCI6MTUwNDExMjA3NSwic2lkIjo4fQ.UYGXje5It2hAJryruP3etUaabSh5pfiPP_sXXZF37og" }

$ curl -H "Content -Type: application/json" -H "Accept:application/json" -H

"Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MDQxMTU2NzUsImlkIjoiYWRta W4iLCJvcmlnX2lhdCI6MTUwNDExMjA3NSwic2lkIjo4fQ.UYGXje5It2hAJryruP3et UaabSh5 pfiPP_sXXZF37og" htt p://10.20.30.40:8080/api/v1/system/info

{ "serialNumber": "0012345678", "type": "ACS8048 with single power supply", "bootcode": "1.17", "firmwar e": "1.3.77.2909+551+28+11", "bootedFrom": "hardware", "powerSupply1": "on", "cpu": "ARMv7 Processor rev 0 (v7l)", "cores": 2 }

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 45

Page 50

Appendix B: Python

Python examples are included for both http and https that demonstrate how python can be used to communicate with the RESTful API. These examples run on Python versions 2.7 and 3.5. They require the python "requests" module be installed on the system running python.

An example can be run as follows:

$ python acsapi_example_http.py

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 46

Page 51

Appendix C: Helper Script

A bash shell helper script is provided in the ACS8000 root filesystem under /usr/share/restapi/restapihelper.sh.

This helper script modifies the environment of the running shell to add GET/PUT/POST/PATCH/DELETE shell functions. These functions provide a simple command line interface to demonstrate the API. The shell functions utilize the 'curl' program, which must be installed on the system.

From a bash shell, the script must be "sourced" in order to make the necessary changes to the shell environment which are shown as SETUP parameters and functions.

When sourcing the script, the last parameter is the IPv4 address of the ACS8000. In the example below,

10.20.30.40 is the ACS IP address.

$. restapi-helper.sh 10.20.30.40

Token for Basic Authentication saved in /home/root/.acsrestapi/Basictoken-127.0.0.1

SETUP parameters:

ACSHOST 127.0.0.1

ACSPROTOCOL http http

NOTE:A special means for using the helper script is provided when logged into the appliance as a user in the admin group. The command useapi allows subsequent GET and PUT commands to the logged in appliance.

ACSPORT 8180

ACSTOKENDIR /home/root/.acsrestapi

ACSTOKENTYP Basic (Basic Authentication)

ACSURL /api/v1

ACSDEBUG no

Change your ACSHOST parameter to the ACS IP Address. For example:ACSHOST=192.168.161.10

GET /resource

Example:

GET /serialPorts/2

PUT /resource '{...json parameters...}'

Example:

PUT /serialPorts/2 '{"physical":{"speed":38400}}'

PATCH /resource '{...json parameters...}'

Example:

PATCH /security '{"idleTimeout":0}'

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 47

Page 52

POST /resource '{...json parameters...}'

Example:

POST /sessions/login

'{"username":"admin","password":"avocent"}'

DELETE /resource

Note: These functions automatically prepend '/acs/v1' to the /resource

After running the helper script, the current shell environment can now execute POST, GET and the other commands mentioned above:

$ GET /system/info { "serialNumber": "001234567", "type": "ACS8048 with single power supply", "bootcode": "1.17", "firmwar e": "1.3.77.2909+551+28+11", "firmwar eDate": "Sep 20 2017 – 08:03:39", "bootedFrom": "Hardware", "powerSupply1": "On", "cpu": "ARMv7 Processor rev 0 (v7l)", "cores": 2 }

Appendix D: Certificate Verification

When using HTTPS, in order to avoid certificate verification warnings, the client should be set to ignore SSL certificate verification.

With the python requests package, this is done by adding "verify=False" to the requests command:

>>> requests.get(URL, verify=False)

With cURL the "-k" option is used to disable certificate verification:

$ curl -k -H "Content-Type: application/json" -H "Accept:application/json" https://10.20.30.40:48048/api/v1/sessions/login -d '{"username":"admin","password":"avocent "}'

The restapi-helper script automatically includes the -k option on the underlying curl commands when using https.

Vertiv | Avocent® ACS800/8000 Advanced Console System APIGuide | 48

Page 53

Page 54

VertivCo.com | Vertiv Headquarters, 1050 Dearborn Drive, Columbus, OH, 43085, USA

© 2017 Vertiv Co. Allrights reserved. Vertiv and the Vertiv logo are trademarks or registered trademarks of Vertiv Co. Allother names and logos referred to are trade names, trademarks or registered trademarks of their respective owners. While every precaution has been taken to ensure accuracy and completeness herein, Vertiv Co. assumes no responsibility, and disclaimsallliability, for damages resulting from use of this information or for anyerrors or omissions. Specificationsare subject to change without notice.

590-1814-501B