API v2: Listeners¶

Listener determines server connection mode (proxy, gateway, transparent, bastion) as well as its specifics.

Data structures¶

`ListenerModel`¶
Parameter	Type	Required	Description
id	string	yes	Read-only object Identifier
name	string	yes	Unique listener’s name
blocked	boolean; default value `false`	yes
reason	string	if `blocked` == `true`
announcement	string	no
protocol	string {http, modbus, mysql, rdp, ssh, system, tcp, tds, telnet, tn3270, tn5250, vnc}	yes	Immutable
ignore_case	boolean; default value `false`	If `protocol` == `vnc` \|\| `ssh`
legacy_crypto	boolean; default value `false`	If `protocol` == `ssh` \|\| `http` \|\| `rdp` & `tls_enabled` == `true`	Enabling legacy cryptographic protocols and settings
mode	string {bastion, gateway, proxy, transparent}	yes
listen_interface	string	If `mode` == `gateway` \|\| `transparent`	Network interface for user connections
listen_ip	string; default value `0.0.0.0`	If `mode` == `bastion` \|\| `proxy`	IP address for user connections
listen_port	number; value range from `1` to `60000`	If `mode` == `bastion` \|\| `proxy`	Port number for user connections
external_address	string	with `external_port`	Listener address to present in Access Gateway
external_port	number; value range from `1` to `65535`	with `external_address`	Listener port to present in Access Gateway
http_render	boolean; default value `true`	If `protocol` == `http`	Is graphical representation for HTTP(S) sessions enabled?
rdp	ListenerRDPAttributes	If `protocol` == `rdp`	RDP protocol properties
ssh	ListenerSSHAttributes	If `protocol` == `ssh`	SSH protocol properties
tls	ListenerTLSAttributes	If `protocol` == `http` \|\| `rdp`	TLS protocol properties
created_at	datetime		Read-only
modified_at	datetime		Read-only
removed	boolean		Read-only

`ListenerRDPAttributes`¶
Parameter	Type	Required	Description
rdp_private_key	string	If `protocol` == `rdp` & `tls_enabled` == `false`	RDP private key
rdp_public_key	string	If `protocol` == `rdp` & `tls_enabled` == `false`	RDP public key

`ListenerSSHAttributes`¶
Parameter	Type	Required	Description
ssh_private_key	string	yes	SSH private key
ssh_proxyjump	boolean; default value `false`	yes	Is SSH ProxyJump function enabled?
ssh_public_key	string	yes	Read-only SSH public key

`ListenerTLSAttributes`¶
Parameter	Type	Required	Description
tls_enabled	boolean; default value `true`	If `protocol` == `http` \|\| `rdp`	Enabling the TLS protocol
tls_private_key	string	If `protocol` == `http` \|\| `rdp` & `tls_enabled` == `true`	TLS private key
tls_certificate	string	If `protocol` == `http` \|\| `rdp` & `tls_enabled` == `true`	TLS certificate

Request for retrieving available attributes of the ListenerModel

Method	GET
Path	/api/v2/objspec/listener

`AccountSafeListenerAssignmentModel`¶
Parameter	Type	Required	Description
id	string	yes	Read-only object Identifier
account_id	string	yes	Immutable. Expects unique `safe_id` and `listener_id`
safe_id	string	yes	Immutable. Expects unique `account_id` and `listener_id`
listener_id	string	no	Immutable. Expects unique `account_id` and `safe_id`
valid_to	datetime
created_at	datetime		Read-only
modified_at	datetime		Read-only
removed	boolean		Read-only

Request for retrieving available attributes of the AccountSafeListenerAssignmentModel

Method	GET
Path	/api/v2/objspec/account_safe_listener

`ListenerGrantAssignmentModel`¶
Parameter	Type	Required	Description
id	string		Read-only, protected object Identifier
to_user_id	string	yes	Immutable. Expects unique `for_listener_id`
for_listener_id	string	yes	Immutable. Expects unique `to_user_id`
to_user_name	string		Read-only, expensive to use
for_listener_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 ListenerGrantAssignmentModel

Method	GET
Path	/api/v2/objspec/listener_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 Listener objects.

Retrieving listeners list¶

Request

Method	GET
Path	/api/v2/listener

Example request

Sending GET https://10.0.0.0/api/v2/listener

    "result": "success",
"listener": [
    {
        "id": "1234138875067073217",
        "name": "rdp_list_fd_10647",
        "protocol": "rdp",
        "mode": "bastion",
        "listen_ip": "0.0.0.0",
        "listen_port": 3388,
        "blocked": false,
        "created_at": "2022-10-15 14:52:30.980597+02",
        "modified_at": "2022-10-15 14:52:30.980597+02",
        "legacy_crypto": false,
        "tls_enabled": true,
        "tls_certificate": "-----BEGIN CERTIFICATE-----\nMIIE0DCCArigAwIBAgIUSGWBY/C...0w/BXGR\n-----END CERTIFICATE-----"
    },
    {
        "id": "1234138875067073219",
        "name": "telnet_proxy_3",
        "protocol": "telnet",
        "mode": "proxy",
        "listen_ip": "0.0.0.0",
        "listen_port": 2236,
        "blocked": false,
        "created_at": "2022-10-17 09:34:32.582169+02",
        "modified_at": "2022-10-17 09:34:32.582169+02"
    },
    {
        "id": "12348875067073220",
        "name": "mssql_proxy",
        "protocol": "tds",
        "mode": "proxy",
        "listen_ip": "0.0.0.0",
        "listen_port": 8874,
        "blocked": false,
        "created_at": "2022-10-17 10:50:53.209773+02",
        "modified_at": "2022-10-17 10:50:53.209773+02" }]

Creating a listener¶

Request

Method	POST
Path	/api/v2/listener
Headers	Content-Type: Application/JSON
Body	ListenerModel

Retrieving a listener¶

Request

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

Modifying a listener¶

Request

Method	PATCH
Path	/api/v2/listener/<id>
Headers	Content-Type: Application/JSON
Body	ListenerModel

Example request: Changing the listener’s address

Sending PATCH https://10.0.0.0/api/v2/listener/12345678819172646915

{ "listen_ip": "10.0.2.0" }

Response

{ "result": "success" }

Retrieving users allowed to manage given listener¶

Request

Method	GET
Path	/api/v2/grant/listener

Granting management privileges¶

Request

Method	POST
Path	/api/v2/grant/listener
Body	{ to_user_id: 1234567890, for_listener_id: 1234567891 }

Creating an account-safe-listener assignments¶

Request

Method	POST
Path	/api/v2/account/safe/listener
Headers	Content-Type: Application/JSON
Body	AccountSafeListenerAssignmentModel

Example request

Sending POST https://10.0.0.0/api/v2/account/safe/listener

    { "account_id": 1232678819172646919,
"safe_id": 1232678819172646913,
"listener_id": 1232678819172646914 }

Response

    { "result": "success",
"account_safe_listener": {} }

Deleting an account-safe-listener assignment¶

Request

Method	DELETE
Path	/api/v2/account/<account_id>/safe/<safe_id>/listener/<listener_id>

Deleting a listener¶

Request

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