Administering Tunnels with the API

1. OpenAPI Specification

The Transfer v2 OpenAPI Specification provides detailed information about tunnel management operations and an interactive interface for trying them out. Developers should use this as the primary reference. The following sections highlight noteworthy items for developers getting started with the API.

For detailed information on permissions granted to each endpoint role type, refer to the Globus Connect Server Streaming Admin Guide.

2. Tunnel Discovery

GET /v2/monitored/tunnels lists tunnels that use a stream access point on any subscribed endpoint where the caller has an appropriate role, regardless of who created them. You can narrow the list down with query string parameters.

Parameter Returns

filter[owner]=<identity id>

Tunnels created by that identity

filter[stream_access_point]=<id>

Tunnels that use that access point on either side

filter[listener]=<id>, filter[initiator]=<id>

Tunnels that use that access point on one specific side

filter[state]=ACTIVE

Tunnels in that state. Also accepts filter[state][in]=ACTIVE,ACTIVATING.

sort=created_time or sort=-created_time

Oldest first or newest first

GET /v2/tunnels/<tunnel id> and GET /v2/tunnels/<tunnel id>/events work for these tunnels, too.

3. Limitations on Displayed Results

Some details stay private to the tunnel’s owner and to the administrators of the side they belong to:

  • submission_id is shown only to the owner.

  • The listener IP address and port are shown only to the owner and to role holders on the listener side. The initiator IP address and port work the same way for the initiator side.

  • Event details are shown only to the owner and to people who hold a role on both sides. Everyone else sees "Details redacted". Event codes, times and descriptions are always shown.

Withheld values are null. Each tunnel’s meta.permissions shows whether you can update, stop or delete it.

4. Tunnel State Management

To stop a tunnel, issue a PATCH /v2/tunnels/<tunnel id> request with the body set to:

{
  "data": {
    "type": "Tunnel",
    "attributes": {
      "state": "STOPPING",
      "stopped_by_admin_message": "Stopped for scheduled DTN maintenance. Contact support@example.org."
    }
  }
}

The message is required when the stop request is made by someone other than the tunnel’s owner. It can be up to 256 characters, and is shown to the tunnel’s owner. To delete the tunnel once it reaches STOPPED, issue the request DELETE /v2/tunnels/<tunnel id>.

Deleting a tunnel also removes it from the owner’s view, and owners aren’t notified by email when an administrator stops or deletes their tunnel. To make sure the owner sees your message, stop the tunnel and leave it in place for a while before you delete it.

5. Changes to Query Parameters

If you have worked with the Transfer v2 resources for tunnels, please be aware of the following changes to query parameters.

  • Tunnel lists are paginated - GET /v2/tunnels used to return every tunnel at once. It now returns up to 1,000 tunnels per page (set the page size with page[limit]). Follow links.next to get the next page.

  • The tunnel event filters were renamed - Use filter[code]=<code> instead of code_name=<code>, and filter[is_error]=true|false instead of is_error=true|false. You can now combine the two filters.

  • Bookmark filtering and sorting - GET /v2/bookmarks now supports filter[name] (eq, ne, in, nin), filter[collection] and filter[id] (eq, in), and sort by name or id.

  • Invalid query parameters now return 400 - On these v2 list routes, an unrecognized parameter or an unsupported filter, operator or sort field gets a 400 error that lists every problem. These parameters used to be ignored silently.