1# swarm join-token
2
3<!---MARKER_GEN_START-->
4Manage join tokens
5
6### Options
7
8| Name | Type | Default | Description |
9|:----------------|:-----|:--------|:-------------------|
10| `-q`, `--quiet` | | | Only display token |
11| `--rotate` | | | Rotate join token |
12
13
14<!---MARKER_GEN_END-->
15
16## Description
17
18Join tokens are secrets that allow a node to join the swarm. There are two
19different join tokens available, one for the worker role and one for the manager
20role. You pass the token using the `--token` flag when you run
21[swarm join](swarm_join.md). Nodes use the join token only when they join the
22swarm.
23
24> **Note**
25>
26> This is a cluster management command, and must be executed on a swarm
27> manager node. To learn about managers and workers, refer to the
28> [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
29> documentation.
30
31## Examples
32
33You can view or rotate the join tokens using `swarm join-token`.
34
35As a convenience, you can pass `worker` or `manager` as an argument to
36`join-token` to print the full `docker swarm join` command to join a new node to
37the swarm:
38
39```console
40$ docker swarm join-token worker
41
42To add a worker to this swarm, run the following command:
43
44 docker swarm join \
45 --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx \
46 172.17.0.2:2377
47
48$ docker swarm join-token manager
49
50To add a manager to this swarm, run the following command:
51
52 docker swarm join \
53 --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2 \
54 172.17.0.2:2377
55```
56
57Use the `--rotate` flag to generate a new join token for the specified role:
58
59```console
60$ docker swarm join-token --rotate worker
61
62Successfully rotated worker join token.
63
64To add a worker to this swarm, run the following command:
65
66 docker swarm join \
67 --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-b30ljddcqhef9b9v4rs7mel7t \
68 172.17.0.2:2377
69```
70
71After using `--rotate`, only the new token will be valid for joining with the specified role.
72
73The `-q` (or `--quiet`) flag only prints the token:
74
75```console
76$ docker swarm join-token -q worker
77
78SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-b30ljddcqhef9b9v4rs7mel7t
79```
80
81### `--rotate`
82
83Because tokens allow new nodes to join the swarm, you should keep them secret.
84Be particularly careful with manager tokens since they allow new manager nodes
85to join the swarm. A rogue manager has the potential to disrupt the operation of
86your swarm.
87
88Rotate your swarm's join token if a token gets checked-in to version control,
89stolen, or a node is compromised. You may also want to periodically rotate the
90token to ensure any unknown token leaks do not allow a rogue node to join
91the swarm.
92
93To rotate the join token and print the newly generated token, run
94`docker swarm join-token --rotate` and pass the role: `manager` or `worker`.
95
96Rotating a join-token means that no new nodes will be able to join the swarm
97using the old token. Rotation does not affect existing nodes in the swarm
98because the join token is only used for authorizing new nodes joining the swarm.
99
100### `--quiet`
101
102Only print the token. Do not print a complete command for joining.
103
104## Related commands
105
106* [swarm ca](swarm_ca.md)
107* [swarm init](swarm_init.md)
108* [swarm join](swarm_join.md)
109* [swarm leave](swarm_leave.md)
110* [swarm unlock](swarm_unlock.md)
111* [swarm unlock-key](swarm_unlock-key.md)
112* [swarm update](swarm_update.md)
View as plain text