Skip to content

Using the macchina.io Remote Manager Provisioning API Endpoint

Jump to bottom
Günter Obiltschnig edited this page Aug 13, 2020 · 1 revision

Using the macchina.io Remote Manager Provisioning API Endpoint

The REST API of the macchina.io Remote Manager includes an endpoint for generating a configuration file for the device agent (WebTunnelAgent.properties).

The endpoint supports different parameters and modes of operation. It can generate a completely new device configuration with configuration properties such as port numbers specified in request parameters. It can also generate a configuration based on an existing device in the Remote Manager server's database.

Generating a Configuration for a New Device

In the simplest form, the endpoint can be invoked with at least one parameter specifying the ports to be forwarded.

GET /my-devices/api/provision?httpPort=80 HTTP/1.1
Host: reflector.my-devices.net
Authorization: Basic dXNlcjpzM2NyM3Q=

If authentication was successful, the server will send back a configuration file with device ID based on the device's MAC address (determined dynamically at runtime), with port 80 configured as HTTP port for forwarding. The device's domain will be the user's default domain.

Generating a Configuration for an Existing Device

It is also possible to retrieve the configuration for a device that has already been created on the Remote Manager server. The ID of the device must be given in the device parameter.

GET /my-devices/api/provision?device=38154b7a-033f-4be3-bac7-b1d14b327d60 HTTP/1.1
Host: reflector.my-devices.net
Authorization: Basic dXNlcjpzM2NyM3Q=

If authentication is successful and the user has access to that specific device, the returned configuration file will be based on the device properties for that specific device.

Request Parameters

The following request parameters can be specified with the request. The request can be send as a GET or POST request.

  • device: Specify the ID of the device. If a device with the given ID already exists, configuration parameters will be taken from there. The user must have access to that device.
  • domain: Specify the domain ID of the device. The user must have access to that specific domain. If not specified, defaults to the existing device's domain, or the user's default domain.
  • ports: Specify a comma-separated list of TCP ports to be forwarded. Ports specified via the httpPort, sshPort, vncPort and rdpPort parameters need not be included in that list. Defaults to the targetPorts device property.
  • httpPort: Specify the HTTP port number. Defaults to the httpPort device property if the device and property exists, or 0 (disabled).
  • sshPort: Specify the SSH port number. Defaults to the sshPort device property if the device and property exists, or 0 (disabled).
  • vncPort: Specify the VNC port number. Defaults to the vncPort device property if the device and property exists, or 0 (disabled).
  • rdpPort: Specify the RDP port number. Defaults to the rdpPort device property if the device and property exists, or 0 (disabled).
  • target: Specify the target host name. Defaults to the targetHost device property if the device exists, or 127.0.0.1.
  • password: Specify a device password to be included in the configuration file.

Authentication

The endpoint supports all authentication methods described in the macchina.io Remote Manager API documentation (HTTP Basic authentication, session-based authentication and token-based authentication).

Examples (curl)

Create a configuration file for a device with a MAC-based ID in the user's default domain, forwarding ports 80/HTTP and 22/SSH:

$ curl --user user:s3cr3t 'https://reflector.my-devices.net/my-devices/api?httpPort=8080&sshPort=22'

Create a configuration file for device 38154b7a-033f-4be3-bac7-b1d14b327d60, but overriding HTTP and SSH port numbers:

$ curl --user user:s3cr3t 'https://reflector.my-devices.net/my-devices/api?device=38154b7a-033f-4be3-bac7-b1d14b327d60&httpPort=8080&sshPort=22'
Clone this wiki locally