API v2: 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. Read-write. Expensive to use. Port number used if no port range is defined. Uniqueness is required in the combination of attribute `port` with attributes `address` and `mask`.
`legacy_crypto`	boolean; default value `false`	If `protocol == rdp` \|\| `ssh` \|\| `http` \|\| `mysql` \|\| `telnet` \|\| `tn3270` \|\| `tn5250` \|\| `rdp` & `tls_enabled` == `true`	Enabling legacy cryptographic protocols and settings.
`protocol`	string{http, modbus, mysql, rdp, ssh, system, 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.
`pools_ids`	string-array		Read-only; hidden; expensive to use
`pools_names`	string-array		Read-only; hidden; expensive to use
`state`	string		Server’s discovery state: discovered, onboarded, quarantined or created (for manually created accounts). 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. Unique identifier of the user who performed the onboarding.
`onboarded_by_name`	string		Read-only. Expensive to use. Name of the user who performed the onboarding.
`quarantined_at`	datetime		Read-only. Expensive to use. Server quarantined at timestamp.
`quarantined_by_id`	string		Read-only. Expensive to use. Unique identifier of the user who performed the quarantine.
`quarantined_by_name`	string		Read-only. Expensive to use. Name of the user who performed the quarantine.
`scanner_id`	string		Read-only. Expensive to use. Unique identifier of a scanner used to discover this server.
`scanner_name`	string		Read-only. Expensive to use. Name of a scanner used to discover this server.
`rights`	string-array		Read-only; list of rights the subject has to this object.
`created_at`	datetime		Read-only. Timestamp of creation.
`modified_at`	datetime		Read-only. Timestamp of modification.
`builtin`	boolean		Read-only; Expensive to use; If `true`, the object is not editable.
`hidden`	boolean		Read-only; Expensive to use; If `true`, the object is 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.

tabularcolumns::: p{0.27linewidth} p{0.16linewidth} p{0.31linewidth} p{0.15linewidth}

`MySQLServerAttributes`¶
Attribute	Type	Required	Description
`mysql_tls_required`	boolean; default value `false`	If `protocol` == `mysql` & `tls_enabled` == `true`

`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 == rdp` \|\| `http` \|\| `mysql` \|\| `telnet` \|\| `tn3270` \|\| `tn5250`	Enabling the TLS protocol.
`tls_ca_certificate`	string	If `protocol == rdp` \|\| `http` \|\| `mysql` \|\| `telnet` \|\| `tn3270` \|\| `tn5250` & `tls_enabled` == `true`	TLS CA certificate. Value format: x509-certificate
`tls_certificate`	string	If `protocol == rdp` \|\| `http` \|\| `mysql` \|\| `telnet` \|\| `tn3270` \|\| `tn5250` & `tls_enabled` == `true`	TLS certificate. Value format: x509-certificate

Retrieve Available Attributes of the ServerModel¶

Request

Method	`GET`
Path	`/api/v2/objspec/server`

`ServerPoolModel`¶
Attribute	Type	Required	Description
`id`	number	yes	Read-only object Identifier.
`pool_id`	number	yes	Immutable. Uniqueness is required in the combination of attribute `pool_id` with attribute `server_id`.
`server_id`	number	yes	Immutable. Uniqueness is required in the combination of attribute `server_id` with attribute `pool_id`.
`created_at`	datetime		Read-only.
`modified_at`	datetime		Read-only.
`removed`	boolean		Read-only.

Retrieve Available Attributes of the ServerPoolModel¶

Request

Method	`GET`
Path	`/api/v2/objspec/pool_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" }

Adding a Server to the Pool¶

Request

Method	`POST`
Path	`/api/v2/pool/server`
Headers	`Content-Type: Application/json`
Body	`ServerPoolModel`

Example Request

POST /api/v2/pool/server

     { "pool_id": "122678819172646916",
"server_id": "123402678819172646914"}

Response

    { "result": "success",
"pool_server": {} }

Deleting a Server From a Pool¶

Request

Method	`DELETE`
Path	`/api/v2/pool/<pool_id>/server/<server_id>`

Deleting a Server¶

Request

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