1# swarm init
2
3<!---MARKER_GEN_START-->
4Initialize a swarm
5
6### Options
7
8| Name | Type | Default | Description |
9|:--------------------------------------------|:--------------|:---------------|:-----------------------------------------------------------------------------------------------------------------------------|
10| [`--advertise-addr`](#advertise-addr) | `string` | | Advertised address (format: `<ip\|interface>[:port]`) |
11| [`--autolock`](#autolock) | | | Enable manager autolocking (requiring an unlock key to start a stopped manager) |
12| [`--availability`](#availability) | `string` | `active` | Availability of the node (`active`, `pause`, `drain`) |
13| `--cert-expiry` | `duration` | `2160h0m0s` | Validity period for node certificates (ns\|us\|ms\|s\|m\|h) |
14| [`--data-path-addr`](#data-path-addr) | `string` | | Address or interface to use for data path traffic (format: `<ip\|interface>`) |
15| [`--data-path-port`](#data-path-port) | `uint32` | `0` | Port number to use for data path traffic (1024 - 49151). If no value is set or is set to 0, the default port (4789) is used. |
16| [`--default-addr-pool`](#default-addr-pool) | `ipNetSlice` | | default address pool in CIDR format |
17| `--default-addr-pool-mask-length` | `uint32` | `24` | default address pool subnet mask length |
18| `--dispatcher-heartbeat` | `duration` | `5s` | Dispatcher heartbeat period (ns\|us\|ms\|s\|m\|h) |
19| [`--external-ca`](#external-ca) | `external-ca` | | Specifications of one or more certificate signing endpoints |
20| [`--force-new-cluster`](#force-new-cluster) | | | Force create a new cluster from current state |
21| [`--listen-addr`](#listen-addr) | `node-addr` | `0.0.0.0:2377` | Listen address (format: `<ip\|interface>[:port]`) |
22| [`--max-snapshots`](#max-snapshots) | `uint64` | `0` | Number of additional Raft snapshots to retain |
23| [`--snapshot-interval`](#snapshot-interval) | `uint64` | `10000` | Number of log entries between Raft snapshots |
24| `--task-history-limit` | `int64` | `5` | Task history retention limit |
25
26
27<!---MARKER_GEN_END-->
28
29## Description
30
31Initialize a swarm. The Docker Engine targeted by this command becomes a manager
32in the newly created single-node swarm.
33
34## Examples
35
36```console
37$ docker swarm init --advertise-addr 192.168.99.121
38
39Swarm initialized: current node (bvz81updecsj6wjz393c09vti) is now a manager.
40
41To add a worker to this swarm, run the following command:
42
43 docker swarm join --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx 172.17.0.2:2377
44
45To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
46```
47
48The `docker swarm init` command generates two random tokens: a worker token and
49a manager token. When you join a new node to the swarm, the node joins as a
50worker or manager node based upon the token you pass to [swarm
51join](swarm_join.md).
52
53After you create the swarm, you can display or rotate the token using
54[swarm join-token](swarm_join-token.md).
55
56### <a name="autolock"></a> Protect manager keys and data (--autolock)
57
58The `--autolock` flag enables automatic locking of managers with an encryption
59key. The private keys and data stored by all managers are protected by the
60encryption key printed in the output, and is inaccessible without it. Make sure
61to store this key securely, in order to reactivate a manager after it restarts.
62Pass the key to the `docker swarm unlock` command to reactivate the manager.
63You can disable autolock by running `docker swarm update --autolock=false`.
64After disabling it, the encryption key is no longer required to start the
65manager, and it will start up on its own without user intervention.
66
67### <a name=""></a> Configure node healthcheck frequency (--dispatcher-heartbeat)
68
69The `--dispatcher-heartbeat` flag sets the frequency at which nodes are told to
70report their health.
71
72### <a name="external-ca"></a> Use an external certificate authority (--external-ca)
73
74This flag sets up the swarm to use an external CA to issue node certificates.
75The value takes the form `protocol=X,url=Y`. The value for `protocol` specifies
76what protocol should be used to send signing requests to the external CA.
77Currently, the only supported value is `cfssl`. The URL specifies the endpoint
78where signing requests should be submitted.
79
80### <a name="force-new-cluster"></a> Force-restart node as a single-mode manager (--force-new-cluster)
81
82This flag forces an existing node that was part of a quorum that was lost to
83restart as a single-node Manager without losing its data.
84
85### <a name="listen-addr"></a> Specify interface for inbound control plane traffic (--listen-addr)
86
87The node listens for inbound swarm manager traffic on this address. The default
88is to listen on `0.0.0.0:2377`. It is also possible to specify a network
89interface to listen on that interface's address; for example `--listen-addr
90eth0:2377`.
91
92Specifying a port is optional. If the value is a bare IP address or interface
93name, the default port 2377 is used.
94
95### <a name="advertise-addr"></a> Specify interface for outbound control plane traffic (--advertise-addr)
96
97The `--advertise-addr` flag specifies the address that will be advertised to
98other members of the swarm for API access and overlay networking. If
99unspecified, Docker will check if the system has a single IP address, and use
100that IP address with the listening port (see `--listen-addr`). If the system
101has multiple IP addresses, `--advertise-addr` must be specified so that the
102correct address is chosen for inter-manager communication and overlay
103networking.
104
105It is also possible to specify a network interface to advertise that
106interface's address; for example `--advertise-addr eth0:2377`.
107
108Specifying a port is optional. If the value is a bare IP address or interface
109name, the default port 2377 is used.
110
111### <a name="data-path-addr"></a> Specify interface for data traffic (--data-path-addr)
112
113The `--data-path-addr` flag specifies the address that global scope network
114drivers will publish towards other nodes in order to reach the containers
115running on this node. Using this parameter you can separate the container's
116data traffic from the management traffic of the cluster.
117
118If unspecified, the IP address or interface of the advertise address is used.
119
120### <a name="data-path-port"></a> Configure port number for data traffic (--data-path-port)
121
122The `--data-path-port` flag allows you to configure the UDP port number to use
123for data path traffic. The provided port number must be within the 1024 - 49151
124range. If this flag isn't set, or if it's set to 0, the default port number
1254789 is used. The data path port can only be configured when initializing the
126swarm, and applies to all nodes that join the swarm. The following example
127initializes a new Swarm, and configures the data path port to UDP port 7777;
128
129```console
130$ docker swarm init --data-path-port=7777
131```
132
133After the swarm is initialized, use the `docker info` command to verify that
134the port is configured:
135
136```console
137$ docker info
138<...>
139ClusterID: 9vs5ygs0gguyyec4iqf2314c0
140Managers: 1
141Nodes: 1
142Data Path Port: 7777
143<...>
144```
145
146### <a name="default-addr-pool"></a> Specify default subnet pools (--default-addr-pool)
147
148The `--default-addr-pool` flag specifies default subnet pools for global scope
149networks. For example, to specify two address pools:
150
151```console
152$ docker swarm init \
153 --default-addr-pool 30.30.0.0/16 \
154 --default-addr-pool 40.40.0.0/16
155```
156
157Use the `--default-addr-pool-mask-length` flag to specify the default subnet
158pools mask length for the subnet pools.
159
160### <a name="max-snapshots"></a> Set limit for number of snapshots to keep (--max-snapshots)
161
162This flag sets the number of old Raft snapshots to retain in addition to the
163current Raft snapshots. By default, no old snapshots are retained. This option
164may be used for debugging, or to store old snapshots of the swarm state for
165disaster recovery purposes.
166
167### <a name="snapshot-interval"></a> Configure Raft snapshot log interval (--snapshot-interval)
168
169The `--snapshot-interval` flag specifies how many log entries to allow in
170between Raft snapshots. Setting this to a high number will trigger snapshots
171less frequently. Snapshots compact the Raft log and allow for more efficient
172transfer of the state to new managers. However, there is a performance cost to
173taking snapshots frequently.
174
175### <a name="availability"></a> Configure the availability of a manager (--availability)
176
177The `--availability` flag specifies the availability of the node at the time
178the node joins a master. Possible availability values are `active`, `pause`, or
179`drain`.
180
181This flag is useful in certain situations. For example, a cluster may want to
182have dedicated manager nodes that don't serve as worker nodes. You can do this
183by passing `--availability=drain` to `docker swarm init`.
184
185## Related commands
186
187* [swarm ca](swarm_ca.md)
188* [swarm join](swarm_join.md)
189* [swarm join-token](swarm_join-token.md)
190* [swarm leave](swarm_leave.md)
191* [swarm unlock](swarm_unlock.md)
192* [swarm unlock-key](swarm_unlock-key.md)
193* [swarm update](swarm_update.md)
View as plain text