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 Device Configuration APIs.

Authentication​

For detailed information on how to authenticate requests to this API, please refer to Authentication.

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

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/config/rest/ssh/v2/users" \
  --data '{
  "data": {
    "username": "username1",
    "password": "password1",
    "comment": "comment1"
  }
}'
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

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/config/rest/ssh/v2/users"
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

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/config/rest/ssh/v2/users/username1"
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

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/config/rest/ssh/v2/users/username1" \
  --data '{
  "data": {
    "password": "newpassword",
    "comment": "new comment"
  }
}'
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

curl --request DELETE \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/config/rest/ssh/v2/users/username1"
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

Version 1 of the SSH object.

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

This is the entity collection with SSH users. Each SSH user entity is identified by the key username.

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 Range: No

The comment is a property in the ssh.v2.users entity. It is connected to a username. If the comment property is used then it can not be an empty string.

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

The password is a property in the ssh.v2.users entity. It is connected to a username. The password can not be read once set.

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

The username is an unique key property in the ssh.v2.users entity. It is used to identify an SSH user in the SSH users collection.

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