Agent Remoting

As of v1.0.5 the zrok Agent and controller support secure, opt-in remote control for creating shares and accesses through the central zrok API.

Enabling Agent Remoting in the zrok Controller

Create an identity for your zrok controller to use for interacting with remote agents:

$ zrok admin create identity agentremoting
zrok identity 'agentremoting' created with ziti id 'WEfGMIx-e4'

note

The indentity can be named anything; I chose agentremoting just for this example.

Next, you'll need to configure remoting in your controller config like this:

agent_controller:
  z_id:             WEfGMIx-e4
  identity_path:    /home/michael/.zrok/identities/agentremoting.json

Restart your controller with this configuration and the agent remoting endpoints will become available.

Enrolling an Agent

Enrolling an Agent in remoting requires an enabled environment. You can use the zrok agent enroll command from an enabled environment to enroll your agent:

$ zrok agent enroll

warning! proceeding will allow remote control of your zrok agent!

your agent will accept remote commands from:

https://api-v1.zrok.io

you should only proceed if you understand the implications of this action!

to proceed, type 'yes': yes

agent enrolled with token 'yC9atRbCOskz'

restart your zrok agent to enable remote control

When you restart your agent, you will notice the following message in the Agent's log:

[   0.001]    INFO zrok/agent.(*Agent).remoteAgent: listening for remote commands at 'yC9atRbCOskz'

The Agent Remoting API

note

See the zrok OpenAPI spec for complete details of /agent endpoints.

Create A Remote Share

note

The apiEndpoint http://localhost:18080 is a zrok controller in a local development environment. All of the credentials in this document are local to that instance and already invalid as of publication of this document. It's just an example.

You can call the /agent/share endpoint to create a share on a remote Agent through the API:

$ curl -H "X-TOKEN: ojF2fna5GKlt" -XPOST -H "Content-Type: application/zrok.v1+json" -d '{"envZId": "qDWmgIxne4", "shareMode": "public", "backendMode": "web", "target": "/home/michael/Repos/nf/zrok"}' http://localhost:18080/api/v1/agent/share | jq
{
  "frontendEndpoints": [
    "http://51bnatug7ua3.zrok.quigley.com:8080"
  ],
  "token": "51bnatug7ua3"
}

Query the Status of the Remote Agent

$ curl -H "X-TOKEN: ojF2fna5GKlt" -XPOST -H "Content-Type: application/zrok.v1+json" -d '{"envZId": "qDWmgIxne4"}' http://localhost:18080/api/v1/agent/status | jq
{
  "accesses": null,
  "shares": [
    {
      "backendEndpoint": "/home/michael/Repos/nf/zrok",
      "backendMode": "web",
      "frontendEndpoints": [
        "http://51bnatug7ua3.zrok.quigley.com:8080"
      ],
      "shareMode": "public",
      "token": "51bnatug7ua3"
    }
  ]
}

Remove the Remote Share

$ curl -H "X-TOKEN: ojF2fna5GKlt" -XPOST -H "Content-Type: application/zrok.v1+json" -d '{"envZId": "qDWmgIxne4", "token": "51bnatug7ua3"}' http://localhost:18080/api/v1/agent/unshare

$ curl -H "X-TOKEN: ojF2fna5GKlt" -XPOST -H "Content-Type: application/zrok.v1+json" -d '{"envZId": "qDWmgIxne4"}' http://localhost:18080/api/v1/agent/status | jq
{
  "accesses": null,
  "shares": null
}

Creating and Removing Private Access

The /agent/access and /agent/unaccess endpoints also exist and allow for creating and removing private access frontends remotely.

Unenrolling an Agent

The zrok agent unenroll command will remove all remote control access from an Agent in an environment:

$ zrok agent unenroll
SUCCESS: unenrolled agent from 'https://api-v1.zrok.io'
SUCCESS: removed agent-enrollment.json

Unenrolling an agent currently enrolled in remoting will result in (ignorable) agent errors. Restart your agent to resume unenrolled operation.