Platform API Version 2.0

The API's are accessible via remote ssh and require a VidyoPlatformAPI User account with a public/private key pair. An account can be created via Admin Console > Advanced Options > VidyoPlatformAPI User menu.

General API

Syslog API

Apache2 API

Mysql API

VidyoInsights API

General API

test | Test

This API is used to test which API the VidyoPlatformAPI is using and will echo the command, parameters, and version detected.

Syntax:

test <test_parameter_1> ... <test_parameter_n>

Example:

ssh adminAPI@10.122.210.25 test Hello world! Command testVersion 0.0.10 Parameters Hello world!

vidyoUpload | VidyoUpload

This API allows the upload of an arbitrary file. This file will be overwritten every time it is uploaded. The file is limited to 20480000000 bytes (20.48 GB). This is meant to prevent filling up the disk. Other commands will look for the uploaded file to either upgrade or install. These commands will validate the integrity of the uploaded file before installing. The command expects the file to be passed in via stdin and will stop either after the stdin is complete or when the size hits 4G.

Syntax:

Syntax here.

Example:

cat TestPatchUpdate01-signed.vidyo | ssh adminAPI@10.122.210.25 VidyoUpload 1534033+1 records in 1534033+1 records out785425175 bytes (785 MB) copied, 10.6273 s, 73.9 MB/s

vidyoUpdate | VidyoUpdate

This API is used to install signed .vidyo files. There are three modes of operation for this command:

  • By using the VidyoUpload to upload the .vidyo file to the server. Then, by running the VidyoUpdate API afterwards, the last uploaded fill will be verified and installed (only if it passes the integrity test).
  • Uses a file already located on the target file server.
  • Pass a URL for the .vidyo file. In this case, the server will attempt to download the file pointed to by the URL, verify the integrity, and then install.

Example 1:

ssh adminAPI@10.122.210.25 VidyoUpdate

Example 2:

ssh adminAPI@10.122.210.25 VidyoUpdate <full_file_path>

Example 3:

ssh adminAPI@10.122.210.25 VidyoUpdate <file_URL> 1470466+1 records in1470466+1 records out752878794 bytes (753 MB) copied, 21.1218 s, 35.6 MB/s

vidyoDeleteUpload | VidyoDeleteUpload

Used to delete a file uploaded by the VidyoUpload API.

Example:

ssh adminAPI@10.122.210.25 VidyoDeleteUpload

vidyoDeleteDownload | VidyoDeleteDownload

Used to clean up the temporary file created by VidyoDownloadLogs API within the /opt/vidyo/data/VidyoPlatformAPI/download directory in cases where the user interrupts the download process.

Example:

ssh adminAPI@10.122.210.25 VidyoDeleteDownload

vidyoDownloadLogs | VidyoDownloadLogs

This API will send a tar.gz formatted copy of the directory within the /opt/vidyo/log directory to stdout. It will also include syslog and kernel logs. The command output must be sent to a file (see example).

Syntax:

VidyoDownloadLogs <application_name> > <output_file>

  • application_name - Optional API parameter allowing user to download logs folder for the particular application listed in /opt/vidyo/log. If the parameter is not provided, all logs under the /opt/vidyo/log folder will be included to command output.

Example:

ssh adminAPI@10.122.210.25 VidyoDownloadLogs VidyoPortal2 > logs.tgz

SSL_InstallPFX

This API is used to install password protected .pfx files. There are two modes of operation for this command.

  • The first method is to use the VidyoUpload API to upload the .pfx file to the server. Then, by running the SSL_InstallPFX afterward, the last uploaded file will be installed only if the proper password is provided.
  • The second method is to pass a remote URL to the command.

Example 1:

echo <PFX_PASSWORD> | ssh adminAPI@10.122.210.25 SSL_InstallPFX

Example 2:

techo <PFX_PASSWORD> | ssh adminAPI@10.122.210.25 SSL_InstallPFX http://vidyo-platform.edge.local/Public/security_bundle.pfx

Cert: /C=US/ST=New Jersey/L=Hackensack/O=Vidyo, Inc./CN=*.vidyoqa.comCert

Chain: /C=US/O=DigiCert Inc/CN=DigiCert SHA2 Secure Server CACert

Chain: /C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert Global Root CACA

Certs: 3WARNING: Skipping duplicate certificate self-cert.pem

SSL_InstallTrustedCA

This API is used to install files. There are two modes of operation for this command:

  • The first method is to use the VidyoUpload API to upload the trusted CA file to the server. A standard CRT file is supported. Then, by running the SSL_InstallTrustedCA API afterward, the last uploaded fill will be installed. A check of the CA file is performed to ensure the proper format.
  • The second method is to pass a remote URL to the command.

Example 1:

ssh adminAPI@10.122.210.25 SSL_InstallTrustedCA

Example 2:

ssh adminAPI@10.122.210.25 SSL_InstallTrustedCA http://vidyo-platform.edge.local/Public/ca-certificates.crt--2020-09-04 14:41:55-- http://vidyo-platform.edge.local/Public/ca-certificates.crt Resolving vidyo-platform.edge.local... 10.51.29.201

Connecting to vidyo-platform.edge.local|10.51.29.201|:80... connected.

HTTP request sent, awaiting response... 200 OK

Length: 233394 (228K) [application/x-x509-ca-cert]

Saving to: ‘/opt/vidyo/data/VidyoPlatformAPI/upload’

0K ..................................... 21% 203M 0s

50K .................................... 43% 146M 0s

100K ................................... 65% 167M 0s

150K ................................... 87% 314M 0s

200K ................................... 100% 264M=0.001s

2020-09-04 14:41:55 (198 MB/s) - ‘/opt/vidyo/data/ VidyoPlatformAPI/upload’ saved [233394/233394]

WARNING: Skipping duplicate certificate ACCVRAIZ1.pem

SSL_UseDefaultCA_on

This API turns on the CA that ships with the platform. This reverts the setting to use the default CA that ships with the platform. This will modify the /etc/ca-certificates.conf file.

Example:

ssh adminAPI@10.122.210.25 SSL_UseDefaultCA_on

SSL_UseDefaultCA_off

This API turns off the CA that ships with the platform. This is desired if a customer wants to restrict the trusted CA's to the list installed using SSL_InstallTrustedCA. This will modify the /etc/ca-certificates.conf file.

Example:

ssh adminAPI@10.122.210.25 SSL_UseDefaultCA_off

reboot | Reboot

This command reboots the server.

Example:

ssh adminAPI@10.122.210.25 reboot

shutdown | Shutdown | SHUTDOWN

This command will shut down the server. Only call this command if there is an ability to power the server on again.

Example:

ssh adminAPI@10.122.210.25 SHUTDOWN

getVidyoadminToken | GetVidyoadminToken

This API is used to generate a vidyoadmin token for providing access to Vidyo Support engineers. This command enables the vidyoadmin password for a 24 hour period, or until it is disabled.

Example:

ssh adminAPI@10.122.210.25 GetVidyoadminToken

clearVidyoadminToken | ClearVidyoadminToken

This API is used to disable a vidyoadmin token.

Example:

ssh adminAPI@10.122.210.25 ClearVidyoadminToken

getVersion | GetVersion

This API will return the version of a given application on the system.

Syntax:

getVersion <application_name>

  • application_name - Current implementation shows versions only for apps which name matches pattern Vidyo* and which contains the VERSION file within the application folder.

Example:

ssh adminAPI@10.122.210.25 getVersion VidyoPortal2

addStaticHost | AddStaticHost

This API will add a host name for a given IP address. It will only allow a single entry for a given IP address. If the use of a duplicate IP address is attempted, an error message will be displayed.

Syntax:

addStaticHost <new_host_IP> <new_host_name>

Example:

ssh adminAPI@10.122.210.25 addStaticHost 160.79.220.123 reflector123.vidyoqa.com 160.79.220.123 reflector123.vidyoqa.com added

removeStaticHost | RemoveStaticHost

This API will remove an entry for a given IP address.

Syntax:

removeStaticHost <host_IP>

Example:

ssh adminAPI@10.122.210.25 removeStaticHost 160.79.220.123 Removed 160.79.220.123

addLocalHost | AddLocalHost

This API will add an entry on the local interface. It will check for the form 127.x.y.z and also expects each entry to be unique. If a second entry for a previously used address is given, an error message will be displayed.

Syntax:

addLocalHost <new_host_IP> <new_host_name>

Example:

ssh adminAPI@10.122.210.25 addLocalHost 127.0.0.10 dev-test.lab.vidyo 127.0.0.10 dev-test.lab.vidyo added

removeLocalHost | RemoveLocalHost

This API will remove a local host entry for a given localhost IP address

Syntax:

removeLocalHost <host_IP>

Example:

ssh adminAPI@10.122.210.25 removeLocalHost 127.0.0.10 Removed 127.0.0.10

listStaticHost | ListStaticHost

This API will list static host entries that have been configured with the addStaticHost and the addLocalHost command(s).

Example:

ssh adminAPI@10.122.210.25 listStaticHost 10.122.210.25 test.dev.com test160.79.220.123 reflector123.vidyoqa.com127.0.0.10 dev-test.lab.vidyo

setHostname | SetHostname

Sets the host name for the machine. This is independent of the domain. To set the FQDN see SetFQDN platform API.

Host name must be from 2 up to 63 chars in length and must only contain numbers [0-9] and chars [a-z].

Example:

ssh adminAPI@10.122.210.25 setHostname test

getHostname | GetHostname

Gets the host name for the machine. This is independent of the domain. To get the FQDN see GetFQDN platform API.

Example:

ssh adminAPI@10.122.210.25 getHostname test

setFQDN | SetFQDN

Set the system FQDN based upon the host name and domain name given on the command line (setFQDN host name domain).

  • All identities between the dots are checked the same way as the host name.
  • Total domain length should be less then 254 chars.

Syntax:

FQDN = domain + host name

 

Example:

ssh adminAPI@10.122.210.25 setFQDN test.dev.com

getFQDN | GetFQDN

Gets the fully qualified domain name for the host.

Example:

ssh adminAPI@10.122.210.25 getFQDN test.dev.com

updateAdminKey | UpdateAdminKey

Used for changing VidyoPlafromAPI user’s public key. This command should be applied only to the user calling this API. Once a new key is set the user should start with a new private key for all following API calls.

Example:

echo <NEW_KEY_VALUE> | ssh adminAPI@10.122.210.25 updateAdminKey adminAPI

updateAdminPassword | UpdateAdminPassword

Sets new user password (should be base64 encoded).

Example:

echo <NEW_USER_BASE64_PASSWD> | ssh adminAPI@10.122.210.25 updateAdminPassword adminAPI

unlockUser | UnlockUser

Unlocks a user account that was locked after 5+ login fails.

Example:

ssh adminAPI@10.122.210.25 unlockUser admin

Syslog API

test | Test

Checks if Syslog APIs are installed.

Example:

ssh adminAPI@10.122.210.25 syslogapi test

enableSyslogForwardingTCP | EnableSyslogForwardingTCP

This API is used for configuring system logs or any log file to be forwarded to a remote syslog server.

Example:

ssh adminAPI@10.122.210.25 syslogapi enableSyslogForwardingTCP <IP> <PORT>

disableSyslogForwardingTCP | DisableSyslogForwardingTCP

This command is used to disable forwarding system logs to a remote syslog server.

Example:

ssh adminAPI@10.122.210.25 syslogapi disableSyslogForwardingTCP

enableSyslogForwardingTLS | EnableSyslogForwardingTLS

This is similar to the enableSyslogForwardingTCP except that the message will use a TLS connection to the remote syslog server. This command requires the remote syslog server to present a valid certificate and the issuer must be on the list of trusted root certificates.

Example:

ssh adminAPI@10.122.210.25 syslogapi enableSyslogForwardingTLS <IP> <PORT>

disableSyslogForwardingTLS | DisableSyslogForwardingTLS

This command is used to disable forwarding system logs to a remote syslog server.

Example:

ssh adminAPI@10.122.210.25 syslogapi disableSyslogForwardingTLS

enableFileForwardingTCP | EnableFileForwardingTCP

This command is used for forwarding application logs that are not using the syslog facility.

Syntax:

syslogapi enableFileForwardingTCP <IP> <PORT> <FILE_NAME> [<TAG> <OFFSET>]

  • <IP> - IP Address of the syslog server.
  • <PORT> - Port Number where the remote syslog server is listening.
  • <FILENAME> - This is the file name of the log file. (Note: The absolute path must be included.)
  • [TAG] - All the messages from the custom logs will be prepended with <TAG>. This is optional.
  • [OFFSET] - Use this parameter if you want syslog to send all the messages starting from Nth column where N is the offset. This is useful in case the application log file has a date on every message. It can be configured to exclude the date column so there won't be duplicate dates on every line.

Example:

ssh adminAPI@10.122.210.25 syslogapi enableFileForwardingTCP 172.16.7.232 2000 /opt/vidyo/log/VidyoCLI/history.log VidyoCLI 20

disableFileForwardingTCP | DisableFileForwardingTCP

This command is used to disable forwarding custom logs to a remote syslog server.

Syntax:

syslogapi disableFileForwardingTCP <FILE_NAME>

  • <FILENAME> - This is the file name of the log file. (Note: The absolute path must be included.)

Example:

ssh adminAPI@10.122.210.25 syslogapi disableFileForwardingTCP /tmp/file.log

enableFileForwardingTLS | EnableFileForwardingTLS

This command is used for forwarding via TLS connection application logs that are not using the syslog facility.

Syntax:

syslogapi enableFileForwardingTLS <IP> <PORT> <FILE_NAME> [<TAG> <OFFSET>]

  • <IP> - IP Address of the syslog server.
  • <PORT> - Port number where the remote syslog server is listening.
  • <FILENAME> - This is the file name of the log file. (Note: The absolute path must be included.)
  • [TAG] - All the messages from the custom logs will be prepended with <TAG>. This is optional.
  • [OFFSET] - Use this parameter if you want syslog to send all the messages starting from Nth column where N is the offset. This is useful in case the application log file has a date on every message. It can be configured to exclude the date column so there won't be duplicate dates on every line.

Example:

ssh adminAPI@10.122.210.25 syslogapi enableFileForwardingTLS 172.16.7.232 2000 /opt/vidyo/log/VidyoCLI/history.log VidyoCLI 20

disableFileForwardingTLS | DisableFileForwardingTLS

This command is used to disable forwarding custom logs to a remote syslog server.

Syntax:

syslogapi disableFileForwardingTLS <FILE_NAME>

  • <FILENAME> - This is the file name of the log file. (Note: The absolute path must be included.)

Example:

ssh adminAPI@10.122.210.25 syslogapi disableFileForwardingTLS /tmp/file.log

removeAllSyslogForwarding | RemoveAllSyslogForwarding

Remove all the syslog forwarding configuration.

Example:

ssh adminAPI@10.122.210.25 syslogapi removeAllSyslogForwarding

restart | Restart

Restarts syslog service.

Example:

ssh adminAPI@10.122.210.25 syslogapi restart

validateServerCertificate | ValidateServerCertificate

Validates server certificate.

Syntax:

syslogapi validateServerCertificate <IP> <PORT>

  • <IP> - IP address
  • <PORT> - Port number

Example:

ssh adminAPI@10.122.210.25 syslogapi validateServerCertificate 172.16.7.232 2000 Validating server certificate from 172.16.7.232:2000...[FAILED] Verify return code: 18 (self signed certificate)

Apache2 API

test | Test

Checks if Apache2 APIs are installed.

Example:

ssh adminAPI@10.122.210.25 apache2 test

start | Start

Starts Apache2 service.

Example:

ssh adminAPI@10.122.210.25 apache2 start

stop | Stop

Stops Apache2 service.

Example:

ssh adminAPI@10.122.210.25 apache2 stop

restart | Restart

Restarts Apache2 service.

Example:

ssh adminAPI@10.122.210.25 apache2 restart

reload | Reload

Performs the same action as restart.

Example:

ssh adminAPI@10.122.210.25 apache2 reload

setModern | SetModern

Sets "modern" SSL configurations (configures SSL protocols and ciphers set).

Example:

ssh adminAPI@10.122.210.25 apache2 setModern

setIntermediate | SetIntermediate

Sets "intermediate" SSL configurations (configures SSL protocols and ciphers set).

Example:

ssh adminAPI@10.122.210.25 apache2 setIntermediate

Mysql API

test | Test

  • Checks if Mysql APIs are installed.

Example:

ssh adminAPI@10.122.210.25 mysql test

isPasswordSet | IsPasswordSet

Checks if mysql user exists and has password.

Syntax:

mysql isPasswordSet <USER_NAME>

Example:

ssh adminAPI@10.122.210.25 mysql isPasswordSet cdraccess && echo “password is set“ || echo “NO password

generatePassword | GeneratePassword

Generates random password for mysql user.

The file with random password is created at /opt/vidyo/conf/mysql/<USER_NAME>.

Syntax:

mysql generatePassword <USER_NAME>

Example:

ssh adminAPI@10.122.210.25 mysql generatePassword cdracces

setPassword | SetPassword

Sets mysql user password (should be base64 encoded).

Example:

echo <USER_BASE64_PASSWD> | ssh adminAPI@10.122.210.25 mysql setPassword <USER_NAME>

VidyoInsights API

test | Test

Checks if VidyoInsights APIs are installed.

Example:

ssh adminAPI@10.122.210.25 VidyoInsightsAgent test

enable | Enable

Enables VidyoInsights. Basically this API sets VidyoInsights_RUN configuration parameter to true, so VidyoInsights service will start on the next system boot. To start the service immediately after enabling please call the start API.

Syntax:

VidyoInsights enable

Example:

ssh adminAPI@10.122.210.25 VidyoInsightsAgent enable

disable | Disable

Disables VidyoInsights. Basically this API sets VidyoInsights_RUN configuration parameter to false, so VidyoInsights service will not start on the next boot. To stop the service immediately after disabling please call the stop API.

Syntax:

VidyoInsights disable

Example:

ssh adminAPI@10.122.210.25 VidyoInsightsAgent disable

start | Start

Starts VidyoInsights service in case it is enabled.

Syntax:

VidyoInsights start

Example:

ssh adminAPI@10.122.210.25 VidyoInsightsAgent start

stop | Stop

Stops VidyoInsights service.

Syntax:

VidyoInsights stop

Example:

ssh adminAPI@10.122.210.25 VidyoInsightsAgent stop

restart | Restart

Restarts VidyoInsights service.

Syntax:

VidyoInsights restart

Example:

ssh adminAPI@10.122.210.25 VidyoInsightsAgent restart

setServerUrl | SetServerUrl

Sets VidyoInsights server URL used by agent to send collected metrics.

Syntax:

VidyoInsights setServerUrl <server_url>

Example:

ssh adminAPI@10.122.210.25 VidyoInsightsAgent setServerUrl emp.alpha.vidyo.com

setUserName | SetUserName

Sets user ID used by agent to authenticate on VidyoInsights.

Syntax:

VidyoInsights setUserName <user_name>

Example:

ssh adminAPI@10.122.210.25 VidyoInsightsAgent setUserName telegraf

setUserPassword | SetUserPassword

Sets user password used by agent to authenticate on VidyoInsights.

Example:

echo <USER_PASSWD> | ssh adminAPI@10.122.210.25 VidyoInsightsAgent setUserPassword