Transient Port Forwarding

This document explains how to manage transient port forwarding for your MikroTik routers using the provided API endpoints. This feature allows temporary port forwarding over the existing management tunnel, which is useful for accessing LAN devices behind a router that might not have a public IP address.

Retrieve Active Port Forwards

The /api/routers/{router_id}/transient-forwarding endpoint allows you to retrieve all active port forwards for the specified router.

Endpoint

GET /api/routers/{router_id}/transient-forwarding

Sample Response

[
  {
    "id": "12345678-1234-1234-1234-123456789012",
    "port": 49159,
    "revoked_early": false,
    "allow_only_cidr": "198.51.100.0/24",
    "authorized_at": null,
    "expires_at": "2024-06-22T04:33:29+00:00",
    "expired": false,
    "entry_point": "us-east1.mkcld.io",
    "dst_address": "192.168.88.43",
    "dst_port": 22,
    "time_to_expire": "1 hour from now"
  }
  // Additional data points...
]

Transient Port Forwarding Object

Retrieve Specific Port Forward

The /api/routers/{router_id}/transient-forwarding/{id} endpoint allows you to retrieve a specific port forward for the specified router.

Endpoint

GET /api/routers/{router_id}/transient-forwarding/{id}

Sample Response

{
  "id": "12345678-1234-1234-1234-123456789012",
  "port": 49159,
  "revoked_early": false,
  "allow_only_cidr": "198.51.100.0/24",
  "authorized_at": null,
  "expires_at": "2024-06-22T04:33:29+00:00",
  "expired": false,
  "entry_point": "us-east1.mkcld.io",
  "dst_address": "192.168.88.43",
  "dst_port": 22,
  "time_to_expire": "1 hour from now"
}

Create a Transient Port Forward

The /api/routers/{router_id}/transient-forwarding endpoint allows you to create a new transient port forward.

Endpoint

POST /api/routers/{router_id}/transient-forwarding

Creation Object

Sample Request

{
  "expire_after_minutes": 120,
  "dst_port": 22,
  "dst_address": "192.168.88.43",
  "allow_from": "198.51.100.0/24"
}

Sample Response

{
  "id": "9c56202d-c388-484d-ac9a-7677f24f1f18",
  "port": 49159,
  "revoked_early": false,
  "allow_only_cidr": "198.51.100.0/24",
  "authorized_at": null,
  "expires_at": "2024-06-22T04:33:29+00:00",
  "expired": false,
  "entry_point": "us-east1.mkcld.io",
  "dst_address": "192.168.88.43",
  "dst_port": 22,
  "time_to_expire": "2 hours from now"
}

Delete a Transient Port Forward

The /api/routers/{router_id}/transient-forwarding/{id} endpoint allows you to delete a specific transient port forward.

Endpoint

DELETE /api/routers/{router_id}/transient-forwarding/{id}

Response

A successful deletion returns a 204 No Content response.

Important Considerations

• Management Traffic Only: This feature is intended for management traffic, such as logging into a phone or printer. Heavy data transfer is not permitted.
• TCP Only: Only TCP traffic is supported.
• Duration: The maximum duration for a port forward is 1 day.
• Default Gateway Requirement: The device behind the MikroTik router to where traffic is being forwarded must use the MikroTik as its default gateway. If not, an extra NAT rule will need to be added programmatically. Look at the asynchronous API for guidance on adding a masquerade rule to overcome this limitation.

Transient Port Forward Life Cycle

The lifecycle of a transient port forward involves several key steps to ensure proper configuration, usage, and cleanup:

1. Creation: When a transient port forward is created, a job is dispatched to the router. The necessary configuration is added to the router to establish the port forward.
2. Usage: The port forward is active and can be used to access the specified device behind the router. The user must connect to the specified entry point and port, which forwards traffic to the destination address and port.
3. Expiration: Each transient port forward has a defined expiration time (maximum of 1 day). As the expiration time approaches, the time-to-expire property updates accordingly.
4. Revocation: If necessary, a transient port forward can be revoked early by issuing a delete request to the API endpoint. This will remove the port forward configuration from the router.
5. Automatic Cleanup: Upon expiration or revocation, a job is dispatched to the router to remove the port forward configuration. This ensures that no stale configurations remain on the router.

By following these steps and using the provided API endpoints, you can effectively manage the lifecycle of transient port forwards for your MikroTik routers.