Servers

Server is a definition of the IT infrastructure resource, which can be accessed over one of the specified protocols.

Data Structures

ServerModel

Attribute	Type	Required	Description
id	string	yes	Unique, read-only object identifier. Requires read right on object type server for GET requests, modify for PATCH requests, and delete for DELETE requests.
name	string	yes	Unique server’s name.
description	string	no	Object description.
blocked	boolean; default value false	yes
reason	string	if blocked == true
bind_ip	string		Required format: IP address or fudo:label: <ip_label_name> for labeled IP addresses.
address	string	yes	IP address. Uniqueness is required in the combination of attribute address with attributes mask, port_first and port_last
mask	number {from 0 to 128}	no	Uniqueness is required in the combination of attribute mask with attributes address, port_first and port_last.
port_first	number		Value-format: port. Uniqueness is required in the combination of attribute port_first with attributes address, mask and port_last.
port_last	number		Value-format: port. Uniqueness is required in the combination of attribute port_last with attributes address, mask and port_first.
port	number	yes	Value-format: port. Server port number if no port range. Read-write; Expensive to use.
legacy_crypto	boolean; default value false	If protocol == ssh || (protocol == http || mysql || pgsql || telnet || tn3270 || tn5250 || rdp || vnc & tls_enabled == true)	Enabling legacy cryptographic protocols and settings.
tunneled	boolean; default value false	yes
tunnel_key	string	If tunneled == true	SSH public key for tunneled connections. Value-format: ssh-public-key.
protocol	string {http, modbus, mysql, pgsql, rdp, ssh, tcp, tds, telnet, tn3270, tn5250, vnc}	yes	Immutable; case insensitive.
http	HTTPServerAttributes	If protocol == http	HTTP protocol properties.
mysql	MySQLServerAttributes	If protocol == mysql	MySQL protocol properties.
rdp	RDPServerAttributes	If protocol == rdp	RDP protocol properties.
tls	TLSServerAttributes	If tls_enabled == true	TLS protocol properties.
ssh_public_key	string	If protocol == ssh	SSH public key. Value-format: ssh-public-key.
last_login	datetime		Read-only; Expensive to use.
pools	object-array		Read-only; Expensive to use; JSON object array containing id and name of assigned pools.
pool_ids	string-array		Read-only; Hidden; Expensive to use.
pool_names	string-array		Read-only; Hidden; Expensive to use.
state	string {created, discovered, onboarded, quarantined}		Discovery state. Read-only; Expensive to use.
discovered_at	datetime		Read-only; Expensive to use. Server discovered at timestamp.
onboarded_at	datetime		Read-only; Expensive to use. Server onboarded at timestamp.
onboarded_by_id	string		Read-only; Expensive to use. User identifier who onboarded this server.
onboarded_by_name	string		Read-only; Expensive to use. User name who onboarded this server.
quarantined_at	datetime		Read-only; Expensive to use. Server quarantined at timestamp.
quarantined_by_id	string		Read-only; Expensive to use. User identifier who quarantined this server.
quarantined_by_name	string		Read-only; Expensive to use. User name who quarantined this server.
scanner_id	string		Read-only; Expensive to use. Scanner identifier.
scanner_name	string		Read-only; Expensive to use. Scanner name.
rights	string-array		Read-only. List of rights the subject has to this object.
created_at	datetime		Read-only.
modified_at	datetime		Read-only.
removed	boolean		Read-only.
builtin	boolean		Read-only; Expensive to use. Is object built-in? Built-in objects shouldn’t be editable.
hidden	boolean		Read-only; Expensive to use. Shall the object be hidden in UI?

HTTPServerAttributes

Attribute	Type	Required	Description
http_host	string	yes	HTTP host header value.
http_timeout	number {seconds}	yes	Period of inactivity, after which the user will have to authenticate again.
http_authentication	boolean; default value false	no
http_authentication _method	string {Asana, Azure, Facebook, HPE BladeSystem, HPE iLO, HTTP Authentication, LinkedIn, Salesforce, Twitter}; Default value null	If http_authentication == true	Case insensitive.
http_username_element	string	If http_authentication == true & http_authentication_method == null	Custom login page details.
http_press_enter	boolean; default value false	If http_authentication == true & http_authentication_method == null	The Press the enter key prior to password option.
http_password_element	string	If http_authentication == true & http_authentication_method == null	Custom login page details.
http_signon_realm	string	If http_authentication == true & http_authentication_method == null	Custom login page details.

MySQLServerAttributes

Attribute	Type	Required	Description
mysql_tls_required	boolean; default value false	If protocol == mysql & tls_enabled == true	Require TLS for MySQL connections.

RDPServerAttributes

Attribute	Type	Required	Description
rdp_hotseat	boolean; default value false	If protocol == rdp	The option to have the users informed that other users are connected to the server, they are trying to connect to.
rdp_nla_enabled	boolean; default value true	If protocol == rdp & tls_enabled == true
rdp_public_key	string	If protocol == rdp & tls_enabled == false	RDP public key. Value-format: public-key.

TLSServerAttributes

Attribute	Type	Required	Description
tls_enabled	boolean; default value true	If protocol == http || mysql || pgsql || telnet || tn3270 || tn5250 || rdp || vnc	Enabling the TLS protocol.
tls_ca_certificate	string	If protocol == http || mysql || pgsql || telnet || tn3270 || tn5250 || rdp || vnc & tls_enabled == true	TLS CA certificate. Value-format: x509-ca-certificate.
tls_certificate	string	If protocol == http || mysql || pgsql || telnet || tn3270 || tn5250 || rdp || vnc & tls_enabled == true	TLS certificate. Value-format: x509-certificate.

Retrieve Available Attributes of the ServerModel

Request

Method	GET
Path	/api/v2/objspec/server

To check allowed methods, available URL parameters and possible responses please refer to the API Overview section.

Refer to the Batch operations topic to create nested requests for operating on the Server objects.

Create a Server

Request

Method	POST
Path	/api/v2/server
Headers	Content-Type: Application/json
Body	ServerModel

Example Request

POST /api/v2/server

      {
"name": "my-1st-rdp-server",
"protocol": "rdp",
"address": "10.0.2.0",
"port": 3389,
"legacy_crypto": false
      }

Response

    { "result": "success",
"server": {
    "id": "41234678819172646916" }}

Get Servers List

Request

Method	GET
Path	/api/v2/server

Get a Server

Request

Method	GET
Path	/api/v2/server/<id>

Example Request

GET /api/v2/server/<id>

    {
"result": "success",
"server": {
    "id": "4602678819172646916",
    "name": "my-1st-rdp-server",
    "blocked": false,
    "address": "10.0.2.0",
    "mask": 32,
    "port": 3389,
    "protocol": "rdp",
    "legacy_crypto": false,
    "rdp_hotseat": false,
    "rdp_nla_enabled": true,
    "tls_enabled": true,
    "tls_use_ca_store": false,
    "created_at": "2022-10-27 01:43:39.688273-07",
    "modified_at": "2022-10-27 01:43:39.688273-07",
    "last_login": "-infinity"
}}

Modify a Server

Request

Method	PATCH
Path	/api/v2/server/<id>
Headers	Content-Type: Application/json
Body	ServerModel

Example Request: Enable Using CA Store for Server Verification

PATCH /api/v2/server/<id>

{"tls_use_ca_store": true}

Response

{ "result": "success" }

Deleting a Server

Request

Method	DELETE
Path	/api/v2/server/<id>