github.com/kaisenlinux/docker.io@v0.0.0-20230510090727-ea55db55fac7/cli/docs/reference/commandline/swarm_ca.md (about)

     1  ---
     2  title: "swarm ca"
     3  description: "The swarm ca command description and usage"
     4  keywords: "swarm, ca"
     5  ---
     6  
     7  # swarm ca
     8  
     9  ```markdown
    10  Usage:  docker swarm ca [OPTIONS]
    11  
    12  Manage root CA
    13  
    14  Options:
    15        --ca-cert pem-file          Path to the PEM-formatted root CA certificate to use for the new cluster
    16        --ca-key pem-file           Path to the PEM-formatted root CA key to use for the new cluster
    17        --cert-expiry duration      Validity period for node certificates (ns|us|ms|s|m|h) (default 2160h0m0s)
    18    -d, --detach                    Exit immediately instead of waiting for the root rotation to converge
    19        --external-ca external-ca   Specifications of one or more certificate signing endpoints
    20        --help                      Print usage
    21    -q, --quiet                     Suppress progress output
    22        --rotate                    Rotate the swarm CA - if no certificate or key are provided, new ones will be generated
    23  ```
    24  
    25  ## Description
    26  
    27  View or rotate the current swarm CA certificate.
    28  
    29  > **Note**
    30  >
    31  > This is a cluster management command, and must be executed on a swarm
    32  > manager node. To learn about managers and workers, refer to the
    33  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
    34  > documentation.
    35  
    36  ## Examples
    37  
    38  Run the `docker swarm ca` command without any options to view the current root CA certificate
    39  in PEM format.
    40  
    41  ```console
    42  $ docker swarm ca
    43  
    44  -----BEGIN CERTIFICATE-----
    45  MIIBazCCARCgAwIBAgIUJPzo67QC7g8Ebg2ansjkZ8CbmaswCgYIKoZIzj0EAwIw
    46  EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAzMTcxMDAwWhcNMzcwNDI4MTcx
    47  MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH
    48  A0IABKL6/C0sihYEb935wVPRA8MqzPLn3jzou0OJRXHsCLcVExigrMdgmLCC+Va4
    49  +sJ+SLVO1eQbvLHH8uuDdF/QOU6jQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB
    50  Af8EBTADAQH/MB0GA1UdDgQWBBSfUy5bjUnBAx/B0GkOBKp91XvxzjAKBggqhkjO
    51  PQQDAgNJADBGAiEAnbvh0puOS5R/qvy1PMHY1iksYKh2acsGLtL/jAIvO4ACIQCi
    52  lIwQqLkJ48SQqCjG1DBTSBsHmMSRT+6mE2My+Z3GKA==
    53  -----END CERTIFICATE-----
    54  ```
    55  
    56  Pass the `--rotate` flag (and optionally a `--ca-cert`, along with a `--ca-key` or
    57  `--external-ca` parameter flag), in order to rotate the current swarm root CA.
    58  
    59  ```console
    60  $ docker swarm ca --rotate
    61  desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e
    62    rotated TLS certificates:  [=========================>                         ] 1/2 nodes
    63    rotated CA certificates:   [>                                                  ] 0/2 nodes
    64  ```
    65  
    66  Once the rotation os finished (all the progress bars have completed) the now-current
    67  CA certificate will be printed:
    68  
    69  ```console
    70  $ docker swarm ca --rotate
    71  desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e
    72    rotated TLS certificates:  [==================================================>] 2/2 nodes
    73    rotated CA certificates:   [==================================================>] 2/2 nodes
    74  -----BEGIN CERTIFICATE-----
    75  MIIBazCCARCgAwIBAgIUFynG04h5Rrl4lKyA4/E65tYKg8IwCgYIKoZIzj0EAwIw
    76  EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTE2MDAxMDAwWhcNMzcwNTExMDAx
    77  MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH
    78  A0IABC2DuNrIETP7C7lfiEPk39tWaaU0I2RumUP4fX4+3m+87j0DU0CsemUaaOG6
    79  +PxHhGu2VXQ4c9pctPHgf7vWeVajQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB
    80  Af8EBTADAQH/MB0GA1UdDgQWBBSEL02z6mCI3SmMDmITMr12qCRY2jAKBggqhkjO
    81  PQQDAgNJADBGAiEA263Eb52+825EeNQZM0AME+aoH1319Zp9/J5ijILW+6ACIQCg
    82  gyg5u9Iliel99l7SuMhNeLkrU7fXs+Of1nTyyM73ig==
    83  -----END CERTIFICATE-----
    84  ```
    85  
    86  ### <a name="rotate"></a> Root CA rotation (--rotate)
    87  
    88  Root CA Rotation is recommended if one or more of the swarm managers have been
    89  compromised, so that those managers can no longer connect to or be trusted by
    90  any other node in the cluster.
    91  
    92  Alternately, root CA rotation can be used to give control of the swarm CA
    93  to an external CA, or to take control back from an external CA.
    94  
    95  The `--rotate` flag does not require any parameters to do a rotation, but you can
    96  optionally specify a certificate and key, or a certificate and external CA URL,
    97  and those will be used instead of an automatically-generated certificate/key pair.
    98  
    99  Because the root CA key should be kept secret, if provided it will not be visible
   100  when viewing swarm any information via the CLI or API.
   101  
   102  The root CA rotation will not be completed until all registered nodes have
   103  rotated their TLS certificates.  If the rotation is not completing within a
   104  reasonable amount of time, try running
   105  `docker node ls --format '{{.ID}} {{.Hostname}} {{.Status}} {{.TLSStatus}}'` to
   106  see if any nodes are down or otherwise unable to rotate TLS certificates.
   107  
   108  
   109  ### <a name="detach"></a> Run root CA rotation in detached mode (--detach)
   110  
   111  Initiate the root CA rotation, but do not wait for the completion of or display the
   112  progress of the rotation.
   113  
   114  ## Related commands
   115  
   116  * [swarm init](swarm_init.md)
   117  * [swarm join](swarm_join.md)
   118  * [swarm join-token](swarm_join-token.md)
   119  * [swarm leave](swarm_leave.md)
   120  * [swarm unlock](swarm_unlock.md)
   121  * [swarm unlock-key](swarm_unlock-key.md)