Seiko SmartCS REST API Operation Manual
  1. Manuals
  2. Brands
  3. Seiko Manuals
  4. Network Hardware
  5. SmartCS REST API
  6. Operation manual
Seiko SmartCS REST API Operation Manual

Seiko SmartCS REST API Operation Manual

Hide thumbs
Table of Contents

Advertisement

Quick Links

Download this manual
Operation Guide
Operation Guide
SmartCS REST API Operation Guide
First Edition
Sep 6, 2022
U00147060001

Advertisement

Table of Contents
loading

Related Manuals for Seiko SmartCS REST API

Summary of Contents for Seiko SmartCS REST API

  • Page 1 Operation Guide Operation Guide SmartCS REST API Operation Guide First Edition Sep 6, 2022 U00147060001...
  • Page 2 The contents of this document may be changed without notice. "SEIKO" is a registered trademark of Seiko Holdings Corporation. Seiko Solutions does not bear any liability for damage occurring due to the use of this document and the software described within or for the expenses required to recover from...

  • Page 3: Table Of Contents

    Table of Contents Introduction ........... 1 About this document ....................1 Function overview ...................... 2 SmartCS operation overview ................... 3 Operating environment ..................... 4 Preparation ............ 5 SmartCS preparation ....................5 Enable and disable REST API functions ............5 2.1.1 User creation ......................
  • Page 4 Request ......................22 4.1.1.2 Response ..................... 23 4.1.1.3 Error ......................24 4.1.1.4 Execution example ..................24 4.1.1.5 USERS ......................... 25 /users (GET) ....................... 25 4.2.1 Overview ..................... 25 4.2.1.1 Request ......................25 4.2.1.2 Response ..................... 26 4.2.1.3 Error ......................27 4.2.1.4 Execution example ..................
  • Page 5 Response ..................... 43 4.2.6.3 Error ......................44 4.2.6.4 Execution example ..................44 4.2.6.5 SERIAL ........................45 /serial/tty (GET) ....................45 4.3.1 Overview ..................... 45 4.3.1.1 Request ......................45 4.3.1.2 Response ..................... 46 4.3.1.3 Error ......................47 4.3.1.4 Execution example ..................47 4.3.1.5 /serial/tty/{ttylist} (GET) ................
  • Page 6 Overview ..................... 68 4.5.1.1 Request ......................68 4.5.1.2 Response ..................... 69 4.5.1.3 Error ......................69 4.5.1.4 Execution example ..................70 4.5.1.5 /log/history/console (GET) ................71 4.5.2 Overview ..................... 71 4.5.2.1 Request ......................71 4.5.2.2 Response ..................... 72 4.5.2.3 Error ......................72 4.5.2.4 Execution example ..................
  • Page 7 Request ......................86 4.6.3.2 Response ..................... 87 4.6.3.3 Error ......................88 4.6.3.4 Execution example ..................89 4.6.3.5 /ttymanage explanation ........90 Instructions and Directions for Use ..............90 Limitations ........................92 Operation under each option ................. 93 sendchar and recvchar operation ..............93 5.3.1 Operation when recvchar is not configured ..........

  • Page 8: Introduction

    About this document This document is the Operation Guide which summarizes the information that is required when using the SmartCS REST API functions. It lists information such as the SmartCS settings, specifications of each API resource, and how to use it, so please refer to this document when using the REST API functions.

  • Page 9: Function Overview

    Function overview This section provides an overview of the SmartCS REST API functions. SmartCS has so far executed a CLI after logging into a device via telnet or SSH for settings and information acquisition or the operation of managed nodes connected to SmartCS. By using the REST API functions, you can execute each function (processing by each API resource) from various clients and tools.

  • Page 10: Smartcs Operation Overview

    Invalid request, etc. Operation failed SmartCS operation overview This section provides an operation overview of the SmartCS REST API functions. The REST API functions access each API resource provided by SmartCS from the client and return a response for each function according to the request details.

  • Page 11: Operating Environment

    Process Description Access each API Accesses each API resource according to the resource request from the client. At that time, it also checks whether the correct method is specified and the appropriate user authority is granted, etc. Data check Checks whether the data is correct with respect to the specification of each API resource at the time of the request.

  • Page 12: Preparation

    Preparation SmartCS preparation 2.1.1 Enable and disable REST API functions This section describes the SmartCS settings for using the REST API functions. (1) Enable the HTTP/HTTPS functions Enable the SmartCS HTTP/HTTPS functions. Enabling the HTTP function (0)NS-2250# enable http (0)NS-2250# Enabling the HTTPS function (0)NS-2250# enable https (0)NS-2250#...
  • Page 13 (2) Enable the TTY manage function The TTY manage function must be enabled when accessing the /ttymanage API resource and performing operations on managed nodes connected to SmartCS. Enabling the TTY manage function (0)NS-2250# enable ttymanage (0)NS-2250#...

  • Page 14: User Creation

    2.1.2 User creation This section explains the process for creating a user to access the SmartCS REST API functions. A user for accessing each API resource provided by the REST API functions is a user that belongs to the extusr group.
  • Page 15 ■SmartCS user groups and executable functions User group Description normal User group that can connect to SmartCS via telnet, root ssh, or console to configure devices and acquire information. portusr User group that can connect to managed nodes connected to the serial port of the SmartCS via telnet or ssh and carry out operations.
  • Page 16 (1) Creating an extusr group user Create a user that belongs to the extusr user group. (0)NS-2250# create user api group extusr password New password: xxxxx Retype new password: xxxxx (0)NS-2250# (2) Setting the administrator authority Set the administrator authority for the user in the created extusr group.

  • Page 17: Security

    2.1.3 Security When using the REST API function, set and use the Firewall (ipfilter) function to strengthen security as needed. You can restrict access by specifying the TCP port number set to HTTP/HTTPS.

  • Page 18: Log Information

    2.2.2 REST API operation logs The SmartCS REST API functions ultimately execute the request details with the CLI. Therefore, you can check the commands executed when accessing each API resource with the show log command.

  • Page 19: Rest Api Functions

    REST API Functions Request 3.1.1 Base URL The base URL which accesses the SmartCS REST API functions uses the following address. Protocol Base URL HTTP http://<IP address>:<http port number>/api/v1/ HTTPS https://<IP address>:<https port number>/api/v1/ The IP address supports both v4 and v6.

  • Page 20: Http Method

    3.1.2 HTTP method The SmartCS REST API functions support the following HTTP methods. Method Description Issues a request to acquire information from the specified API resource. The operation corresponds to the show related command under the SmartCS CLI commands. POST Issues a request to create a new resource in the specified API.

  • Page 21: Parameters

    3.1.3 Parameters Each method can specify the parameters at the time of the request. Request Description GET query Optional values can be specified as parameters for a URL query. http://<IP>:<PORT>/api/v1/users/{username} The {username} portion is optional data that can be specified as a GET query. The specifiable content differs according to each API resource.

  • Page 22: Authentication

    Authentication 3.2.1 Basic authentication The SmartCS REST API functions support Basic authentication as the form of authentication at the time of the request. Specify the username and password pair in the Authorization header. Extusr members registered in SmartCS are subject to Basic authentication.

  • Page 23: Response

    Response 3.3.1 Status code The SmartCS REST API functions return the following status codes as a response after accessing the API resource. Status Meaning Overview code Status code when the REST API request was successfully processed. Bad Request Status code when the REST API request was unable to be successfully processed due to some sort of error.

  • Page 24: Common Data

    3.3.2 Common data After accessing each API resource, it returns JSON formatted data as a response together with the status code. The JSON formatted data is divided into common data and response data that is unique to each API resource with the common data stored in object format with "info"...
  • Page 25 Ex: if the request was successfully processed "info": { "result": 0, Common data "message": "" "systeminfo": { "Boot": { Response data for "System": { each API resource "Version": "3.0d", "Build": "2022-05-20", Ex: if the request was not successfully processed "info": { "result": 1, Common "message": "Error: Invalid request.

  • Page 26: Common Error

    Common error This section explains the details of errors which commonly occur with each API resource and how to handle them when they occur. Message Explanation Error: Invalid request.(400) Displayed when there is an irregularity in the information for accessing the specified API resource.
  • Page 27 Message Explanation Error: Invalid request.(601) Displayed when required parameter (Authorization) is not included in the request information header. Error: Invalid request.(602) Displayed when the user specified in the request information header does not exist or when the setting (authority) for accessing the specified API resource is not assigned.

  • Page 28: Api Resources And Methods

    API Resources and Methods The following is a list of resources provided by the SmartCS REST API functions. This chapter explains the specifications of each API resource (overview, requests, responses, errors, and execution examples). Classification Overview Method SYSTEM /system/version System...

  • Page 29: System

    4.1 SYSTEM 4.1.1 /system/version (GET) 4.1.1.1 Overview Acquire the system information. 4.1.1.2 Request Item Description Accessible user authority normal root Optional parameter This API resource is not a specifiable option.

  • Page 30: Response

    4.1.1.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data <Response data> Key name Description systeminfo Boot System Version Version of system software being booted Build Creation date of system software being booted Unit Side of system software being booted Status Boot type...

  • Page 31: Error

    4.1.1.4 Error This resource only returns an error for a common error. 4.1.1.5 Execution example $ curl -u api:api -X GET http://<IP>:<PORT>/api/v1/system/version "info": { "result": 0, "message": "" "systeminfo": { "Boot": { "System": { "Version": "3.0", "Build": "2022-05-26", "Unit": "main" "Status": "Reboot", "Config": { "Unit": "external",...

  • Page 32: Users

    4.2 USERS 4.2.1 /users (GET) 4.2.1.1 Overview Acquire a list of user information. 4.2.1.2 Request Item Description Accessible user authority normal root Optional parameter This API resource is not a specifiable option.

  • Page 33: Response

    4.2.1.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data <Response data> Key name Description users name User name (Array) group Name of the group that the user belongs to encrypt Encrypted password User group ID information port Serial port allow list permission...

  • Page 34: Error

    4.2.1.4 Error This resource only returns an error for a common error. 4.2.1.5 Execution example $ curl -u api:api -X GET http://<IP>:<PORT>/api/v1/users "info": { "result": 0, "message": "" "users": [ "name": "root", "group": "root", "encrypt": "", "uid": 0, "port": "", "permission": "", "sshkey": ""...

  • Page 35: Users (Post)

    4.2.2 /users (POST) 4.2.2.1 Overview Create a user. 4.2.2.2 Request Item Description Accessible user authority root Optional parameter Specify the JSON formatted data as the request body with the object format. <Request body data format> Key name Value type Description name Character Specify the username.
  • Page 36 Key name Value type Description port Character Specify the serial port numbers allowed for the string port user and extusr. ■Settings Numerical ・ A numerical value may be specified when value specifying only one port. ・When specifying multiple ports, you can use ttylist format to specify the ports with a character string.
  • Page 37 Key name Value type Description sshkey Array Set the ssh public key. ■Settings [“<method>”, “<public-key>”] Method is up to 20 characters Public-key is up to 720 characters ■default: none <CLI execution order> Execution CLI commands executed with a request extension order create user <username>...

  • Page 38: Response

    4.2.2.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data 4.2.2.4 Error In addition to common errors, the following errors also occur with this resource. Message Explanation (Status code) Displayed when the request body details are not Error: Invalid json data in the JSON format.

  • Page 39: Execution Example

    4.2.2.5 Execution example Request body JSON data $ cat users-post.json "name": "testuser", "group": "extusr", "password": "abcdefghijklmn51", "encrypt": "UuSOuT.h8r6nSBV0xaeR1bRhLf9Zx/", "uid": 403, "port": "1-4", "permission": { "root": "off", "ttymanage": "on" "sshkey": [ "ssh-rsa","AAAAB3NzaC1yc2EAAAADAQABA3FO" *Request body JSON data example $ curl -u api:api -X POST -H "Content-Type: application/json"...

  • Page 40: Users/{Username} (Get)

    4.2.3 /users/{username} (GET) 4.2.3.1 Overview Acquire the specified user information. 4.2.3.2 Request Item Description Accessible user authority normal root Optional parameter Specify the username with a GET query. <Parameter specification by GET query> Parameters Description {username} Specify the created username to acquire the information.

  • Page 41: Response

    4.2.3.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data <Response data> Key name Description users name User name (Array) group Name of the group that the user belongs to encrypt Encrypted password User group ID information port Serial port allow list permission...

  • Page 42: Error

    4.2.3.4 Error In addition to common errors, the following errors also occur with this resource. Message Explanation (Status code) Displayed when an unsupported character string Error: Invalid request. is specified in the username specified in the GET (400) query. Check the username specified in the GET query. Displayed when the specified user does not exist.

  • Page 43: Users/{Username} (Put)

    4.2.4 /users/{username} (PUT) 4.2.4.1 Overview Edit the specified user information. 4.2.4.2 Request Item Description Accessible user authority root Optional parameter Specify the username with a GET query. Specify JSON formatted data in object format as the request body of the specified user information. *The user information can be edited even only with the key name and value pair (only with the target data) where the settings are to be changed.
  • Page 44 Key name Value type Description port Character Specify the serial port numbers allowed for the string port user and extusr. ■Settings Numerical ・ A numerical value may be specified when value specifying only one port. ・When specifying multiple ports, you can use ttylist format to specify the ports with a character string.
  • Page 45 <CLI execution order> Execution CLI commands executed with a request extension order set user <username> {password | encrypt <string>}} *Set password when both password and encrypt are specified set user <username> port <enable port_list > unset user <username> port set user <username> permission {root | ttymanage { on | off }} set user <username>...

  • Page 46: Response

    4.2.4.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data 4.2.4.4 Error In addition to common errors, the following errors also occur with this resource. Message Explanation (Status code) Displayed when the request body details are not Error: Invalid json data in the JSON format.

  • Page 47: Execution Example

    4.2.4.5 Execution example Request body JSON data $ cat users-put.json "name": "testuser", "group": "extusr", "password": "abcdefghijklmn51", "encrypt": "UuSOuT.h8r6nSBV0xaeR1bRhLf9Zx/", "uid": 403, "port": "1-4,8,10", "permission": { "root": "off", "ttymanage": "on" "sshkey": [ "ssh-rsa","AAAAB3NzaC1yc2EAAAADAQABA3FO" *Request body JSON data example ( The user information can be edited even only with the data lines where the settings are to be changed.

  • Page 48: Users/{Username} (Delete)

    4.2.5 /users/{username} (DELETE) 4.2.5.1 Overview Delete the specified user. 4.2.5.2 Request Item Description Accessible user authority root Optional parameter GET query <Parameter specification by GET query> Parameters Description {username} Specify the created username to delete.

  • Page 49: Response

    4.2.5.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data 4.2.5.4 Error In addition to common errors, the following errors also occur with this resource. Message Explanation (Status code) Displayed when an unsupported character string Error: Invalid request.

  • Page 50: Users/Login (Get)

    4.2.6 /users/login (GET) 4.2.6.1 Overview Acquire the information about the currently logged in user. 4.2.6.2 Request Item Description Accessible user authority normal root Optional parameter API resource is not a specifiable option. This 4.2.6.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data"...

  • Page 51: Error

    4.2.6.4 Error This resource only returns an error for a common error. 4.2.6.5 Execution example $ curl -u api:api -X GET http://<IP>:<PORT>/api/v1/users/login "info": { "result": 0, "message": "" "user_login": [ "User-Name": "somebody", "Device": "console", "Login-Time": "May 27 00:05:18", "Idle": "00:00", "Remote-Host": ""...

  • Page 52: Serial

    SERIAL 4.3.1 /serial/tty (GET) 4.3.1.1 Overview Acquire a list of the serial information for each TTY 4.3.1.2 Request Item Description Accessible user authority normal root Optional parameter This API resource is not a specifiable option.

  • Page 53: Response

    4.3.1.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data <Response data> Description ttylist Serial port number (Array) config baud Serial port transfer rate bitchar Serial port data bit length parity Serial port parity stop Serial port stop bit length flow Serial port flow control...

  • Page 54: Error

    4.3.1.4 Error This resource only returns an error for a common error. 4.3.1.5 Execution example $ curl -u api:api -X GET http://<IP>:<PORT>/api/v1/serial/tty "info": { "result": 0, "message": "" "ttylist": [ "tty": 1, "config": { "baud": 115200, "bitchar": 8, "parity": "none", "stop": 1, "flow": "none", "detect_dsr": "off",...

  • Page 55: Serial/Tty/{Ttylist} (Get)

    4.3.2 /serial/tty/{ttylist} (GET) 4.3.2.1 Overview Acquire the serial information for the specified TTY. 4.3.2.2 Request Item Description Accessible user authority normal root Optional parameter GET query <Parameter specification by GET query> Parameters Description {ttylist} Specify the TTY number in ttylist format. Ex: specifying the tty numbers 1, 2, 3, 4, 10 1-4,10...

  • Page 56: Response

    4.3.2.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data <Response data> Description ttylist Serial port number (Array) config baud Serial port transfer rate bitchar Serial port data bit length parity Serial port parity stop Serial port stop bit length flow Serial port flow control...

  • Page 57: Error

    4.3.2.4 Error In addition to common errors, the following errors also occur with this resource. Message Explanation (Status code) Displayed when an unsupported character string Error: Invalid request. or a value that is outside of the specification is (400) specified in the TTY list (ttylist) specified in the GET query.

  • Page 58: Execution Example

    4.3.2.5 Execution example $ curl -u api:api -X GET http://<IP>:<PORT>/api/v1/serial/tty/1,16 "info": { "result": 0, "message": "" "ttylist": [ "tty": 1, "config": { "baud": 9600, "bitchar": 8, "parity": "none", "stop": 1, "flow": "none", "detect_dsr": "off", "label": "NS-2250-48" "status": { "DSR": "on", "CTS": "on", "DTR": "on", "RTS": "on",...

  • Page 59: Serial/Tty/{Ttylist} (Put)

    4.3.3 /serial/tty/{ttylist} (PUT) 4.3.3.1 Overview Edit the serial information for the specified TTY. 4.3.3.2 Request Item Description Accessible user authority root Optional parameter GET query Specify JSON formatted data in object format as the request body for each specified TTY setting. *The serial information can be edited even only with the key name and value pair (only with the target data) where the settings are to be changed.
  • Page 60 Key name Value type Description bitchar Numerical Specify the serial port data bit length. ■Specifiable values: value ■default: none parity Character Specify the serial port parity. ■Specifiable values: string even, odd, none ■default: none stop Numerical Specify the serial port stop bit length. ■Specifiable values: value 1, 2...
  • Page 61 <CLI execution order> Execution CLI commands executed with a request extension order set tty <ttylist> baud set tty <ttylist> bitchar set tty <ttylist> parity set tty <ttylist> stop set tty <ttylist> flow set tty <ttylist> detect_dsr set portd tty <ttylist> label <"string"> unset portd tty <...

  • Page 62: Response

    4.3.3.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data 4.3.3.4 Error In addition to common errors, the following errors also occur with this resource. Message Explanation (Status code) Displayed when the request body details are not Error: Invalid json data in the JSON format.

  • Page 63: Execution Example

    4.3.3.5 Execution example Request body JSON data $ cat tty-put.json "baud": 9600, "bitchar": 8, "parity": "none", "stop": 1, "flow": "none", "detect_dsr": "off", "label": "SWITCH-1" *Request body JSON data example ( The serial information can be edited even only with the data lines where the settings are to be changed.

  • Page 64: Serial/Hangup/Tty/{Ttylist} (Post)

    4.3.4 /serial/hangup/tty/{ttylist} (POST) 4.3.4.1 Overview Backup the specified TTY. 4.3.4.2 Request Item Description Accessible user authority root Optional parameter GET query POST *No request body data <Parameter specification by GET query> Parameters Description {ttylist} Specify the TTY number in ttylist format. Ex: specifying the tty numbers 1, 2, 3, 4, 10 1-4,10...

  • Page 65: Response

    4.3.4.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data 4.3.4.4 Error In addition to common errors, the following errors also occur with this resource. Message Explanation (Status code) Displayed when an unsupported character string Error: Invalid request.

  • Page 66: Execution Example

    4.3.4.5 Execution example Request body JSON data $ curl -u api:api -X POST -H "Content-Type: application/json" –d "" http://<IP>:<PORT>/api/v1/serial/hangup/tty/16 "info": { "result": 0, "message": "" *The description of the execution example is formatted.

  • Page 67: Ttymanage

    TTYMANAGE 4.4.1 /ttymanage (POST) 4.4.1.1 Overview Use the TTY manage function to execute character string sending and receiving on the serial port. 4.4.1.2 Request Item Description Accessible user authority ttymanage Optional parameter Specify the JSON formatted data as the request body with the object format.
  • Page 68 Key name Type Description Character Specify the line break code to assign at string the end of the sendchar. ■Choices: cr, lf, crlf ■Notes: codes other than the available choices will result in an error. recvchar Array Specify the character strings to wait for after the sendchar transmission.
  • Page 69 <Request body data format> (2) Operation upon occurrence of errors Key name Type Description error_detect_on_sendchar Character When an error occurs after the string sendchar transmission, specify whether send/not send subsequent sendchar. ■Choices ・exec Transmits a sendchar even when an error occurs ・cancel Does not transmit a sendchar when an error occurs...

  • Page 70: Response

    4.4.1.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data <Response data> Description request Request data specified in the request body error Number of errors that occurred data About the serial sending and receiving scenarios specified in the (Array) request body Transmitted data (execute_command)

  • Page 71: Error

    4.4.1.4 Error In addition to common errors, the following errors also occur with this resource. Message Description (Status code) Displayed when the request body details Error: Invalid json data are not in the JSON format. (400) Displayed when required parameters are Error: The required parameter missing from the request body.
  • Page 72 Message Description (Status code) Displayed when the number of settings for Error: The configurable lines of the request body error_recvchar_regex error_recvchar_regex are 1-8. option is out of range. (400) Displayed when the setting value for the Error: request body error_detect_on_sendchar error_detect_on_sendchar option option is unsupported.

  • Page 73: Execution Example

    4.4.1.5 Execution example Request body JSON data $ cat switch_version.json "tty": 2, "nl": "cr", "cmd_timeout": 30, "recvchar": [ "Switch>", "Switch#", "Press RETURN to get started." "recvchar_regex": [ "[Uu]sername:", "[Pp]assword:", "(^|\\r|\\n|!)[a-zA-Z0-9_().-]*(>|#) " "sendchar": [ "__NL__", "ssol", "ssol", "terminal length 0", "show version", "exit"...
  • Page 74 $ curl -u api:api -X POST -H "Content-Type: application/json" http://<IP>:<PORT>/api/v1/ttymanage --data @./switch_version.json "info": { "result": 0, "message": "" "request": { "tty": 2, "nl": "cr", "cmd_timeout": 30, "sendchar": [ "__NL__", "ssol", "ssol", "terminal length 0", "show version", "exit" "recvchar": [ "Switch>", "Switch#", "Press RETURN to get started."...

  • Page 75: Log/History

    LOG/HISTORY 4.5.1 /log/history/command (GET) 4.5.1.1 Overview Acquire the SmartCS command log information. 4.5.1.2 Request Item Description Accessible user authority root Optional parameter GET query <Parameter specification by GET query> Parameters Description lines Specify the number of lines in the command log to display.

  • Page 76: Response

    4.5.1.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data <Response data> Description Display the SmartCS command log data (Array) 4.5.1.4 Error In addition to common errors, the following errors also occur with this resource. Message Explanation (Status code)

  • Page 77: Execution Example

    4.5.1.5 Execution example $ curl -u api:api -X GET http://<IP>:<PORT>/api/v1/log/history/command "info": { "result": 0, "message": "" "log": [ "2022 May 26 22:06:21 root: show version", (Omitted) "2022 May 26 22:06:21 root: show user" *No options *The description of the execution example is formatted. $ curl -u api:api -X GET http://<IP>:<PORT>/api/v1/log/history/command?lines=100 "info": {...

  • Page 78: Log/History/Console (Get)

    4.5.2 /log/history/console (GET) 4.5.2.1 Overview Acquire the SmartCS console log information. 4.5.2.2 Request Item Description Accessible user authority root Optional parameter GET query <Parameter specification by GET query> Parameters Description lines Specify the number of lines in the command log to display.

  • Page 79: Response

    4.5.2.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data <Response data> Description Display the SmartCS console log data (Array) 4.5.2.4 Error In addition to common errors, the following errors also occur with this resource. Message Explanation (Status code)

  • Page 80: Execution Example

    4.5.2.5 Execution example $ curl -u api:api -X GET http://<IP>:<PORT>/api/v1/log/history/console "info": { "result": 0, "message": "" "log": [ "2022 May 27 00:05:18 login: login success: somebody/console", (Omitted) "2022 May 27 00:15:18 login: logout: somebody/console" *No options *The description of the execution example is formatted. $ curl -u api:api -X GET http://<IP>:<PORT>/api/v1/log/history/console?lines=100 "info": {...

  • Page 81: Log/History/Ttysend/Tty/{Ttyno} (Get)

    4.5.3 /log/history/ttysend/tty/{ttyno} (GET) 4.5.3.1 Overview Each command of the TTY manage function acquires the data logs sent to the TTY. 4.5.3.2 Request Item Description Accessible user authority root Optional parameter GET query <Parameter specification by GET query> Parameters Description {ttyno} Specify one TTY number.

  • Page 82: Response

    4.5.3.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data <Response data> Description Each command of the TTY manage function displays the data logs sent to the TTY. (Array) 4.5.3.4 Error In addition to common errors, the following errors also occur with this resource.

  • Page 83: Execution Example

    4.5.3.5 Execution example $ curl -u api:api -X GET http://<IP>:<PORT>/api/v1/log/history/ttysend/tty/4 "info": { "result": 0, "message": "" "log": [ "2022 May 12 19:01:01 restapi: enable<CR>", (Omitted) "2022 May 12 19:02:19 restapi: show running-config<CR> *No options *The description of the execution example is formatted. $ curl -u api:api -X GET http://<IP>:<PORT>/api/v1/log/history/ttysend/tty/4?lines=25 "info": {...

  • Page 84: Log/History/Webapi (Get)

    4.5.4 /log/history/webapi (GET) 4.5.4.1 Overview Acquire the SmartCS webapi log information. 4.5.4.2 Request Item Description Accessible user authority root Optional parameter GET query <Parameter specification by GET query> Parameters Description lines Specify the number of lines of the REST API log to display.

  • Page 85: Response

    4.5.4.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data <Response data> Description Display the SmartCS webapi log data. (Array) 4.5.4.4 Error In addition to common errors, the following errors also occur with this resource. Message Explanation (Status code)

  • Page 86: Execution Example

    4.5.4.5 Execution example $ curl -u api:api -X GET http://<IP>:<PORT>/api/v1/log/history/webapi "info": { "result": 0, "message": "" "log": [ (Omitted) "2022 May 27 11:47:15 [10080] login success: api/172.31.8.41:41188", "2022 May 27 11:47:16 [10080] logout: api/172.31.8.41:41188" *No options *The description of the execution example is formatted. $ curl -u api:api -X GET http://<IP>:<PORT>/api/v1/log/history/webapi "info": { "result": 0,...

  • Page 87: Log/Serial

    LOG/SERIAL 4.6.1 /log/serial/tty/{ttyno} (GET) 4.6.1.1 Overview Acquire the SmartCS TTY log information. 4.6.1.2 Request Item Description Accessible user authority ttymanage Optional parameter GET query <Parameter specification by GET query> Parameters Description {ttyno} Specify one TTY number. ■Specification range: 1 to 48 lines Specify the number of lines in the command log to display.

  • Page 88: Response

    4.6.1.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data <Response data> Description Display the log information for the specified TTY number saved (Array) by SmartCS. 4.6.1.4 Error In addition to common errors, the following errors also occur with this resource.

  • Page 89: Execution Example

    4.6.1.5 Execution example $ curl -u api:api -X GET http://<IP>:<PORT>/api/v1/log/serial/tty/2 "info": { "result": 0, "message": "" "log": [ (Omitted) *No options *The description of the execution example is formatted. $ curl -u api:api -X GET http://<IP>:<PORT>/api/v1/log/serial/tty/2?lines=100 "info": { "result": 0, "message": ""...

  • Page 90: Log/Serial/Files/Tty/{Ttyno} (Get)

    4.6.2 /log/serial/files/tty/{ttyno} (GET) 4.6.2.1 Overview Acquire (download) the SmartCS TTY log data. 4.6.2.2 Request Item Description Accessible user authority ttymanage Optional parameter GET query <Parameter specification by GET query> Parameters Description {ttyno} Specify one TTY number. ■Specification range: 1 to 48 lines Specify the number of lines in the command log to display.

  • Page 91: Response

    4.6.2.3 Response Item Description Format Text data (text/plain) <Response data> Description Download the log information for the specified TTY number saved by SmartCS as text data. ■File name specification (Content-Disposition attachment:filename) ・Label name_host name_ttyNN_yymmddhhmm.log - NN is the TTY number (If the TTY number is a single digit, a 0 is assigned. In the case of TTY2, the result is _tty02_) - If a SPACE character is used in the label name, it is converted to "_"...

  • Page 92: Execution Example

    4.6.2.5 Execution example $ curl -u api:api –LOJ -X GET http://<IP>:<PORT>/api/v1/log/serial/files/tty/2 $ ls SWITCH-1_NS-2250_tty02_2205271913.log *No options *The description of the execution example is formatted. $ curl -u api:api –LOJ -X GET http://<IP>:<PORT>/api/v1/log/serial/files/tty/2?lines=100 $ ls SWITCH-1_NS-2250_tty02_2205271913.log *Download the latest 100 lines from the log file...

  • Page 93: Log/Serial/Search/Tty/{Ttyno} (Get)

    4.6.3 /log/serial/search/tty/{ttyno} (GET) 4.6.3.1 Overview Search the SmartCS TTY log information. 4.6.3.2 Request Item Description Accessible user authority ttymanage Optional parameter GET query <Parameter specification by GET query> Parameters Description {ttyno} Specify one TTY number. (Required) ■Specification range: 1 to 48 string Specify the character string to search.

  • Page 94: Response

    4.6.3.3 Response Item Description Format JSON (object format) Common Refer to "3.3.2 Common data" data <Response data> Description TTY number to search for log information label Label name set for the TTY number to search for log information string Search character string count Number of search character strings included in the log information...

  • Page 95: Error

    4.6.3.4 Error In addition to common errors, the following errors also occur with this resource. Message Explanation (Status code) Displayed when an unsupported character Error: Invalid value(ttyno). string or value is specified in the TTY (400) number specified in the GET query. The search character string, which is a Error: The required parameter is required parameter, is not specified in the...

  • Page 96: Execution Example

    4.6.3.5 Execution example $ curl -u api:api -X GET "http://<IP>:<PORT>/api/v1/log/serial/search/tty/2?string=version" "info": { "result": 0, "message": "" "tty": "2", "label": "SWITCH", "string": "version", "count": "4", "data": [] *Searching for a character string that includes "version" *The description of the execution example is formatted. $ curl -u api:api -X GET "http://<IP>:<PORT>/api/v1/log/serial/search/tty/2?string=version&lines=1"...

  • Page 97: /Ttymanage Explanation

    /ttymanage explanation Instructions and Directions for Use This section provides instructions and directions for using the tty manage function by specifying API resources of “/ttymanage”. The tty manage function enables to send the specified characters to managed nodes connected to SmartCS and receive the command result to execute various operations.
  • Page 98 Exclusion control function is available to avoid an accident such as sending unintended commands since these two methods of operation are executed at the same time. Enabling exclusion control function of serial operation (0)NS-2250# set portd service exclusive on (0)NS-2250# * Exclusion control is enabled by default.

  • Page 99: Limitations

    Limitations While this content applies to the REST API functions overall, care is required regarding the timeout time of the client application particularly when the TTY manage function, which uses the /ttymanage API resource, receives a request from the client and returns a response after serial communication at its own convenience.

  • Page 100: Operation Under Each Option

    Operation under each option This section explains the operation under each option. 5.3.1 sendchar and recvchar operation sendchar sends the specified characters in order from the top. recvchar waits to see whether or not the matching characters are included in the input/output content after sending the characters. When the matching characters are received, it sends the next characters.

  • Page 101: Operation When Recvchar Is Not Configured

    5.3.2 Operation when recvchar is not configured If recvchar (recvchar_regex) is not configured, sendchar waits until the cmd_timeout period has passed before sending the next characters. *The only parameters which are essential for the JSON option as the request body of “/ttymaage” are the tty and sendchar options. *The figure below shows an example of not specifying the recvchar option.

  • Page 102: Special Sendchar Settings

    5.3.3 Special sendchar settings In addition to sending the specified characters, sendchar can be set to special sending methods by specifying certain options. 1. Send only the line feed code __NL__ option Set the transmitted character string to "__NL__" to send only the line feed character.
  • Page 103 2. Set a timeout period for each transmitted character string __WAIT__：sec option The characters specified in sendchar wait for the characters configured in recvchar for the period of time set in the cmd_timeout option (default of 10 seconds). If the commands executed on the network devices console by the transmitted character string take time to output the results (execution of commands to retrieve the running config or support information), only the specific transmitted character string can...
  • Page 104 3. Setting to not wait for recvchar for each transmitted character string __NOWAIT__ option This option immediately sends the next characters without waiting for the period of time set in the cmd_timeout option. *Transmits approximately one second later. This option can be used when you wish to sequentially send characters to the console connection destination without waiting for recvchar.
  • Page 105 4. Setting to wait only for a set period of time without waiting for recvchar for each transmitted character string __NOWAIT__：sec option If the recvchar setting is configured, this option checks whether or not the recvchar are included in the input/output results after sending the characters and sends the next characters if they are included.
  • Page 106 ＜__NOWAIT__:sec option usage example＞...
  • Page 107 5. Send a control character __CTL__ option Specify "__CTL__:hex" in sendchar when sending a control character. The following range of control characters can be sent. 00 : [Ctrl-@] 08 : [Ctrl-H] 10 : [Ctrl-P] 18 : [Ctrl-X] 01 : [Ctrl-A] 09 : [Ctrl-I] 11 : [Ctrl-Q] 19 : [Ctrl-Y]...
  • Page 108 ＜__CTL__:hex option usage example＞...
  • Page 109 6. Sending multiple control characters together __HEX__ option When sending multiple control characters together, specify "__HEX__:hex" in sendchar. The range of control characters which can be sent is from 00 to 7F. The __HEX__ option does not wait for the received character string specified in recvchar. The following types of situations are expected for sending control characters together via the console.

  • Page 110: Error_Detect_On_Sendchar Operation

    5.3.4 error_detect_on_sendchar operation In some cases, sending the characters specified in sendchar may result in an error for the following reasons. ＜Causes of character transmission errors＞ Error cause Cause Unable to receive recvchar before the end of the timeout Error:: period Timeout.
  • Page 111 1. Operation when error_detect_on_sendchar:cancel is configured *The default value is error_detect_on_sendchar:cancel. 2. Operation when error_detect_on_sendchar:exec is configured...

  • Page 112: List Of Sendchar Sending Methods

    List of sendchar sending methods The following table shows combinations of sendchar sending methods. Configuration method Notes show version Send characters show version __WAIT__：sec Wait recvchar configured period of time after sending the characters show version __NOWAIT__ Immediately send next characters after sending the characters.
  • Page 113 Configuration method Notes __HEX__: 54 65 73 74 Send various types of data such as control characters and control codes in hexadecimal or ASCII character strings. __HEX__: 54 65 73 74 __WAIT__：sec Wait recvchar configured time after sending the specified data in hexadecimal. __HEX__: 54 65 73 74 __NOWAIT__ Immediately send...

  • Page 114: Configuring Regular Expressions

    Configuring Regular Expressions Regular expressions can be configured within the following options when creating the JSON data to operate console of managed nodes specifying API resource “/ttymanage”. ・recvchar_regex ・error_recvchar_regex The following table lists the regular expressions which can be configured with these options.
  • Page 115 (3) Other expressions (re) (re is any regular expression) Match re. Match either expression separated by this symbol. [0-9] Match a single numerical character from 0 to 9. [a-z] Match a single alphabetic character from a to z. [A-Z] Match a single alphabetic character from A to Z. (4) Combined expressions (^|\n|\r) Match the beginning of the line.

  • Page 116: Appendix A Accessible Api Resources For Each User Authority

    Appendix A Accessible API Resources for Each User Authority A list of the API resources that are accessible according to each level of authority granted to extusr members is shown below. 〇: accessible x: not accessible API resource Method Authority granted to an extusr normal root...
  • Page 117 8, Nakase 1-chome, Mihama-ku, Chiba-shi, Chiba 261-8507, Japan ns-global-support@seiko-sol.co.jp https://www.seiko-sol.co.jp/en/...

Table of Contents