mirror of
https://github.com/openziti/zrok.git
synced 2025-07-11 03:35:03 +02:00
130 lines
4.0 KiB
Plaintext
130 lines
4.0 KiB
Plaintext
---
|
|
title: Agent Remoting
|
|
sidebar_label: Remoting
|
|
sidebar_position: 20
|
|
---
|
|
|
|
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:
|
|
|
|
```yaml
|
|
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](https://github.com/openziti/zrok/blob/main/specs/zrok.yml) 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. |