---
title: "Initialize a new swarm"
method: POST
path: "/swarm/init"
tags: ["Swarm"]
---

# Initialize a new swarm

`POST /swarm/init`

## Request body

- object
  - `ListenAddr` string — Listen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.
  - `AdvertiseAddr` string — Externally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.
  - `DataPathAddr` string — Address or interface to use for data path traffic (format: `<ip|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used. The `DataPathAddr` 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 it is possible to separate the container data traffic from the management traffic of the cluster.
  - `DataPathPort` integer — DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.
  - `DefaultAddrPool` string[] — Default Address Pool specifies default subnet pools for global scope networks.
  - `ForceNewCluster` boolean — Force creation of a new swarm.
  - `SubnetSize` integer — SubnetSize specifies the subnet size of the networks created from the default subnet pool.
  - `Spec` SwarmSpec — User modifiable swarm configuration.
    - `Name` string — Name of the swarm.
    - `Labels` object — User-defined key/value metadata.
    - `Orchestration` object, nullable — Orchestration configuration.
      - `TaskHistoryRetentionLimit` integer — The number of historic tasks to keep per instance or node. If negative, never remove completed or failed tasks.
    - `Raft` object — Raft configuration.
      - `SnapshotInterval` integer — The number of log entries between snapshots.
      - `KeepOldSnapshots` integer — The number of snapshots to keep beyond the current snapshot.
      - `LogEntriesForSlowFollowers` integer — The number of log entries to keep around to sync up slow followers after a snapshot is created.
      - `ElectionTick` integer — The number of ticks that a follower will wait for a message from the leader before becoming a candidate and starting an election. `ElectionTick` must be greater than `HeartbeatTick`. A tick currently defaults to one second, so these translate directly to seconds currently, but this is NOT guaranteed.
      - `HeartbeatTick` integer — The number of ticks between heartbeats. Every HeartbeatTick ticks, the leader will send a heartbeat to the followers. A tick currently defaults to one second, so these translate directly to seconds currently, but this is NOT guaranteed.
    - `Dispatcher` object, nullable — Dispatcher configuration.
      - `HeartbeatPeriod` integer — The delay for an agent to send a heartbeat to the dispatcher.
    - `CAConfig` object, nullable — CA configuration.
      - `NodeCertExpiry` integer — The duration node certificates are issued for.
      - `ExternalCAs` object[] — Configuration for forwarding signing requests to an external certificate authority.
        - `Protocol` 'cfssl' — Protocol for communication with the external CA (currently only `cfssl` is supported).
        - `URL` string — URL where certificate signing requests should be sent.
        - `Options` object — An object with key/value pairs that are interpreted as protocol-specific options for the external CA driver.
        - `CACert` string — The root CA certificate (in PEM format) this external CA uses to issue TLS certificates (assumed to be to the current swarm root CA certificate if not provided).
      - `SigningCACert` string — The desired signing CA certificate for all swarm node TLS leaf certificates, in PEM format.
      - `SigningCAKey` string — The desired signing CA key for all swarm node TLS leaf certificates, in PEM format.
      - `ForceRotate` integer — An integer whose purpose is to force swarm to generate a new signing CA certificate and key, if none have been specified in `SigningCACert` and `SigningCAKey`
    - `EncryptionConfig` object — Parameters related to encryption-at-rest.
      - `AutoLockManagers` boolean — If set, generate a key and use it to lock data stored on the managers.
    - `TaskDefaults` object — Defaults for creating tasks in this cluster.
      - `LogDriver` object — The log driver to use for tasks created in the orchestrator if unspecified by a service. Updating this value only affects new tasks. Existing tasks continue to use their previously configured log driver until recreated.
        - `Name` string — The log driver to use as a default for new tasks.
        - `Options` object — Driver-specific options for the selected log driver, specified as key/value pairs.

## Response `200`

no error

- string — The node ID

## Other responses

- `400` — bad parameter
- `500` — server error
- `503` — node is already part of a swarm

---

[API](https://skmtc.net/moby/apis/docker-engine-api.md) · [All operations](https://skmtc.net/moby/apis/docker-engine-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/moby/docker-engine-api/versions/4752769870da/schema)