SSH Management

The VAPIX® SSH API is used to manage SSH accounts on a device and has methods to:

• Add an SSH user
• Retrieve details of SSH users
• Modify an SSH user
• Remove an SSH user

note

This API includes sensitive data. You must use a secured channel for the communication transmissions.

Overview

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to the Device Configuration APIs section in the VAPIX®.

warning

This API is in BETA stage. The API is provided for testing purposes and is subject to backward-incompatible changes, including modifications to functionality, behavior, and availability. Please don't use in production environment.

Use cases

Add a new SSH user

Make a request with the following information to create a new SSH user on your device:

• User collection: ssh.v2.users
• Properties: username, password and comment

Example

POST /config/rest/ssh/v2beta/users HTTP/1.1
HOST: my-device
Content-Type: application/json

{
  "data": {
    "username": "username1",
    "password": "password1",
    "comment": "comment1"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

Adding a new SSH user also creates a home directory for the user. Note that there is only a small amount of storage available on the device.

Get all of the SSH users

Make a request with the following information to retrieve all SSH user information from your device:

• User collection: ssh.v2.users

This will return an array with the following information:

• Properties: username and comment

Example

GET /config/rest/ssh/v2beta/users HTTP/1.1
HOST: my-device
Content-Type: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status: "success",
  "data": [
    {
      "username": "username1",
      "comment": "comment1"
    },
    {
      "username": "username2",
      "comment": "comment2"
    }
  ]
}

Get an existing SSH user

Make a request with the following information to retrieve SSH information for a single user from your device:

• User collection: ssh.v2.users
• Key property: username

This will return the following information:

• Properties: username and comment

Example

GET /config/rest/ssh/v2beta/users/username1 HTTP/1.1
HOST: my-device
Content-Type: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "data": {
    "username": "username1",
    "comment": "comment1"
  }
}

Modify an existing SSH user

Make a request with the following information to modify an SSH user on your device:

• User collection: ssh.v2.users
• Key property: username
• Properties: password and comment

Example

PATCH /config/rest/ssh/v2beta/users/username1 HTTP/1.1
HOST: my-device
Content-Type: application/json

{
  "data": {
    "password": "newpassword",
    "comment": "new comment"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

Remove an existing SSH user

Make a request with the following information to remove an SSH user from your device:

• User collection: ssh.v2.users
• Key property: username

Example

DELETE /config/rest/ssh/v2beta/users/username1 HTTP/1.1
HOST: my-device
Content-Type: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

Removing an existing SSH user also deletes the corresponding home directory and all of its contents.

API Definition

Structure

ssh.v2 (Root Entity)
  users (Entity Collection)
    comment (Property)
    password (Property)
    username (Property)

Entities

ssh.v2

• Description: The SSH object
• Type: Singleton
• Operations: GET
• Attributes: Dynamic Support: No

Properties

This entry has no properties

Actions

This entry has no actions.

ssh.v2.users

• Description: The SSH users collection
• Type: Collection (Key Property: username)
• Operations:
  • GET
  • SET - Properties: password, comment
  • ADD - Permissions: admin / Required properties: username, password / Optional properties: comment
  • REMOVE - Permissions: admin
• Attributes: Dynamic Support: No

Properties

comment

• Description: The full name or comment of the SSH user
• Datatype: comment_type
• Operations: GET - Permissions: admin | SET - Permissions: admin
• Attributes:
  • Nullable: No
  • Dynamic Support: No
  • Dynamic Enum: No
  • Dynamic Rang: No

password

• Description: The password of the SSH user
• Datatype: password_type
• Operations: SET - Permissions: admin
• Attributes:
  • Nullable: No
  • Dynamic Support: No
  • Dynamic Enum: No
  • Dynamic Rang: No

username

• Description: The user name of the SSH user
• Datatype: username_type
• Operations: GET - Permissions: admin
• Attributes:
  • Nullable: No
  • Dynamic Support: No
  • Dynamic Enum: No
  • Dynamic Rang: No

Actions

This entry has no actions.

Data Types

comment_type

• Description: The full name or comment of the SSH user
• Type: string
• Minimum Length: 0
• Maximum Length: 256
• Pattern: ^[^: ]*$

password_type

• Description: The password of the SSH user
• Type: string
• Minimum Length: 1
• Maximum Length: 256

username_type

• Description: The user name of the SSH user
• Type: string
• Minimum Length: 1
• Maximum Length: 32
• Pattern: ^[a-z_][a-z0-9-_]*[$]?$