docs/reference/commandline/swarm_init.md - external/github.com/docker/cli - Git at Google


            
            # swarm init


            <!---MARKER_GEN_START-->

            
            Initialize a swarm


            ### Options


            | Name                                              | Type          | Default        | Description                                                                                                                  |

            
            |:--------------------------------------------------|:--------------|:---------------|:-----------------------------------------------------------------------------------------------------------------------------|

            
            | [`--advertise-addr`](#advertise-addr)             | `string`      |                | Advertised address (format: `<ip\|interface>[:port]`)                                                                        |

            
            | [`--autolock`](#autolock)                         | `bool`        |                | Enable manager autolocking (requiring an unlock key to start a stopped manager)                                              |

            
            | [`--availability`](#availability)                 | `string`      | `active`       | Availability of the node (`active`, `pause`, `drain`)                                                                        |

            
            | `--cert-expiry`                                   | `duration`    | `2160h0m0s`    | Validity period for node certificates (ns\|us\|ms\|s\|m\|h)                                                                  |

            
            | [`--data-path-addr`](#data-path-addr)             | `string`      |                | Address or interface to use for data path traffic (format: `<ip\|interface>`)                                                |

            
            | [`--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. |

            
            | [`--default-addr-pool`](#default-addr-pool)       | `ipNetSlice`  |                | default address pool in CIDR format                                                                                          |

            
            | `--default-addr-pool-mask-length`                 | `uint32`      | `24`           | default address pool subnet mask length                                                                                      |

            
            | [`--dispatcher-heartbeat`](#dispatcher-heartbeat) | `duration`    | `5s`           | Dispatcher heartbeat period (ns\|us\|ms\|s\|m\|h)                                                                            |

            
            | [`--external-ca`](#external-ca)                   | `external-ca` |                | Specifications of one or more certificate signing endpoints                                                                  |

            
            | [`--force-new-cluster`](#force-new-cluster)       | `bool`        |                | Force create a new cluster from current state                                                                                |

            
            | [`--listen-addr`](#listen-addr)                   | `node-addr`   | `0.0.0.0:2377` | Listen address (format: `<ip\|interface>[:port]`)                                                                            |

            
            | [`--max-snapshots`](#max-snapshots)               | `uint64`      | `0`            | Number of additional Raft snapshots to retain                                                                                |

            
            | [`--snapshot-interval`](#snapshot-interval)       | `uint64`      | `10000`        | Number of log entries between Raft snapshots                                                                                 |

            
            | `--task-history-limit`                            | `int64`       | `5`            | Task history retention limit                                                                                                 |


            <!---MARKER_GEN_END-->


            ## Description


            Initialize a swarm. The Docker Engine targeted by this command becomes a manager

            
            in the newly created single-node swarm.


            ## Examples


            ```console

            
            $ docker swarm init --advertise-addr 192.168.99.121


            Swarm initialized: current node (bvz81updecsj6wjz393c09vti) is now a manager.


            To add a worker to this swarm, run the following command:


                docker swarm join --token SWMTKN-1-aabbccdd00112233aabbccdd00112233aabbccdd00112233aa-aabbccdd00112233... 172.17.0.2:2377


            To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.

            
            ```


            The `docker swarm init` command generates two random tokens: a worker token and

            
            a manager token. When you join a new node to the swarm, the node joins as a

            
            worker or manager node based upon the token you pass to [swarm

            
            join](swarm_join.md).


            After you create the swarm, you can display or rotate the token using

            
            [swarm join-token](swarm_join-token.md).


            ### <a name="autolock"></a> Protect manager keys and data (--autolock)


            The `--autolock` flag enables automatic locking of managers with an encryption

            
            key. The private keys and data stored by all managers are protected by the

            
            encryption key printed in the output, and is inaccessible without it. Make sure

            
            to store this key securely, in order to reactivate a manager after it restarts.

            
            Pass the key to the `docker swarm unlock` command to reactivate the manager.

            
            You can disable autolock by running `docker swarm update --autolock=false`.

            
            After disabling it, the encryption key is no longer required to start the

            
            manager, and it will start up on its own without user intervention.


            ### <a name="dispatcher-heartbeat"></a> Configure node healthcheck frequency (--dispatcher-heartbeat)


            The `--dispatcher-heartbeat` flag sets the frequency at which nodes are told to

            
            report their health.


            ### <a name="external-ca"></a> Use an external certificate authority (--external-ca)


            This flag sets up the swarm to use an external CA to issue node certificates.

            
            The value takes the form `protocol=X,url=Y`. The value for `protocol` specifies

            
            what protocol should be used to send signing requests to the external CA.

            
            Currently, the only supported value is `cfssl`. The URL specifies the endpoint

            
            where signing requests should be submitted.


            ### <a name="force-new-cluster"></a> Force-restart node as a single-mode manager (--force-new-cluster)


            This flag forces an existing node that was part of a quorum that was lost to

            
            restart as a single-node Manager without losing its data.


            ### <a name="listen-addr"></a> Specify interface for inbound control plane traffic (--listen-addr)


            The node listens for inbound swarm manager traffic on this address. The default

            
            is to listen on `0.0.0.0:2377`. It is also possible to specify a network

            
            interface to listen on that interface's address; for example `--listen-addr

            
            eth0:2377`.


            Specifying a port is optional. If the value is a bare IP address or interface

            
            name, the default port 2377 is used.


            ### <a name="advertise-addr"></a> Specify interface for outbound control plane traffic (--advertise-addr)


            The `--advertise-addr` flag specifies the address that will be advertised to

            
            other members of the swarm for API access and overlay networking. If

            
            unspecified, Docker will check if the system has a single IP address, and use

            
            that IP address with the listening port (see `--listen-addr`). If the system

            
            has multiple IP addresses, `--advertise-addr` must be specified so that the

            
            correct address is chosen for inter-manager communication and overlay

            
            networking.


            It is also possible to specify a network interface to advertise that

            
            interface's address; for example `--advertise-addr eth0:2377`.


            Specifying a port is optional. If the value is a bare IP address or interface

            
            name, the default port 2377 is used.


            ### <a name="data-path-addr"></a> Specify interface for data traffic (--data-path-addr)


            The `--data-path-addr` flag specifies the address that global scope network

            
            drivers will publish towards other nodes in order to reach the containers

            
            running on this node. Using this parameter you can separate the container's

            
            data traffic from the management traffic of the cluster.


            If unspecified, the IP address or interface of the advertise address is used.


            Setting `--data-path-addr` does not restrict which interfaces or source IP

            
            addresses the VXLAN socket is bound to. Similar to `--advertise-addr`, the

            
            purpose of this flag is to inform other members of the swarm about which

            
            address to use for control plane traffic. To restrict access to the VXLAN port

            
            of the node, use firewall rules.


            ### <a name="data-path-port"></a> Configure port number for data traffic (--data-path-port)


            The `--data-path-port` flag allows you to configure the UDP port number to use

            
            for data path traffic. The provided port number must be within the 1024 - 49151

            
            range. If this flag isn't set, or if it's set to 0, the default port number

            
            4789 is used. The data path port can only be configured when initializing the

            
            swarm, and applies to all nodes that join the swarm. The following example

            
            initializes a new Swarm, and configures the data path port to UDP port 7777;


            ```console

            
            $ docker swarm init --data-path-port=7777

            
            ```


            After the swarm is initialized, use the `docker info` command to verify that

            
            the port is configured:


            ```console

            
            $ docker info

            
            <...>

            
            ClusterID: 9vs5ygs0gguyyec4iqf2314c0

            
            Managers: 1

            
            Nodes: 1

            
            Data Path Port: 7777

            
            <...>

            
            ```


            ### <a name="default-addr-pool"></a> Specify default subnet pools (--default-addr-pool)


            The `--default-addr-pool` flag specifies default subnet pools for global scope

            
            networks. For example, to specify two address pools:


            ```console

            
            $ docker swarm init \

            
              --default-addr-pool 30.30.0.0/16 \

            
              --default-addr-pool 40.40.0.0/16

            
            ```


            Use the `--default-addr-pool-mask-length` flag to specify the default subnet

            
            pools mask length for the subnet pools.


            ### <a name="max-snapshots"></a> Set limit for number of snapshots to keep (--max-snapshots)


            This flag sets the number of old Raft snapshots to retain in addition to the

            
            current Raft snapshots. By default, no old snapshots are retained. This option

            
            may be used for debugging, or to store old snapshots of the swarm state for

            
            disaster recovery purposes.


            ### <a name="snapshot-interval"></a> Configure Raft snapshot log interval (--snapshot-interval)


            The `--snapshot-interval` flag specifies how many log entries to allow in

            
            between Raft snapshots. Setting this to a high number will trigger snapshots

            
            less frequently. Snapshots compact the Raft log and allow for more efficient

            
            transfer of the state to new managers. However, there is a performance cost to

            
            taking snapshots frequently.


            ### <a name="availability"></a> Configure the availability of a manager (--availability)


            The `--availability` flag specifies the availability of the node at the time

            
            the node joins a master. Possible availability values are `active`, `pause`, or

            
            `drain`.


            This flag is useful in certain situations. For example, a cluster may want to

            
            have dedicated manager nodes that don't serve as worker nodes. You can do this

            
            by passing `--availability=drain` to `docker swarm init`.


            ## Related commands


            * [swarm ca](swarm_ca.md)

            
            * [swarm join](swarm_join.md)

            
            * [swarm join-token](swarm_join-token.md)

            
            * [swarm leave](swarm_leave.md)

            
            * [swarm unlock](swarm_unlock.md)

            
            * [swarm unlock-key](swarm_unlock-key.md)

            
            * [swarm update](swarm_update.md)
	# swarm init

	<!---MARKER_GEN_START-->
	Initialize a swarm

	### Options

	\| Name \| Type \| Default \| Description \|
	\|:--------------------------------------------------\|:--------------\|:---------------\|:-----------------------------------------------------------------------------------------------------------------------------\|
	\| [`--advertise-addr`](#advertise-addr) \| `string` \| \| Advertised address (format: `<ip\\|interface>[:port]`) \|
	\| [`--autolock`](#autolock) \| `bool` \| \| Enable manager autolocking (requiring an unlock key to start a stopped manager) \|
	\| [`--availability`](#availability) \| `string` \| `active` \| Availability of the node (`active`, `pause`, `drain`) \|
	\| `--cert-expiry` \| `duration` \| `2160h0m0s` \| Validity period for node certificates (ns\\|us\\|ms\\|s\\|m\\|h) \|
	\| [`--data-path-addr`](#data-path-addr) \| `string` \| \| Address or interface to use for data path traffic (format: `<ip\\|interface>`) \|
	\| [`--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. \|
	\| [`--default-addr-pool`](#default-addr-pool) \| `ipNetSlice` \| \| default address pool in CIDR format \|
	\| `--default-addr-pool-mask-length` \| `uint32` \| `24` \| default address pool subnet mask length \|
	\| [`--dispatcher-heartbeat`](#dispatcher-heartbeat) \| `duration` \| `5s` \| Dispatcher heartbeat period (ns\\|us\\|ms\\|s\\|m\\|h) \|
	\| [`--external-ca`](#external-ca) \| `external-ca` \| \| Specifications of one or more certificate signing endpoints \|
	\| [`--force-new-cluster`](#force-new-cluster) \| `bool` \| \| Force create a new cluster from current state \|
	\| [`--listen-addr`](#listen-addr) \| `node-addr` \| `0.0.0.0:2377` \| Listen address (format: `<ip\\|interface>[:port]`) \|
	\| [`--max-snapshots`](#max-snapshots) \| `uint64` \| `0` \| Number of additional Raft snapshots to retain \|
	\| [`--snapshot-interval`](#snapshot-interval) \| `uint64` \| `10000` \| Number of log entries between Raft snapshots \|
	\| `--task-history-limit` \| `int64` \| `5` \| Task history retention limit \|


	<!---MARKER_GEN_END-->

	## Description

	Initialize a swarm. The Docker Engine targeted by this command becomes a manager
	in the newly created single-node swarm.

	## Examples

	```console
	$ docker swarm init --advertise-addr 192.168.99.121

	Swarm initialized: current node (bvz81updecsj6wjz393c09vti) is now a manager.

	To add a worker to this swarm, run the following command:

	docker swarm join --token SWMTKN-1-aabbccdd00112233aabbccdd00112233aabbccdd00112233aa-aabbccdd00112233... 172.17.0.2:2377

	To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
	```

	The `docker swarm init` command generates two random tokens: a worker token and
	a manager token. When you join a new node to the swarm, the node joins as a
	worker or manager node based upon the token you pass to [swarm
	join](swarm_join.md).

	After you create the swarm, you can display or rotate the token using
	[swarm join-token](swarm_join-token.md).

	### <a name="autolock"></a> Protect manager keys and data (--autolock)

	The `--autolock` flag enables automatic locking of managers with an encryption
	key. The private keys and data stored by all managers are protected by the
	encryption key printed in the output, and is inaccessible without it. Make sure
	to store this key securely, in order to reactivate a manager after it restarts.
	Pass the key to the `docker swarm unlock` command to reactivate the manager.
	You can disable autolock by running `docker swarm update --autolock=false`.
	After disabling it, the encryption key is no longer required to start the
	manager, and it will start up on its own without user intervention.

	### <a name="dispatcher-heartbeat"></a> Configure node healthcheck frequency (--dispatcher-heartbeat)

	The `--dispatcher-heartbeat` flag sets the frequency at which nodes are told to
	report their health.

	### <a name="external-ca"></a> Use an external certificate authority (--external-ca)

	This flag sets up the swarm to use an external CA to issue node certificates.
	The value takes the form `protocol=X,url=Y`. The value for `protocol` specifies
	what protocol should be used to send signing requests to the external CA.
	Currently, the only supported value is `cfssl`. The URL specifies the endpoint
	where signing requests should be submitted.

	### <a name="force-new-cluster"></a> Force-restart node as a single-mode manager (--force-new-cluster)

	This flag forces an existing node that was part of a quorum that was lost to
	restart as a single-node Manager without losing its data.

	### <a name="listen-addr"></a> Specify interface for inbound control plane traffic (--listen-addr)

	The node listens for inbound swarm manager traffic on this address. The default
	is to listen on `0.0.0.0:2377`. It is also possible to specify a network
	interface to listen on that interface's address; for example `--listen-addr
	eth0:2377`.

	Specifying a port is optional. If the value is a bare IP address or interface
	name, the default port 2377 is used.

	### <a name="advertise-addr"></a> Specify interface for outbound control plane traffic (--advertise-addr)

	The `--advertise-addr` flag specifies the address that will be advertised to
	other members of the swarm for API access and overlay networking. If
	unspecified, Docker will check if the system has a single IP address, and use
	that IP address with the listening port (see `--listen-addr`). If the system
	has multiple IP addresses, `--advertise-addr` must be specified so that the
	correct address is chosen for inter-manager communication and overlay
	networking.

	It is also possible to specify a network interface to advertise that
	interface's address; for example `--advertise-addr eth0:2377`.

	Specifying a port is optional. If the value is a bare IP address or interface
	name, the default port 2377 is used.

	### <a name="data-path-addr"></a> Specify interface for data traffic (--data-path-addr)

	The `--data-path-addr` flag specifies the address that global scope network
	drivers will publish towards other nodes in order to reach the containers
	running on this node. Using this parameter you can separate the container's
	data traffic from the management traffic of the cluster.

	If unspecified, the IP address or interface of the advertise address is used.

	Setting `--data-path-addr` does not restrict which interfaces or source IP
	addresses the VXLAN socket is bound to. Similar to `--advertise-addr`, the
	purpose of this flag is to inform other members of the swarm about which
	address to use for control plane traffic. To restrict access to the VXLAN port
	of the node, use firewall rules.

	### <a name="data-path-port"></a> Configure port number for data traffic (--data-path-port)

	The `--data-path-port` flag allows you to configure the UDP port number to use
	for data path traffic. The provided port number must be within the 1024 - 49151
	range. If this flag isn't set, or if it's set to 0, the default port number
	4789 is used. The data path port can only be configured when initializing the
	swarm, and applies to all nodes that join the swarm. The following example
	initializes a new Swarm, and configures the data path port to UDP port 7777;

	```console
	$ docker swarm init --data-path-port=7777
	```

	After the swarm is initialized, use the `docker info` command to verify that
	the port is configured:

	```console
	$ docker info
	<...>
	ClusterID: 9vs5ygs0gguyyec4iqf2314c0
	Managers: 1
	Nodes: 1
	Data Path Port: 7777
	<...>
	```

	### <a name="default-addr-pool"></a> Specify default subnet pools (--default-addr-pool)

	The `--default-addr-pool` flag specifies default subnet pools for global scope
	networks. For example, to specify two address pools:

	```console
	$ docker swarm init \
	--default-addr-pool 30.30.0.0/16 \
	--default-addr-pool 40.40.0.0/16
	```

	Use the `--default-addr-pool-mask-length` flag to specify the default subnet
	pools mask length for the subnet pools.

	### <a name="max-snapshots"></a> Set limit for number of snapshots to keep (--max-snapshots)

	This flag sets the number of old Raft snapshots to retain in addition to the
	current Raft snapshots. By default, no old snapshots are retained. This option
	may be used for debugging, or to store old snapshots of the swarm state for
	disaster recovery purposes.

	### <a name="snapshot-interval"></a> Configure Raft snapshot log interval (--snapshot-interval)

	The `--snapshot-interval` flag specifies how many log entries to allow in
	between Raft snapshots. Setting this to a high number will trigger snapshots
	less frequently. Snapshots compact the Raft log and allow for more efficient
	transfer of the state to new managers. However, there is a performance cost to
	taking snapshots frequently.

	### <a name="availability"></a> Configure the availability of a manager (--availability)

	The `--availability` flag specifies the availability of the node at the time
	the node joins a master. Possible availability values are `active`, `pause`, or
	`drain`.

	This flag is useful in certain situations. For example, a cluster may want to
	have dedicated manager nodes that don't serve as worker nodes. You can do this
	by passing `--availability=drain` to `docker swarm init`.

	## Related commands

	* [swarm ca](swarm_ca.md)
	* [swarm join](swarm_join.md)
	* [swarm join-token](swarm_join-token.md)
	* [swarm leave](swarm_leave.md)
	* [swarm unlock](swarm_unlock.md)
	* [swarm unlock-key](swarm_unlock-key.md)
	* [swarm update](swarm_update.md)