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