Skip to main content

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
info

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-_]*[$]?$
Last updated on