Varnish Controller


Private agents and routers is a concept that makes these components private to an organization in Varnish Controller. Agents and routers that are started with a so-called private token are bound to the organization but could also be shared with other organizations via a shared token.

A shared token is generated based on a private token. When a different organization takes use of the shared token, the organization also gains access to the private agents or routers that use the private token that the shared token references.

An agent that is started with a private token and has a VCLGroup deployed as root, cannot be shared. It is also not possible to deploy a VCLGroup as root onto a shared agent. This is to avoid collisions between usage of agents in a shared environment, since a root deployed agent cannot be used for deployment of any other VCLGroups.

Both organizations and system admin can create private tokens and share these with organizations.

In order to start an agent or router with a private token, we need to first generate a private token using either API, CLI or GUI.

Using the vcli it is a simple as the following example:

vcli pt add MyPrivateToken

The generated private-token (PRIVATE-<identifier>) is then used to start agents and routers. Multiple private tokens can be generated. Agents and routers can share the same token or use different ones. It is up to the user to decide. Note that adding a shared token to reference the private token, will give access to all the routers/agents that use the private token.

Use Cases

Some use cases of private tokens:

  • Share a set of agents/routers to different organizations as system admin.
  • Share private agents/routers by one organization to another organization.
  • Temporary share a set of agents/routers with another organization.



The figure above shows the following scenario:

  • Org1 has created a private token and started a couple of agents and routers.
  • Org1 has created a shared token based on the private token and shared this with org2.
  • Org2 has used the shared token to gain access to org1 agents and routers.
  • Several agents and routers have been started as “system” available (both organizations can use them).
  • Org2 has created a private token and started agents and routers with this token. No shared token has been created and org2 is the only one with access to these private agents and routers.

As an organization user, there is basically nothing to consider when deploying a VCLGroup when using private/shared tokens. Tags can be added to any of these agents/routers and the VCLGroup will be deployed to any of these based on the tags. Just as without tokens. The system will make sure it only deploys the VCLGroup to the components that the organization has access to.

Private Agents/Routers

An agent started with a private token will be shown as private for the system admin or organization that owns the private token that the agent has been started with. As long as there are no shared token for this private token, only the owner of the agent can use this agent to deploy VCLGroups to.

Same goes for routers. It will be shown as private for the owner of the router. It will only use deployments from the owner as long as it is not shared to other organizations. The router will only receive information for agents that are accessible by the organization.

Example output of the vcli from a system admin perspective:

$ vcli agent ls
| ID |  Name  |  Access Level   |  State   | Varnish Host  | Varnish Port | Varnish Version | Tags |
|  1 | agent3 | system          | Running  | |         8083 | plus-6.0.10r1   |      |
|  2 | agent2 | system          | Running  | |         8082 | plus-6.0.10r1   |      |
|  3 | agent6 | system          | Down     | |         8081 | plus-6.0.10r1   |      |
|  4 | agent4 | system          | ReadOnly | |         8084 | plus-6.0.10r1   |      |
|  6 | agent5 | private(system) | Down     | |         8081 | plus-6.0.10r1   |      |
|  7 | agent1 | private(org1)   | Running  | |         8081 | plus-6.0.10r1   |      |

The table output shows four agents started as system global agents, that any user/organization can take use of. Then there are two private agents. agent5 that is owned by the system (system admin). agent1 is owned by the organization org1.

Important Considerations

  • If a private token is deleted, it cannot be re-created. This means that the agents/routers that were using this private token, must be restarted with a new private token. Any shared token that was referencing the deleted private token will be deleted as well. Hence, all shared users will lose access to the agents/routers.

  • A shared token cannot be re-created. This means that deleting a shared token as an owner, will revoke access for the organizations using the shared token. This will lead to undeploy of the agents/routers associated with the shared token for the organizations. Access will not be granted until a new shared token has been generated and handed over to the organizations.

  • An agent or router that is started with a new private token, will be seen as a new agent or router by the Varnish Controller. Hence, changing the private token for an agent or router will result in a new agent/router. The agent and router is unique to the Varnish Controller based on the private token ID and the specified name. The private token ID is baked into the private token ID. The same goes for restaring an agent or router without a private-token. Then it will become a system available.

  • Names of agents/routers must be unique when started as system available (without private token).

  • Names of agents/routers must be unique when started with the same private token. Names can be the same if the private token differs between them.

  • Deleting a private token from the system will make the agents/routers using this fail to register to brainz. All deployments to these agents/routers will stop working. Be very careful when deleting private tokens from the system.

  • System admins cannot use shared tokens (they have full access already)

Starting a Private Agent/Router

  1. Generate a private token
$ vcli pt add MyToken
| ID |  Name   | Agents | Routers |                              Token                              |       Created       |       Updated       |  Organization  | Creator |
|  1 | MyToken |        |         | PRIVATE-GEAX2AMGW2RRKQZL3HNJVKGN6FOBBPUIGOMIOFTLOMVB6CPTDLVGSKI | 2022-09-06 13:39:52 | 2022-09-06 13:39:52 | [System Admin] | test(1) |
  1. Use the private token when starting the agent/router.
# Via command line flag:

# Or via environment variable

Sharing Access

When sharing access to a agent or router it will allow the organization of the shared token to take use of this agent or router as long as the shared token exists. As a shared token owner, the shared token can at any point be revoked (deleted). Once revoked, it must be generated again and the same token will not be possible to reproduce. Meaning that all users of a shared token must get the new token to once again gain access to the previously shared agents/routers.

A user of a shared token can also revoke their access, but as long as the same shared token exists, they can add it back to take use of it again. This means that a user who is using someone else’s shared token can remove it, but it will not be removed from the system. Only for the user that removed it. But if the shared token is removed by the owner of the shared token, it will be removed from the system and from all users that used it.

Multiple shared tokens can be generated for one private token. These can then be given to different organizations.

Example of creating a shared token based on a private token:

# Assuming we have a private token with ID 1
$ vclist add MyShared 1
| ID |   Name   | Agents | Routers |                             Token                             | Users |  Owner   | Private Token |       Created       |       Updated       |  Organization  | Creator |
|  1 | MyShared |        |         | SHARE-EEASANEAJXXBXBBE52XZFZNLF4I5GRXPTR7N27XY4JOA67QZ5R7NF4Y |     0 | [system] | (1)MyToken    | 2022-09-06 14:26:23 | 2022-09-06 14:26:23 | [System Admin] | test(1) |

The token SHARE-EEASANEAJXXBXBBE52XZFZNLF4I5GRXPTR7N27XY4JOA67QZ5R7NF4Y is the one to share with other organizations.

The receiver of this shared token, will take use of it (to gain access to the agents/routers shared via this token):

| ID |   Name   | Agents | Routers |                             Token                             | Users |  Owner   | Private Token |       Created       |       Updated       |
|  1 | MyShared |        |         | SHARE-EEASANEAJXXBXBBE52XZFZNLF4I5GRXPTR7N27XY4JOA67QZ5R7NF4Y |     1 | [system] | (1)MyToken    | 2022-09-06 14:26:23 | 2022-09-06 14:26:23 |

Access Levels

The access levels will appear differently depending on who is logged in to the system, they are individual between organizations. The access level is seen on the agent and router objects.

There are 3 types of access levels for agents/routers.

  • (1) System
  • (2) Shared
  • (3) Private

Listing private and shared tokens will reveal which routers/agents that are affected by the tokens. Also organizations that have access to the tokens will be listed.


By default, starting an agent or router without a private token, will make it fully available to all organizations. These are presented as system access levels. These are no different from earlier versions of Varnish Controller where all organizations can use these agents and routers.


A shared access level means that the agent or router is being shared to your organization by another organization (or system admin). The access to these can either be revoked by the user of them or the owner of them.


A private access level means that it’s private to the organization, it can still be shared to others, but the logged in user will see it as private if the agent or router is theirs.

Transfer Ownership

From version 6 of Varnish Controller, agents and routers can be transferred between organizations and back to the system. This is an operation that system administrators can perform in runtime. There is no need to restart the given component. It is however important to understand the implications. If there are deployed VCLGroups on the given agent/router, these might be undeployed if the deployed VCLGroup can no longer be deployed to the agent/router due to ownership change.

The transfer can be performed using a pre-created private token, or let the system generate a new private token for the target organization.

Transfer agents:

# With an existing private-token
$ vcli agent transfer -o <org_id> -p <private_token_id>
# Generate a new private token for the organization
$ vcli agent transfer -o <org_id
# Transfer from organization back to system wide
$ vcli agent transfer -o 0

Transfer routers:

# With an existing private-token
$ vcli router transfer -o <org_id> -p <private_token_id>
# Generate a new private token for the organization
$ vcli router transfer -o <org_id
# Transfer from organization back to system wide
$ vcli router transfer -o 0