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

Parameter	Type	Required	Description
id	string	yes	Unique, read-only object Identifier
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
address	string	yes	IP address; expects unique mask and port
mask	number {from 0 to 128}	no	Expects unique address and port
port	number {from 1 to 65535}	yes	Expects unique address and mask
legacy_crypto	boolean; default value false	If protocol == rdp || ssh || http || telnet || tn3270 || tn5250 & 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
http	HTTPServerAttributes	If protocol == http	HTTP 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
created_at	datetime		Read-only
modified_at	datetime		Read-only
removed	boolean		Read-only
last_login	datetime		Read-only; expensive to use
pools	string-array		Read-only; expensive to use

HTTPServerAttributes

Parameter	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
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

RDPServerAttributes

Parameter	Type	Required	Description
rdp_hotseat	boolean; default value false	yes	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

TLSServerAttributes

Parameter	Type	Required	Description
tls_enabled	boolean; default value true	If protocol == rdp || http || telnet || tn3270 || tn5250	Enabling the TLS protocol
tls_certificate	string	If protocol == rdp || http || telnet || tn3270 || tn5250 & tls_enabled == true	TLS certificate
tls_use_ca_store	boolean; default value false	If protocol == rdp || http || telnet || tn3270 || tn5250 & tls_enabled == true	Enable using CA store for server verification

Request for retrieving available attributes of the ServerModel

Method	GET
Path	/api/v2/objspec/server

ServerPoolModel

Parameter	Type	Required	Description
id	number	yes	Read-only object Identifier
pool_id	number	yes	Immutable. Expects unique server_id
server_id	number	yes	Immutable. Expects unique pool_id
created_at	datetime		Read-only
modified_at	datetime		Read-only
removed	boolean		Read-only

Request for retrieving available attributes of the ServerPoolModel

Method	GET
Path	/api/v2/objspec/pool_server

ServerGrantAssignmentModel

Parameter	Type	Required	Description
id	string		Read-only, protected object Identifier
to_user_id	string	yes	Immutable. Expects unique for_server_id
for_server_id	string	yes	Immutable. Expects unique to_user_id
to_user_name	string		Read-only, expensive to use
for_server_name	string		Read-only, expensive to use
created_at	string		Read-only
modified_at	string		Read-only
removed	boolean		Read-only

Request for retrieving available attributes of the ServerGrantAssignmentModel

Method	GET
Path	/api/v2/objspec/server_grant

Allowed methods

GET	for reading data of an existing object; no request body is required
POST	for creating an object; requires a request body, specified in JSON format, that contains the values for properties of the object that is about to be created
PATCH	for modifying an existing object; requires a request body, specified in JSON format, that contains the values for properties of the object
DELETE	for removing an existing object; no request body is required

There is a list of URL parameters available for a specific method to be included within a path:

• fields - for including the object fields in the query,

• filter - narrows out the result with available additions:

  • in - include possible field values (separated with comma),
  • match - include a sequence of characters to be searched in field values,
  • eq - equal,
  • ne - not equal,
  • lt - less than,
  • le - less or equal,
  • gt - greater than,
  • ge - greater than or equal
  • blocked - filter blocked objects,
  • !blocked - filter unblocked objects,
  • isempty() - filter objects with empty values in specified fields, only applies to arrays (e.g., server.isnull()),

• order,

• offset,

• limit,

• debug - for showing statistics, database errors, etc,

• total_count,

• reveal - to see objects: active, removed, or all for both removed and un-removed.

An example of the request that shows a list of 10 users that have a role user with their id and name specified, sorted alphabetically by their names and shows a total count of users that match the given criteria: GET https://<fudo_address>/api/v2/user?fields=id,name&filter=role.eq(user)&order=name&limit=10&total_count

Possible responses

Code	Status
200	success	OK
201	success	CREATED
400	failure	BAD REQUEST; message examples: Unrecognized endpoint, Request body is not allowed for this endpoint
401	failure	UNAUTHORIZED
404	failure	BAD REQUEST; message example: Object not found

The next chapter describes procedures for creating separate requests.

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

Creating a server

Request

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

Example request

Sending POST https://10.0.0.0/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" }}

Retrieving servers list

Request

Method	GET
Path	/api/v2/server

Retrieving a server

Request

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

Example request

Sending GET https://10.0.0.0/api/v2/server/41234678819172646916

    {
"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"
}}

Modifying 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

Sending PATCH https://10.0.0.0/api/v2/server/41234678819172646916

{"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

Sending POST https://10.0.0.0/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>

Retrieving users allowed to manage servers

Request

Method	GET
Path	/api/v2/grant/server

Example request

Sending GET https://10.0.0.0/api/v2/grant/server

Response

    { "result": "success",
"server_grant": [
    {
        "for_server_id": "4602678819172646916",
        "to_user_id": "4602678819172646914",
        "created_at": "2022-10-27 01:51:15.839452-07",
        "modified_at": "2022-10-27 01:51:15.839452-07" }]}

Granting management privileges

Request

Method	POST
Path	/api/v2/grant/server
Body	{ to_user_id: 1234567890, for_server_id: 1234567891 }

Deleting a server

Request

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